Documentation source override

(Back to URI documentation protocol)

Documentation override rules are similar to the RedirectMatch directive in Apache and are used in the case where the documentation for a URI is no longer available at its original location (i.e. via HTTP), but is available somewhere else. They may also be used when consulting a documentation mirror is preferred to using the URI with the HTTP protocol. Rules may be either private, global, or somewhere in between.

An override may be specified either as a mapping from URI to documentation URI or as a mapping from URI to replacement URI.

A documentation URI mapping rule transforms a URI to a URI for its documentation. A simple HTTP GET of the documentation URI is supposed to lead to the documentation. For example, a documentation rule{path}   ==>{path}

would imply that the documentation for a URI may be found at

A replacement URI mapping rule transforms a URI to another URI whose documentation is documentation for the URI. To obtain the original URI's documentation, apply the URI documentation protocol to the replacement URI. For example, a replacement rule{path}  ==>{path}

would imply that the documentation for is to be found by applying the documentation protocol to the URI (This might be suitable in cases where an entire web site has been mirrored.)

There may also be a "kill list" of URI patterns for which, were the documentation protocol to be used directly, one would get wrong answers (i.e. answers at variance to the way they were initially documented and subsequently used). This would probably only happen in the unlikely event a domain name were lost and then retaken by someone trying to phish or vandalize established URIs, and no suitable override to correct documentation was known.

There is currently no standard way to write override rules or kill lists, and no standard distribution method by which one might learn which ones should be used. So at the present time we can't tell you how to implement this step of the protocol. We have put forth two designs (Ruttenberg, Amsterdam 2006 and Rees, URI note draft 2007) but as the need is not felt there has been little discussion. Perhaps standardization will have to wait until disaster strikes.

See the URI Templates proposal for a possible syntax.


The override clause of the protocol will not have to be exercised if all participants in URI-based naming adhere to the [URI requirements] we list. DNS domain names will be kept indefinitely, servers will be kept running, and server administrators won't corrupt the documentation, ignore community input, or attempt to prevent mirroring.

But it seems wise to be prepared for the possibility that there may in the future be a failure of technique, administration, or motive at at least one important host. The users of a URI (both writers and readers of RDF) have a stake in what it means, so they have a stake in the URI's documentation. The override clause empowers users and insures their efforts against failures. The clause will have a reassurring social effect even if it is never exercised.

Other "location independent" protocols

The ARK and LSID protocols have adopted essentially the same approach as this one - the use of client-side mappings - to liberating the meaning of URIs from the vagaries of server location, so the idea of HTTP overrides is not new. What is new here is the idea that the same technique may be applied directly to unrestricted HTTP URIs, without appeal to a different syntax. This makes sense since no change in syntax or protocol can in itself make an infrastructure more reliable.

Other things you can do with it

We are proposing client-side URI rewrites as a hedge against the misfortune of URI documentation loss. Other uses for the same mechanism include finding documentation for legacy non-HTTP URIs (such as info:, tag:, or urn: schemes) and private documentation sets (or scripts) that enhance or filter the standard documentation in application- or site-specific ways. For example, a local database with bibliographic information for documents keyed on DOI could be adapted for use as a documentation set for info:hdl/ URIs used in an existing RDF source. Similarly, an HTTP to LSID gateway server could be used to provide LSID "metadata" for use as documentation for urn:lsid: URIs occurring in an RDF source. (Whether the LSID "metadata" tells you what is supposed to be denoted is another story! But that problem is shared with any open documentation approach.)

These techniques may serve as temporary workarounds to allow use of certain RDF sources, but we'd like to discourage them as methods that one would rely on in new work.