© 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
© 2012 IBM Corporation3
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
© 2012 IBM Corporation4
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
© 2012 IBM Corporation5
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#
© 2012 IBM Corporation6
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
© 2012 IBM Corporation7
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
© 2012 IBM Corporation8
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
© 2012 IBM Corporation9
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
© 2012 IBM Corporation11
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/
© 2012 IBM Corporation15
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