This wiki: The development wiki is a work area where Jazz development teams plan and discuss technical designs and operations for the projects at Jazz.net. Work items often link to documents here. You are welcome to browse, follow along, and participate. Participation is what Jazz.net is all about! But please keep in mind that information here is "as is", unsupported, and may be outdated or inaccurate. For information on released products, consult IBM Knowledge Center, support tech notes, and the Jazz.net library. See also the Jazz.net Terms of Use. Any documentation or reference material found in this wiki is not official product documentation, but it is primarily for the use of the development teams. For your end use, you should consult official product documentation (infocenters), IBM.com support artifacts (tech notes), and the jazz.net library as officially "stamped" resources.

Publishing RDF Vocabularies on jazz.net

Jazz tools should embody Linked Data design principles. This means that every resource hosted by a Jazz tool should have an RDF representation. The RDF representation will, in general, contain RDF vocabulary terms that are defined by external groups, such as W3C or OSLC, and the tool itself.

Any RDF term defined by a Jazz tool must be described in a vocabulary document. Since RDF vocabulary terms are themselves HTTP URIs, dereferencing the term should return the description of the term. The description should have both HTML and RDF representations. The recommended way to do this is to create a wiki page for each vocabulary, attach the HTML and RDF vocabulary documents to it, include the HTML in the wiki page body via an INCLUDE macro so it is integrated with the rest of the wiki and is searchable by the wike search engine, and finally, set up the web server to redirect requests for the vocabulary to the wiki. This last step must be done by the website administrators and is necessary since the vocabulary URI is different than the wiki page URI. See Best Practice Recipes for Publishing RDF Vocabularies, Recipe 3.

After you create your vocabulary document and publish it on the wiki, contact the Linked Data Review Board to have it approved and included in the list of HTTP redirects for jazz.net.

Similarly, any resource shapes that you intend to publish statically at jazz.net or dynamically through a Tracked Resource Set must also be reviewed by the Linked Data Review Board.

The following URI prefixes are used in this article:

Prefix	URI	Vocabulary
dcterms:	http://purl.org/dc/terms/	Dublin Core Metadata Initiative (DCMI) Metadata Terms
owl:	http://www.w3.org/2002/07/owl#	W3C Web Ontology Language (OWL)
rdf:	http://www.w3.org/1999/02/22-rdf-syntax-ns#	W3C Resource Description Framework (RDF)
rdfs:	http://www.w3.org/2000/01/rdf-schema#	W3C RDF Vocabulary Description Language (RDF Schema)
vs:	http://www.w3.org/2003/06/sw-vocab-status/ns#	Term-centric Semantic Web Vocabulary Annotations

Creating a Vocabulary Document

A vocabulary document should define all the classes, properties, and individual resources in the vocabulary. The terms should be defined using the RDF Schema vocabulary description language. The following properties should be included at a minimum:

Property	Description
rdf:type	Use rdfs:Class for classes, rdf:Property for properties. May be omitted for individual resources.
rdfs:label	A short text label for the term.
rdfs:comment	A brief description of the term.
rdfs:isDefinedBy	A link to the vocabulary that defines the term.
rdfs:seeAlso	Links to material that explains the term in more detail.
vs:term_status	The status of the term. One of the strings: "unstable", "testing", "stable", "archaic". May be omitted if the value is "stable".

A term definition may include additional properties defined by RDF Schema and OWL. However, these additional properties may have associated inference rule semantics so vocabulary designers should fully understand the implications. The RDFS terms that have associated inferences are:

Property	Description
rdfs:subClassOf	The subject class S is a subclass of the object class O. Given a triple (X rdf:type S) then infer the triple (X rdf:type O).
rdfs:subPropertyOf	The subject property S is a subproperty of the object property O. Given a triple (X S Y) then infer the triple (X O Y).
rdfs:domain	The subject property S has domain the object class O. Given a triple (X S Y) then infer the triple (X rdf:type O).
rdfs:range	The subject property S has range the object class O. Given a triple (X S Y) then infer the triple (Y rdf:type O).

The vocabulary itself should be described. This is done by giving it the OWL type owl:Ontology and including the following properties:

Property	Description
rdf:type	owl:Ontology to identify the vocabulary.
dcterms:title	The title of the vocabulary.
dcterms:description	A brief description of the vocabulary.
dcterms:source	A link to the authoritative RDF source of the vocabulary.
dcterms:license	A link to the license of the vocabulary. This should be http://jazz.net/ns/license.html.
dcterms:dateCopyrighted	The year, e.g. "2012", or first and last year, e.g. "2010, 2012", that the vocabulary was created or modified.
rdfs:label	A short label for the vocabulary.
rdfs:seeAlso	Links to material that explains the vocabulary in more detail.

License and Copyright Statement

The RDF source for the vocabulary must contain the dcterms:license and dcterms:dateCopyrighted properties. In addition, the HTML page for the vocabulary must contain the official IBM statement as defined on the LinkedDataReviewBoard wiki page. This text will be automatically generated if you use the XSLT stylesheet described below. It will insert the values specified by dcterms:license and dcterms:dateCopyrighted into the standard statement.

