Introduction.

The documentation for each vocabulary on vocab.org is built from that vocabulary's RDF schema using a set of XSLT stylesheets and makefiles.

Toolchain Components

vocab-generate-makefile.xsl

An XSLT stylesheet that generates makefiles for building documentation of an RDF schema.

vocab-extract-term-rdf.xsl

An XSLT stylesheet that extracts the subset of RDF that applies to a single property or class in a schema.

pretty-xml.xsl

An XSLT stylesheet that formats an XML document as XHTML.

vocab-html-docs.xsl

An XSLT stylesheet that styles an RDF schema as XHTML.

cc-schema.rdfs

A copy of the creative commons RDF schema, used for generating XHTML descriptions of embedded licenses.

Using the Toolchain

1. Generate the makefile using vocab-generate-makefile.xsl. This stylesheet takes three parameters:

   schema (required)

   The short name of the schema (e.g. vann or bio)

   date (required)

   The date of the schema version (e.g. 20050401). This doesn't have to be a date but needs to act as a version identifier.

   toolchain-dir (optional)

   The directory of the toolchain (defaults to ../2004/03/toolchain/)

   Apply the stylesheet to the vocabulary RDF schema document. For example:

   xsltproc --param schema "'vann'" --param date "'20050401'" ../2004/03/toolchain/vocab-generate-makefile.xsl vann-vocab-20050401.rdf > Makefile-vann-20050401

   (Note how the parameters are enclosed in both types of quotes to ensure that they are passed as text and not interpreted as XPath references.)

   The result is a makefile that contains targets for all the files needed to completely document the vocabulary. I pipe the output to a new makefile for each version of the schema which means I can regenerate the documentation for any version at any time.

2. Run make with the generated makefile. This applies vocab-html-docs.xsl to the schema document once for each class or property and once for the HTML version of the schema. This stylesheet takes an optional parameter:

   term (optional)

   The URI of a vocabulary term (a property or class) to be extracted from the RDF schema. If this parameter is omitted, the entire schema is converted to HTML.

   The makefile generates RDF and HTML descriptions for each property and class in the schema. These files are named following the scheme: NNNN-term-TTTT-DDDD where NNNN is the vocabulary short name (e.g. bio), TTTT is the property or class name (e.g. date) and DDDD is the vocabulary date (e.g. 20050401), .rdf or .html is added as appropriate.

   The makefile also copies the term documents to the short versions of the file names (e.g. date.html) so that they can be returned when a user dereferences the term URI.

RDF Schema Constraints

The toolchain uses XSLT which operates at the syntactic level on the RDF schemas. This means that the RDF used in the schemas has to be authored in a consistent manner. The first child of the rdf:RDF needs to be an owl:Ontology element. This contains all the metadata about the vocabulary. The most important properties used here are:

dc:identifier

Must contain the URI of the RDF schema without the file extension. (e.g. http://purl.org/vocab/vann/vann-vocab-20050401)

dcterm:isVersionOf

Must reference the vocabulary namespace URI (e.g. http://purl.org/vocab/vann/)

dcterm:hasFormat

This is used to describe the HTML and RDF versions of the schema, for example:

  <dcterm:hasFormat>
    <rdf:Description rdf:about="http://purl.org/vocab/vann/vann-vocab-20050401.html">
      <dc:format>
        <dcterm:IMT>
          <rdf:value>text/html</rdf:value>
          <rdfs:label xml:lang="en">HTML</rdfs:label>
        </dcterm:IMT>
      </dc:format>
    </rdf:Description>
  </dcterm:hasFormat>
  <dcterm:hasFormat>
    <rdf:Description rdf:about="http://purl.org/vocab/vann/vann-vocab-20050401.rdf">
      <dc:format>
        <dcterm:IMT>
          <rdf:value>application/rdf+xml</rdf:value>
          <rdfs:label xml:lang="en">RDF</rdfs:label>
        </dcterm:IMT>
      </dc:format>
    </rdf:Description>
  </dcterm:hasFormat>