History   View   Links to this page Revision from: 2012 October 19 | 10:11 am
This is the revision from 2012 October 19 at 10:11 am   View the current live version of the article.

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

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…:

  1. Attach it and the RDF file to the wiki on the Uploads page
  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