1. © 2012 IBM Corporation Best Practices for Publishing RDF Vocabularies Arthur Ryman, 2012-01-10

2. © 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 VocabulariesBest Practice Recipes for Publishing RDF Vocabularies –These best practices are currently implemented at OSLC –We need to implement these at jazz.net

3. © 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 OSLChttp://open-services.net 2.http://jazz.net for Rationalhttp://jazz.net 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

4. © 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.nethttp://open-services.net  We need to do this for Rational vocabularies using http://jazz.nethttp://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 DefinitionsEnterprise Data Standards and Definitions

5. © 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/core# –http://open-services.net/ns/cm#http://open-services.net/ns/cm# –http://open-services.net/ns/qm#http://open-services.net/ns/qm#

6. © 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 URI Naming Guidance –OSLC Core core.rdfcore.rdf –OSLC CM cm.rdfcm.rdf –OSLC QM qm.rdfqm.rdf

7. © 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/XMLVocabulary.xsl –See OSLC Core URI Naming GuidanceOSLC Core URI Naming Guidance –The RDF/XML format must avoid abbreviations in order for the XSLT to produce good results

8. © 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 CoreOSLC Core –OSLC CMOSLC CM –OSLC QMOSLC 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/OslcCoreVocabularyhttp://open-services.net/core#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. © 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 #3Best Practice Recipes for Publishing RDF Vocabularies, Recipe #3 –This has been done at OSLC –We need to do this at jazz.net

10. © 2012 IBM Corporation10

11. © 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/Work item 99050 http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/

12. © 2012 IBM Corporation12

13. © 2012 IBM Corporation13

14. © 2012 IBM Corporation14

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