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 http://www.w3.org/TR/swbp-vocab-pub/ Best Practice Recipes for Publishing RDF Vocabularies Recipe #3.
RDF Content
Provide an RDF/XML document that defines the namespace and each URI in the vocabulary. For an example, see cm.rdf.
Each URI in the vocabulary should appear as the rdf:about attribute 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:seeAlso - a URI to a location in the wiki that defines the URI
- rdfs:isDefinedBy - the URI of the namespace
Do not use rdfs:domain as it has unwanted inferencing implications. Limit the use of rdfs:range.
HTML Content
** NOTE: ** as we are transitioning the wiki, we are working to update this. Continue to use old wiki until noted.
Since OSLC recommends hash URIs, the namespace should redirect to an wiki page that has a section names 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 vocabulary file, e.g. myvocabulary.rdf, by an XSLT transformation such as File:Vocabulary. You can use Ant to execute the XSLT transform. See File:build.xml for example. After you generate the HTML, e.g. myvocabulary.html, attach it and the RDF file to your vocabulary page, and include the HTML contents using the wiki INCLUDE command.
%INCLUDE{%ATTACHURL%/myvocabulary.html}%
See the OSLC Core Vocabulary for example. See Vocabulary index for a list of all published vocabularies (updated manually).
References
Category:Supporting Documents
