Basic Principles for Managing an RDF Vocabulary This version: http://www.w3.org/2001/sw/BestPractices/VM/principles/20050705 Abstract This document articulates some basic principles of good practice for managing an RDF vocabulary. Following these principles makes an RDF vocabulary "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. A number of issues related to the management of RDF vocabularies have yet to be resolved, but these are outside the scope of this document. Introduction An RDF vocabulary is 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 community of developers and a larger community of users. 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 users. 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 in such a way that it can easily be understood and deployed by users. .... [some other stuff ???] Principles of Good Practice 1. Name Terms using URI References 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. Provide readable 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. Egs. 3. Articulate your Maintenance Policies 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. Egs. The developers/maintainers should also provide some facility whereby users can be informed of changes as and when they are made. Egs. 4. Identify Versions 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. Egs. 5. Publish a Formal Schema 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 resource.