URI documentation

(Back to URIs, URI requirements, URI documentation protocol)

What should URI documentation look like, and what should it say?

Content
URI documentation isn't just a pile of information; it is a pile of information that is supposed to tell you what the referent of the URI is. This may seem obvious, but there are many examples of "metadata" that don't answer this question, as even users of RDF are not all in the habit of thinking about this.

Deciding what is worth naming, what should be named, what one needs to name for a particular application and for purposes of interoperability, and then expressing what you mean are much harder than they sound. Although not necessarily the best way to do everything, the most effective tactic we know of for promoting interoperation is to adopt a realist philosophy and to situate all entities within BFO and, or course, relate to ontologies that are themselves situated in BFO. (TBD: write more, or cite help sources)

Most desirable RDF properties in documentation:
 * rdfs:label - constitutes a highly abbreviated for of documentation
 * rdfs:comment - put the best prose you have here, with examples
 * rdf:type - bare minimum in the way of logically checkable assertions (TBD: what about classes/properties)
 * rdfs:seeAlso - link to sources that talk about either the URI or its referent.

rdf:type is enormously important as a statement of what the referent is supposed to be, and therefore what one might meaningfully say about it. It helps to safeguard against deficiencies in other parts of the documentation. As rdf:type is understood by reasoners, the presence of an rdf:type property can enable the automatic detection of inconsistencies both in the documentation and in other statements that use the URI.

Intended relations between this URI's referent and other things are very useful, and usually they are included in the documentation. Some of these relations might be to other things whose URIs are documented in the same ontology as the given URI, but equally important are relations to things outside the URI's ontology.

Curation status - sometimes URIs need to be used or reviewed while they are still under development, or are intentionally temporary. The status should be indicated somehow (TBD: how?).

We do not encourage combining documentation for multiple URIs into a single document, as some writers on Semantic Web technologies promote. See Hash_URIs.

RDF
RDF/XML is ugly but as close to universal as one gets, so is probably the preferred form (see page RDF regarding Turtle).

A human-readable form should be placed in the value of a rdfs:comment property. An rdfs:comment is supposed to describe the URI's referent, and such a description will document the URI by specifying what it should denote.

When there are other documents (besides this URI documentation) that bear on the meaning or use of the URI, it should be referenced using (??) rdfs:seeAlso. In this situation we aren't so picky about what the referent of the target URI of a seeAlso is, as any help is better than none.

(TDB: Talk about use of GRDDL to generate human-readable form)

Human-readable
In early stages of development it may be easier to write human-readable documentation in HTML or XHTML than to write RDF. Certainly any documentation is better than none. We would prefer to have the HTML placed in a separate document, linked via a seeAlso (or better, a more specific predicate), even if the RDF consists only of that seeAlso link. The two documents can then be improved independently.

Future formats
We do not expect RDF to be the last word in knowledge representation formats, so if you adopt this technology keep in the back of your mind that we may need an upgrade path.

Example
The documentation for http://purl.obofoundry.org/obo/OBI_0000225 found via the URI documentation protocol is a good example of orderly URI documentation.