OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-core message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: Fw: Guidance on using relative links in OASIS specifications

Hi Jim,Â

I'm talking about this with Paul and I need to give it careful thought. Going this way would require changing the Naming Directives (http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html) and changing well over a decade of established protocol. It would cause an abrupt change of convention in our repository and it might have ripple effects on other TCs publishing pipelines.Â

I will talk with Paul and with the TAB about the implications next week and see what others think. I'll aim to have an answer one way or another by then.Â



On Thu, Oct 18, 2018 at 11:37 AM Jim Amsden <jamsden@us.ibm.com> wrote:
Chet, any update on this? We're looking to finish up changes to the 7 part OSLC Core specs and they have quite a few relative links that will either be broken, or will require manual updates when published to the OASIS document repository.

I think the primary issue is that we can't use relative links because the file names get changed when the documents are published. For example, OSLC Core Vesion 3.0. Part 1: Overview Committee Specification revision 03 has published URL:


However, the actual file name in the GitHub repo is simply oslc-core.html.

Perhaps OASIS could consider changing the naming guidelines to not put variable information like version, revision number and document status in the published file name. This should be unnecessary because it is also included in the path and results in variable but redundant information. In the URL above, oslc-core-v3.0-csprd03-part1-overview.html is redundant with oslc-core/v3.0/csprd03/part1-overviewin the path. If this redundancy could be eliminated, then the file name would be unchanged when published, and all relative links would work fine.

If you would like to consider this, we could certainly change the names of the files to better reflect their title and part.

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data

----- Forwarded by Jim Amsden/Raleigh/IBM on 10/18/2018 11:28 AM -----

From: Â Â Â ÂJim Amsden/Raleigh/IBM
To: Â Â Â Â"Chet Ensign" <chet.ensign@oasis-open.org>
Cc: Â Â Â Â"OSLC Core TC (oslc-core@lists.oasis-open.org)" <oslc-core@lists.oasis-open.org>, oslc-domains@lists.oasis-open.org
Date: Â Â Â Â10/04/2018 11:44 AM
Subject: Â Â Â ÂGuidance on using relative links in OASIS specifications


The OASIS OSLC Specifications contain numerous URL references across the multi-part specifications. For example, the OSLC Core Specification has links to its vocabulary document. Many of these links include fragment identifiers to link to specific document sections.

Â<p class='conformance'>OSLC Servers MUST implement the OSLC Core vocabulary as defined in <a href="">http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/csprd03/part7-core-vocabulary/oslc-core-v3.0-csprd03-part7-core-vocabulary.html">OSLC Core Version 3.0. Part 7: Vocabulary</a>.</p>

The issue is what to use for stable URIs for these references. We cannot use the file names in the git repository because these do not correspond to the published files. As can be seen from the example above, the actual OASIS published file names correspond to OASIS file naming guidelines, and include document status and revision numbers in the file and path names. So these file names do not provide stable URIs. Each document does have a stable URI that references the latest published version. For example, http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/oslc-core-v3.0-part7-core-vocabulary.htmlis the URI for the latest version of the OSLC Core Vocabulary specification. If we use these to construct the relative URIs, then we have two problems. First, when developing the specifications, the relative links would not work between resources in the git repository. Second, when browsing a particular revision of an OSLC specification, a reader clicking on one of these links may be viewing a different version of the related specification, the latest version.

We could avoid direct href references in the HTML and always link indirectly through a bibliography entry. However, this would provide a poor user experience when viewing the HTML documents, and doesnât support fragment identifiers.

What is the OASIS recommended approach for dealing with relative links between documents?

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data


Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society

Primary: +1 973-996-2298
Mobile: +1 201-341-1393Â

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]