The W3C issued some recipes for publishing your vocabulary that are a good complement to what is introduced here, as well as some more generic good practices for HTTP resources.
Vocabulary IRI
One of the rules of Linked Data is that things are named with IRI so that they can be looked up. Vocabularies are no exception, so make sure yours has an IRI you control. Your vocabulary should be accessible when looking up its IRI. There exists some recommendations to make sure the IRI you picked is cool:
- Keep it simple: short, memorable IRI are less error-prone
- Ensure stability (remember: cool IRI don’t change). To this end, consider applying for a w3id, a permanent IRI that redirects to your own, less stable namespace.
- Promote manageability by using versioned IRI. The W3C versioning approach is to ensure that the permanent IRI of a document always points to its latest version, and that each version has a specific IRI typically including its publication date or version number (referenced with the property
owl:versionInfo). Each version points to the previous one with anowl:priorVersionlink, and the latest version includes aowl:versionIRIproperty indicating its versioned IRI. The Dublin Core also provides versioning terms:terms:isReplacedByandterms:replacesto connect versions to one another,terms:isVersionOfto connect version to the permanent IRI.
We already chose a w3id identifier for the webcomic vocabulary, so all we need to do is versioning, which could look like the following:
@prefix terms: <http://purl.org/dc/terms/> .
@prefix owl: <http://www.w3.org/2002/07/owl#>.
<http://w3id.org/webcomic/ns> rdf:type owl:Ontology ;
owl:versionInfo "0.1.0" ;
owl:versionIRI <http://w3id.org/webcomic/2019/10/09/ns> ;
owl:priorVersion <http://w3id.org/webcomic/2019/10/08/ns> ;
terms:isReplacedBy <http://w3id.org/webcomic/2019/10/08/ns> .
Vocabulary metadata
We already described some meta that should be attached to a vocabulary when covering documentation and versioning. Apart from versioning info and a human-readable description, the Linked Open Vocabularies (a reference for vocabulary publication) recommends to add additional metadata to a vocabulary:
- A voaf:preferredNamespaceUri to reference the preferred IRI of the vocabulary, e.g. its permanent IRI as opposed to its versioned ones.
- A voaf:preferredNamespacePrefix to indicate a short, convenient way of referencing your vocabulary instead of its IRI.
- A terms:title and terms:description, which play the same role as rdfs:label and rdfs:comment
- In addition to the version information that we already mentionned (namely
owl:versionInfo), information about release dates with terms:issued for the initial release and terms:modified for the release of the current version - Relevant information for authoring and intellectual property:
- terms:creator and terms:contributor the creator(s) and contributor(s) of the vocabulary. All the better if they have webid that can be linked to!
- terms:rights or cc:license to describe the property rights or licence under which the vocabulary is available. Some widely used licenses are themselves identified by IRI, so you can directly reference them: creative commons, Apache 2.0, MIT…
- terms:publisher the publisher of the vocabulary, e.g. when creators and contributors work as part of an organization.
Putting all together, the metadata of the webcomic vocabulary could look something like that:
@prefix cc: <http://creativecommons.org/ns#> .
@prefix terms: <http://purl.org/dc/terms/> .
@prefix vann: <http://purl.org/vocab/vann/> .
<http://w3id.org/webcomic/ns> rdf:type owl:Ontology ;
# Ownership
cc:license <https://creativecommons.org/licenses/by/4.0/> ;
terms:creator <https://cleopatra.solidcommunity.net/profile/card#me> ;
terms:contributor <https://jcaesar.solidcommunity.net/profile/card#me> ;
terms:publisher <https://jcaesar.solidcommunity.net/profile/organizations/spqr.ttl#spqr>;
# Description
terms:title "Webcomic ontology" ;
terms:description """
The Webcomic ontology aims at describing webcomics, the things they talk about, the artists who make them and the people who read them.
""" ;
vann:preferredNamespacePrefix "webco" ;
vann:preferredNamespaceURI <http://w3id.org/webcomic/ns> ;
foaf:primaryTopic "Webcomics" ;
# Version
owl:versionIRI <http://w3id.org/webcomic/2019/10/09/ns> ;
owl:priorVersion <http://w3id.org/webcomic/2019/10/08/ns> ;
terms:isReplacedBy <http://w3id.org/webcomic/2019/10/08/ns>
owl:versionInfo "0.1.0" ;
terms:issued "52BC-01-01"
terms:modified "2019-10-09".
Content negotiation
Now that you have an IRI, a vocabulary and its metadata, and its documentation (that you might want to regenerate to include the metadata), you’re nearly there! The next step to publishing your vocabulary is setting up content negotiation, so that your server serves tailored content depending on who asks. The first usage for this is to show, under the same IRI, documentation to humans and RDF to programs. If you exported your vocabulary in different RDF syntaxes, you can also use content negotiation to serve these different flavours to clients who specifically ask for one. The content negotiation mechanism also explains why we left the file extension out of the IRI: the resource identified by the IRI is not necessarily a single document.
Content negotiation is based on HTTP Accept headers:
- On
Accept: X, X being a IANA MIME type for an RDF syntax (e.g.text/turtle,application/rdf+xml,application/trig, ` text/n3,application/ld+json`…), serve the appropriate document - On
Accept: Y, Y being a IANA MIME type for human-readable text (e.g.text/plain,application/xhtml+xml,text/html…), serve the documentation - If the client does not provide one, be sure to implement a default behavior, e.g. serving the Turtle document.
Here are specific instructions to set up content negotiation on some popular web servers:
You now have all the information you need to publish your vocabulary online in a friendly manner for people and programs who need to read it.