Technical Comments on Vocabulary

[Arthur Ryman <ryman@ca.ibm.com>]

I looked at the latest version of the vocabulary. It is in a Word 
document. I'd like to describe how vocabulary documents are produced at 
OSLC.

The OSLC workflow for vocabulary documents is to:
1. write them as Turtle files
2. run a small build script that generates an HTML page
3. embed the HTML in the wiki

Turtle is used as the source format because it is the easiest RDF format 
for humans to write and read. 

The build script does the following:
1. convert the Turtle to RDF/XML using the Jena SDK
2. convert the RDF/XML to HTML using an XSLT stylesheet

We now have a wiki. To demonstrate, I have created a wiki page for the 
vocabulary and embedde the HTML I previously generated. [1] I have 
uploaded all the source to our Documents repository (this is simpler than 
using SVN). The files are 
build.xml (ANT build script)
vocabulary-oasis.xsl (XSLT script)
promcode-vocabulary.ttl (Turtle source)
promcode-vocabulary.rdf (generated RDF/XML)
promcode-vocabulary.html (generated HTML - gets embedded in wiki page)

The benefit of generating the HTML from the Turtle is that formatting, 
cross references, and hyperlinks are added automatically. These are hard 
to maintain manually. The reason the wiki is used is that the RDF terms in 
the vocabulary should be available on the web. We should make the PROMCODE 
terms dereferenceable by setting up HTTP redirects to the wiki page. 

All OSLC vocabulary terms are dereferenceable. This means that if you want 
to know the meaning of an OSLC term, just put its URI in the browser, e.g. 
try  http://open-services.net/ns/core#ResourceShape

I recommend that we follow the OSLC process.

[1] https://wiki.oasis-open.org/oslc-promcode/PromcodeVocabulary

Regards, 
___________________________________________________________________________
Arthur Ryman, PhD

Chief Data Officer, Rational
Chief Architect, Portfolio & Strategy Management
Distinguished Engineer | Master Inventor | Academy of Technology

Toronto Lab | +1-905-413-3077 (office) | +1-416-939-5063 (mobile)