History   View   Links to this page 2015 July 30 | 01:50 pm

Status: Approved guidance

This document gives guidance on how to define URIs for specifications and the expected usage of them.

Contents

Guidelines for Defining URIs

When there is a need to identify anything in OSLC, use a URI. Using URIs allows everything to be linked together.

There are exceptions to this rule. Some examples are:

  • when you need a boolean property value type, using URIs is overkill.
  • when there is a known and predefined identification scheme: enumerations, ISBN, etc.

Domain base URIs

The guidance includes defining a namespace URI structure that matches: http://open-services.net/ns/{domain}#

In some cases, there may be sub-domains within a domain. Then the pattern becomes: http://open-services.net/ns/{primary-domain}/{sub-domain}#

So for the CM 2.0 namespace URI, we’ll have: http://open-services.net/ns/cm#

and for the Core namespace URI, we’ll have: http://open-services.net/ns/core#

Additional guidance

Resource naming Simply append the name of the resource to the end of the domain URI.

For example, to define ChangeRequest in CM, it will become: http://open-services.net/ns/cm#ChangeRequest

Property URIs Append property name to domain URI.

For example, to add the serviceProvider property to Core, it will become: http://open-services.net/ns/core#serviceProvider

Usage Identifiers These are used within various services to identify in what scenarios the service (creation factory, query capabilities, delegated UI dialogs, etc) could be used by a provider.

An example for CM having a “My ToDo” list, http://open-services.net/ns/cm#toDo

Process for publishing meaningful content at URIs

These are rooted at open-services.net at http://open-services.net/ns using the approach outlined in Best Practice Recipes for Publishing RDF Vocabularies Recipe #3.

RDF Content

Provide a Turtle or an RDF/XML document that defines the namespace and each URI in the vocabulary. Turtle is preferred. For examples, see cm.rdf or config-vocab.ttl.

The vocabulary itself should be described with a source of type owl:Ontology, with the following information:

  • rdfs:label and dcterms:title - set both of these to the same value - a short string description of the vocabulary
  • dcterms:description - a longer description of the vocabulary
  • dcterms:source - the URI of the RDF source for this vocabulary (preferably in Turtle)
  • vann:preferredNamespacePrefix - the preferred prefix for this vocabulary, as a string without hash or colon
  • dcterms:license - optional: a string with any applicable license terms
  • dcterms:dateCopyrighted - optional: a string with a copyright date or range

Each term URI in the vocabulary should appear as the subject (or the rdf:about attribute in RDF/XML) on one of the following types of element:

  • rdfs:Class - for class URIs
  • rdf:Property - for property URIs
  • rdf:Description - for individual URIs

The OSLC guidelines recommend the use of hash URIs. The following information should be included:

  • rdfs:label - the fragment part of the hash URI
  • rdfs:comment - a short string description of the URI
  • rdfs:isDefinedBy - the URI of the namespace
  • rdfs:seeAlso - optional, may be a URI to a location in the wiki that defines the term
  • vs:term_status - optional, to mark deprecated terms with the value “archaic”. Note that once published, terms should not be removed from a vocabulary. There is no need to use the value “stable”, since that is the normal case. It is poor practice to use vs:term_status value of “unstable” or “testing” for terms in a vocabulary published at open-services.net or jazz.net.

Do not use rdfs:domain as it has unwanted inferencing implications. Limit the use of rdfs:range.

HTML Content

Since OSLC recommends hash URIs, the namespace should redirect to an wiki page that has a section named for each fragment, i.e. local name. This wiki page should then link to the location in the wiki citied by the rdfs:seeAlso property.

A suitable wiki page can be conveniently generated from the RDF/XML or Turtle vocabulary file, e.g. myvocabulary.rdf or myvocabulary.ttl, by an XSLT transformation such as File:Vocabulary v2.xsl. You can use ANT and Jena to convert the vocabulary file into non-abbreviated RDF/XML and to execute the XSLT transform. See File:build v2.xml and File:perfmon v2.rdf for example. For more information about what to put in your vocabulary file and how the ANT build file works refer to Publishing RDF Vocabularies on jazz.net.

After you generate the HTML, e.g. myvocabulary.html…:

  1. Attach it and the RDF file to the wiki on the File Uploads page. (The name of the page in each wiki is Special:Uploads)
  2. After you upload the file, copy the file name.
  3. In your Vocabulary page, include the html content with the following code: %%INCLUDE:myvocabulary.html%% (changing the file name accordingly). Be aware of the following restrictions:
    • The syntax is case-sensitive: INCLUDE must be all-caps, and the file name must match.
    • Unlike the old wiki, this syntax has two % marks on either side
    • There can be other content on the page, but the %%INCLUDE:...%% command must be by itself on its own line (it cannot be in a code block, table, list, etc)
    • You can only include .html files; for security purposes, some HTML tags are removed (head, style, script, etc) but I haven’t noticed any issues with the vocabulary documents
    • Also for security and performance reasons, the contents of the INCLUDEd file will not appear in the live preview.

See the OSLC Performance Monitoring Vocabulary for an example on the new wiki system, and the OSLC Core Vocabulary for an example on the legacy system.

See Vocabulary index for a list of all published vocabularies (updated manually).

References

Category:Supporting Documents

Categories