Re: Guidance on using relative links in OASIS specifications

On Thu, Oct 4, 2018 at 11:44 AM Jim Amsden <jamsden@us.ibm.com> wrote:

Chet,

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
919-525-6575

oslc-domains message