© 2012 ibm corporation best practices for publishing rdf vocabularies arthur ryman, 2012-01-10

© 2012 IBM Corporation

Best Practices for Publishing RDF VocabulariesArthur Ryman, 2012-01-10

© 2012 IBM Corporation2

Motivation

Rational is adopting Linked Data design principles– All resources should have dereferenceable HTTP URIs– When you dereference a URI you should be able to get RDF data

RDF data contains vocabulary terms which are themselves resources– Vocabulary terms should be dereferenceable HTTP URIs– When you dereference a vocabulary term URI you should be able to get RDF data

Vocabulary documents define the meaning of the terms in the vocabulary– Vocabulary documents in HTML format help human developers– Vocabulary documents in RDF format enable tools to improve the user experience

Rational should therefore publish RDF vocabularies in HTML and RDF formats

This presentation describes best practices for publishing RDF vocabularies– See Best Practice Recipes for Publishing RDF Vocabularies– These best practices are currently implemented at OSLC– We need to implement these at jazz.net


Outline of Recommended Best Practices

1. Define RDF vocabulary terms in a domain name over which we have administrative authority:1. http://open-services.net for OSLC2. http://jazz.net for Rational

2. Use hash URIs (aka URI-refences) for vocabulary terms

3. Create a vocabulary document in RDF format

4. Generate the vocabulary document in HTML format from the RDF format

5. Publish the HTML format in a wiki and attach the RDF format

6. Configure the Web server to redirect HTTP requests for vocabulary documents


Define RDF vocabulary terms in a domain name over which we have administrative authority

RDF vocabulary terms must be dereferenceable

We therefore need to deploy resources to the server that hosts these terms and configure it to perform HTTP redirects

We have done this for OSLC vocabularies using http://open-services.net

We need to do this for Rational vocabularies using http://jazz.net

Note that IBM has a registry for w3.ibm.com XML namespaces but it is not set up for public RDF vocabularies

– See Enterprise Data Standards and Definitions


Use hash URIs for vocabulary terms

W3C recommends using either hash or slash URIs for RDF– Terms are split into a namespace URI and a local name– The namespace URI ends in a hash or slash

Hash URIs are appropriate for vocabularies– The namespace URI identifies the vocabulary (aka ontology)

When you defererence a hash URI you get the whole vocabulary document

All OSLC vocabularies use hash URIs, e.g.– http://open-services.net/ns/core# – http://open-services.net/ns/cm# – http://open-services.net/ns/qm#


Create a vocabulary document in RDF format

The vocabulary should be formally documented in RDF– Use simple RDF Schema terms at a minimum, e.g

• rdf:Property, rdfs:Class, rdfs:label, rdfs:comment, rdfs:isDefinedBy– Use owl:Ontology to describe the vocabulary

The vocabulary should be made available as RDF/XML– Other formats such as Turtle may also be provided

See OSLC Core URI Naming Guidance, e.g.– OSLC Core core.rdf– OSLC CM cm.rdf– OSLC QM qm.rdf


Generate the vocabulary document in HTML format from the RDF format

The HTML and RDF representations must agree with each other

The easiest way to maintain consistency is to generate the HTML representation from the RDF representation

At OSLC, we developed an XSLT transform, Vocabulary.xsl, that generates a HTML compatible with TWiki from RDF/XML

– See OSLC Core URI Naming Guidance– The RDF/XML format must avoid abbreviations in order for the XSLT to produce good

results


Publish the HTML format in the wiki and attach the RDF format

We use wikis extensively to publish technical documentation

The easiest way to publish the HTML format of a vocabulary document is to create a wiki page for it and paste in the content generated from the RDF format, e.g.

– OSLC Core– OSLC CM– OSLC QM

The RDF format (or formats) should be attached to the wiki page

This procedure publishes the vocabulary but doesn’t link it with the vocabulary URI– e.g. HTML for http://open-services.net/core# is published at

http://open-services.net/bin/view/Main/OslcCoreVocabulary

To get the correct dereferencing behavior we need to set up HTTP redirects on the server


Configure the Web server to redirect HTTP requests for vocabulary documents

HTTP requests for a vocabulary must be redirected to the requested format

Redirection uses normal HTTP content negotiation as specified by the Accept header– Redirect application/rdf+xml to RDF/XML– Redirect text/html to HTML

Redirection can be implemented on the Apache web server using configuration files– See Best Practice Recipes for Publishing RDF Vocabularies, Recipe #3– This has been done at OSLC– We need to do this at jazz.net


Status

We are in reasonable shape at OSLC– Some specs, e.g. RM, have not generated an HTML format

We are starting from scratch at jazz.net– There are a large number of undocumented vocabulary terms

e.g. Work item 99050 contains 54 predicates in the namespace http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/


Call to action

Review all current Rational vocabularies

Decide if we should pick better namespaces and use hash URIs for any of these– what breaks if we change namespaces?

Create RDF vocabulary documents

Generate HTML pages

Publish content in the jazz.net wiki

Configure the jazz.net server to redirect vocabulary requests to the published content

© 2012 ibm corporation best practices for publishing rdf vocabularies arthur ryman, 2012-01-10

Documents