Title: Basic Principles for Managing an RDF Vocabulary

This version: http://www.w3.org/2001/sw/BestPractices/VM/principles/20050513


This document articulates some basic principles of good practice for managing an
RDF vocabulary.  By following these principles, an RDF vocabulary becomes
'usable' - new users learn quickly how to use the vocabulary, and a relationship
of trust is built between the user community and the vocabulary
developers/maintainers.  This promotes growth of a user community, which
generates more feedback for the developers/maintainers, leading to further
improvements in quality and usability.

This document focuses on those principles of good practice where a clear
recommendation can be made.  There are a number of open issues relating to the
management of RDF vocabularies, however these are outside the scope of this


An RDF vocabulary consists of a set of *resources* denoted by *URIs*.
Informally, these resources are known as the 'terms' of the vocabulary. The
resources will usually (but not necessarily) be of type rdf:Property,
rdfs:Class, owl:Class or skos:Concept.

An RDF vocabulary is created and maintained for the use of a community of people
(the 'user community') as a set of building blocks for creating RDF descriptions
of things in their domain of interest.  An RDF vocabulary usually implies a
shared conceptualisation, and thus the notion of an 'RDF vocabulary' is almost
identical to the notion of a 'web ontology' [ref???].  

Several of the most prominent RDF vocabularies currently in use (OWL, FOAF,
Dublin Core, SKOS Core) have emerged from a close collaboration between a
relatively small 'developer community' and a larger 'user community'.  The
prominence of these vocabularies may be attributed to their utility, but also to
the commitment made by those responsible for developing/maintaining the
vocabularies to forming, accomodating, serving, and working with, a community of

The goal of implementing the principles outlined in this document is to make an
RDF vocabulary 'usable'.  This could be restated as, managing an RDF vocabulary
with the user in mind. 

.... [some other stuff ???]  

Principles of Good Practice:

1. Naming

An RDF vocabulary consists of a set of resources denoted by URIs.  'Naming'
refers to the act of allocating URIs to resources [ref???].  

The developers/maintainers of an RDF vocabulary should inform the potential user
of the following:

 - The URI space from which resource names are drawn.

 - The ownership of this URI space.

 - Any commitments made by the owner(s) of the URI space to the persistence of
   URIs in that space.

 - Have the owner(s) of the URI space formally delegated responsibility for
   allocating URIs within that space to the vocabulary developers/maintainers?

 - Any rules used by the developers/maintainers for constructing URIs to be used
   as resource names.

E.g.s ....

2. Documentation

The developers/maintainers of an RDF vocabulary should provide natural-language
(i.e. human-readable) documentation about the vocabulary and its proper use.
The principle aim of this documentation is to help potential users *learn* how
to apply the vocabulary, and therefore to promote *consistency* in the way that
the vocabulary is applied.  Inconsistent usage reduces the value of a
vocabulary, because the meaning associated with the vocabulary becomes in
practice ambiguous.

As a bare minimum, a list of the terms should be published, with text
definitions.  It is recommended to publish detailed prose describing proper
usage patterns and scenarios, with examples.


3. Maintenance

An RDF vocabulary may be developed in private by a closed community, and then
published with no possibility for future change.  An RDF vocabulary may, on the
other hand, be developed in public by an open community, with the content of the
vocabulary being allowed to evolve indefinitely.  In any case, a potential user
needs to know under what circumstances the vocabulary (or parts of it) may
change, and what kinds of change may be expected.  

The key concept here is 'stability'.  When a potential user chooses a
vocabulary, they are making an investment of time/money/effort that depends to a
certain extent upon the stability of that vocabulary.  Therefore a potential
user needs to know exactly how stable a vocabulary is, in order to judge how
much to invest.  If a vocabulary is less than perfectly stable, the user needs
to know exactly what may change, how it may change, and of course to be informed
of changes when they do occur.

Therefore, the developers/maintainers of an RDF vocabulary should publish a
maintenance policy for that vocabulary.  The maintenance policy should
articulate whether or not change is allowed, and the way that change is managed.


The developers/maintainers should also provide some facility whereby users can
be informed of changes as and when they are made.


4. Versioning

Where a vocabulary is allowed to change, users developing systems based on that
vocabulary may prefer to work to a stationary, rather than moving, target.  To
support these users, the developers/maintainers of a vocabulary should:

 - Publish versions of the vocabulary, where a 'version' is a 'snapshot' of the
   vocabulary at a particular point in time.  

 - Allocated URIs to vocabulary versions, so that they may be referred to.

Where the resources that are the members of a vocabulary may evolve
independently, or be at differing levels of stability, the
developers/maintainers may also which to allocate URIs to historical versions of
a particular resource.


5. Publication

An RDF description of an RDF vocabulary should be published.  Potential users
should be clearly informed as to which is the 'authoritative' RDF description of
an RDF vocabulary.

Where the resources that are the members of an RDF vocabulary are denoted by
HTTP URIs, an HTTP GET request with the header field
'accept=application/rdf+xml' against that URI should return an RDF/XML
serialisation of an RDF graph that includes a description of the denoted