PublishingRdfVocabularies < LinkedData

%TOC%

---+ Publishing RDF Vocabularies on jazz.net

Jazz tools should embody [[http://www.w3.org/DesignIssues/LinkedData.html][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 [[http://www.w3.org/TR/swbp-vocab-pub/#recipe3][Best Practice Recipes for Publishing RDF Vocabularies, Recipe 3]]. 

After you create your vocabulary document and publish it on the wiki, contact the [[LinkedData.LinkedDataReviewBoard][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 [[http://www.w3.org/TR/rdf-schema/][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 
LinkedData.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 [[LinkedData.ReportingDataDictionaryVocabulary][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.
   1 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 [[https://jena.apache.org/][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.
   1 Create a wiki page on the [[https://jazz.net/wiki/bin/view/LinkedData/][LinkedData]] wiki, e.g. LinkedData.ReportingDataDictionaryVocabulary, to host the HTML and RDF content.
   1 Attach all files, e.g. [[https://jazz.net/wiki/pub/LinkedData/ReportingDataDictionaryVocabulary/dd-vocabulary.ttl][dd-vobabulary.ttl]], [[https://jazz.net/wiki/pub/LinkedData/ReportingDataDictionaryVocabulary/dd-vocabulary.rdf][dd-vocabulary.rdf]], and [[https://jazz.net/wiki/pub/LinkedData/ReportingDataDictionaryVocabulary/dd-vocabulary.html][dd-vocabulary.html]] to the wiki page LinkedData.ReportingDataDictionaryVocabulary.
   1 Edit the wiki page, e.g. LinkedData.ReportingDataDictionaryVocabulary, and insert the following include macro: 
<img width="957" alt="include.png" src="%ATTACHURLPATH%/include.png" height="571" />

---++ 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.
   1 Convert the Turtle or abbreviated RDF/XML source to non-abbreviated RDF/XML using Jena.
   1 Transform the non-abbreviated RDF/XML to HTML using XSLT.

The readability of the HTML page generated from the vocabulary by the attached XSLT script can 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:

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

---+++ Instructions for Using the Ant and XSLT Scripts
Download the following common files into some convenient directory, e.g. =C:\workspaces\vocabularies\stylesheets=:
   * [[%ATTACHURL%/build-common.xml][build-common.xml]]: Common Ant build script to generate HTML
   * [[%ATTACHURL%/vocabulary-common.xsl][vocabulary-common.xsl]]: Common XSLT script to transform RDF source to HTML.
   * [[%ATTACHURL%/vocabulary-jazz.xsl][vocabulary-jazz.xsl]]: XSLT script to transform RDF source to HTML, using Jazz license terms
   * [[%ATTACHURL%/vocabulary-oslc.xsl][vocabulary-oslc.xsl]]: XSLT script to transform RDF source to HTML, using OSLC license terms
   * [[%ATTACHURL%/vocabulary-oasis.xsl][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:
   * [[%ATTACHURL%/build.xml][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: 


   * [[%ATTACHURL%/How_to_set_up_HTTP_redirects_on_jazz.doc][How_to_set_up_HTTP_redirects_on_jazz.doc]]: Instructions for Setting Up HTTP Redirects

Attachments

Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
doc	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
xml	build-common.xml	manage	4.9 K	2015-02-05 - 21:15	UnknownUser	Ant build script common tasks to generate HTML
xml	build.xml	manage	1.5 K	2015-02-02 - 19:47	UnknownUser	Ant build script to generate HTML
png	include.png	manage	71.4 K	2014-09-24 - 19:39	UnknownUser	INCLUDE HTML Attachment
xsl	vocabulary-common.xsl	manage	24.2 K	2015-02-02 - 19:52	UnknownUser	Common XSLT script to transform vocabulary documents to HTML
xsl	vocabulary-jazz.xsl	manage	1.4 K	2015-02-02 - 19:50	UnknownUser	XSLT script to transform Jazz vocabulary documents to HTML
xsl	vocabulary-oasis.xsl	manage	1.4 K	2015-02-02 - 23:00	UnknownUser	XSLT script to transform OASIS vocabulary documents to HTML
xsl	vocabulary-oslc.xsl	manage	1.0 K	2015-02-02 - 23:01	UnknownUser	XSLT script to transform OSLC vocabulary documents to HTML

This topic: LinkedData > LinkedDataReviewBoard > PublishingRdfVocabularies

History: r23 - 2019-06-21 - 14:13:47 - Main.ndjc

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