Setting Up a Vocabulary Wiki Page

See the wiki page Reporting Data Dictionary Vocabulary for an example. The following list summarizes the steps for setting up a vocabulary wiki page:

1. Create a source file that contains the vocabulary in RDF format, e.g. for Reporting Data Dictionary, the file is named dd-vocabulary.ttl which is in Turtle format. Turtle is the easiest format to read and write.
2. Transform the RDF to HTML, e.g. for the Reporting Data Dictionary, this is done in two steps. First, the Turtle file is converted using Jena to dd-vocabulary.rdf which contains non-abbreviated RDF/XML. Second, the RDF/XML is converted using XSLT to the HTML file dd-vocabulary.html. See below for an Ant script and XSLT file to automate this process.
3. Create a wiki page on the LinkedData wiki, e.g. ReportingDataDictionaryVocabulary, to host the HTML and RDF content.
4. Attach all files, e.g. dd-vobabulary.ttl, dd-vocabulary.rdf, and dd-vocabulary.html to the wiki page ReportingDataDictionaryVocabulary.
5. Edit the wiki page, e.g. ReportingDataDictionaryVocabulary, and insert the following include macro:

Generating HTML Vocabulary Documents from RDF Source

Linked Data principles imply that, in general, resources have mutliple representations, e.g. RDF and HTML. It is important that the alternate representations are consistent with each other. The best way to achieve consistency is to automatically generate all representations from a common source. A workable approach is to use an RDF format, such as Turtle or RDF/XML, as the source, and transform that to HTML. XSLT is a simple way to generate HTML from XML and that is the approach described here. XSLT processes XML as input. However, although all documents RDF/XML are XML, there are a large number of abbreviations which make it difficult to reliably process using XSLT. Fortunately, there is an easy solution to this difficulty. Both Turtle and abbreviated RDF/XML can easily be converted to non-abbreviated RDF/XML using Jena. The following list gives an overview of the processing steps for generating HTML:

1. Edit the vocabulary document using an RDF format, e.g. Turtle or abbreviated RDF/XML.
2. Convert the Turtle or abbreviated RDF/XML source to non-abbreviated RDF/XML using Jena.
3. Transform the non-abbreviated RDF/XML to HTML using XSLT.

The readability of the HTML page generated from the vocabulary using XSLT may be improved by defining namespace prefixes in the vocabulary document. Use the OSLC PrefixDefinition terms to define prefixes. For example, the following Turtle snippet defines a prefix for the Dublin Core Terms vocabulary:

<#dcterms> a oslc:PrefixDefinition ;
   oslc:prefix "dcterms" ;
   oslc:prefixBase <http://purl.org/dc/terms/> .

Alternatively, the XSLT script may be improved to include some predefined prefix definitions.

Instructions for Using the Ant and XSLT Scripts

Beware that the scripts here are not maintained, and may be out of date with respect to jazz.net styling, or current best practices in writing vocabularies!

Download the following common files into some convenient directory, e.g. C:\workspaces\vocabularies\stylesheets:

• build-common.xml: Common Ant build script to generate HTML
• vocabulary-common.xsl: Common XSLT script to transform RDF source to HTML.
• vocabulary-jazz.xsl: XSLT script to transform RDF source to HTML, using Jazz license terms
• vocabulary-oslc.xsl: XSLT script to transform RDF source to HTML, using OSLC license terms
• vocabulary-oasis.xsl: XSLT script to transform RDF source to HTML, using OASIS license terms

Create a working directory for your vocabularies. Create the following three subdirectories in the working directory: src, gen, and deploy. Put your RDF source in the src subdirectory. Download the following file to your working directory:

• build.xml: Ant build script to generate HTML

Edit build.xml to point to the directory location of the common files if you downloaded them to a directory other than C:\workspaces\vocabularies\stylesheets. Create Ant targets for your RDF source. Use ttl2html if your RDF source is Turtle. Use rdf2html if your RDF source is RDF/XML. Run build.xml. After running build.xml, the deploy subdirectory will contain RDF/XML, Turtle, and HTML versions of your vocabulary. Deploy these to the web. If your RDF source was RDF/XML, the gen subdirectory will contain its non-abbreviated version. Use the clean target to clean up the gen and deploy subdirectories.

Setting up HTTP Redirects

After you publish your vocabulary on the wiki, contact the Linked Data Review Board to set up the HTTP redirects. This will cause HTTP GET requests for your vocabulary to be redirected to your wiki page and attachments. The instructions for setting up HTTP redirects are described in:

• How_to_set_up_HTTP_redirects_on_jazz.doc: Instructions for Setting Up HTTP Redirects

Existing Vocabularies

For a list of existing vocabularies on this Linked Data Web, see LinkedDataWebVocabularies. For a list of vocabularies currently available at jazz.net, see http://jazz.net/ns.