OSLC Core URI Naming Guidance

Currently being drafted

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

Guidelines for Defining URIs

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

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 an RDF/XML document that defines the namespace and each URI in the vocabulary. For an example, see ems.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

HTML Content

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 Vocabulary.xsl. You can use Ant to execute the XSLT transform. See 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.

References

• RFC3986 URI Syntax
• W3C Cool URIs for the Semantic Web
• Original Email thread proposal
• Dublin Core Terms