Skip to content

URIs in Specifications

Jump to bottom
Nick Crossley edited this page Jun 26, 2019 · 4 revisions

URIs in OSLC Specification Documents

URIs for specifications

OSLC specifications SHALL have URIs of the form:

https://open-services.net/spec/spec-short-name/revision-label/document-name.suffix

where:

URI part ReSpec conf variable Description
spec-short-name shortName Mandatory: the short name of the specification document, such as oslc-core.
revision-label revision Mandatory: a revision number or other label to distinguish a version of this specification.
document-name documentName The name for this document. This defaults to the value of the shortName conf variable. For parts of a multi-part specification, you MUST override this to specify or add a part name, for example part1-overview or oslc-core-part1-overview.
suffix N/A This is automatically generated as .html for the HTML links to a specification, and .pdf for the PDF links.

The above URIs SHALL redirect to the appropriate location - a URI in docs.oasis-open.org for existing work products published by the OASIS TCs, or to a GitHub repo branch or tag via a service that does content negotiation. For example, revision 3.1 of the OSLC Core Overview might have a URI https://open-services.net/spec/oslc-core/3.1/oslc-core-part1-overview.html, which redirects to https://raw.githack.com/oslc-op/oslc-specs/v3.1/core/oslc-core.html.

As special cases:

  • https://open-services.net/spec/spec-short-name/document-name.suffix SHALL redirect to the latest published version of that document
  • https://open-services.net/spec/spec-short-name SHALL redirect to the latest published HTML version of that specification (the first part for a multi-part specification)
  • https://open-services.net/spec/spec-short-name/document-name/draft SHALL redirect to the head of the GitHub master branch of that document
  • https://open-services.net/spec/spec-short-name/draft SHALL redirect to the head of the GitHub master branch of that specification (the first part for a multi-part specification)

By default, ReSpec will generate links to this version of a specification and the latest version of a specification using the above conventions. If a document sets the conf variables thisVersion and/or latestVersion, then those values will be used in place of the conventions. To link to a previous version (which might not follow these conventions), you have to set the conf variable previousVersion.

Use of URIs for links in a specification

  • All URIs cross-referencing documents, anchors, style sheets, images, etc., within a single work product MUST be relative to the current document
  • All URIs referencing other OSLC specifications, non-OSLC specifications, or other external documents MUST be absolute
  • URIs representing normative links to other specifications SHOULD in most cases reference a specific version of that specification
  • URIs representing informative references to other specifications or documents SHOULD in most cases reference the latest version of the target
  • OSLC specification documents SHOULD avoid external references to images, style sheets, and similar resources to be rendered within the specification

Main links

Clone this wiki locally