Best Practices for Publishing RDF Vocabularies Arthur Ryman, 2012-01-10

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

2. 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

3. Outline of Recommended Best Practices • Define RDF vocabulary terms in a domain name over which we have administrative authority: • http://open-services.net for OSLC • http://jazz.net for Rational • Use hash URIs (aka URI-refences) for vocabulary terms • Create a vocabulary document in RDF format • Generate the vocabulary document in HTML format from the RDF format • Publish the HTML format in a wiki and attach the RDF format • Configure the Web server to redirect HTTP requests for vocabulary documents

4. 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

5. 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#

6. 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

7. 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

8. 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

9. 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

11. 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/

15. 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