r26 - 2020-10-02 - 17:46:26 - Main.ndjcYou are here: TWiki >  LinkedData Web > LinkedDataReviewBoard > PublishingRdfVocabularies
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:
include.png

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:

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:

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.

Topic attachments
I Attachment Action Size Date Who Comment
Docdoc How_to_set_up_HTTP_redirects_on_jazz.doc manage 67.0 K 2015-03-02 - 14:30 UnknownUser Instructions for Setting Up HTTP Redirects
Xmlxml build-common.xml manage 4.9 K 2015-02-05 - 21:15 UnknownUser Ant build script common tasks to generate HTML
Xmlxml build.xml manage 1.5 K 2015-02-02 - 19:47 UnknownUser Ant build script to generate HTML
Pngpng include.png manage 71.4 K 2014-09-24 - 19:39 UnknownUser INCLUDE HTML Attachment
Xslxsl vocabulary-common.xsl manage 24.2 K 2020-09-22 - 15:35 UnknownUser Common XSLT script to transform vocabulary documents to HTML
Xslxsl vocabulary-jazz.xsl manage 19.9 K 2020-10-02 - 17:46 UnknownUser XSLT script to transform Jazz vocabulary documents to HTML
Xslxsl vocabulary-oasis.xsl manage 1.4 K 2015-02-02 - 23:00 UnknownUser XSLT script to transform OASIS vocabulary documents to HTML
Xslxsl vocabulary-oslc.xsl manage 1.0 K 2015-02-02 - 23:01 UnknownUser XSLT script to transform OSLC vocabulary documents to HTML
Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r26 < r25 < r24 < r23 < r22 | More topic actions
LinkedData.PublishingRdfVocabularies moved from Main.PublishingRdfVocabularies on 2014-02-21 - 20:49 by Main.ryman -
 
This site is powered by the TWiki collaboration platformCopyright © by IBM and non-IBM contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding TWiki? Send feedback
Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.