First cut at Functional Requirements document

David J. Fiander (
Sun, 09 Jun 1996 22:47:52 -0400

Please get comments back to me by Wednesday morning (EDT), if you
want them incorporated before I ship something off to the IETF as
an internet draft Thursday afternoon.

- David


Functional Requirements for Specifying Document Revision Information in HTTP URLs


Before attempting to develop a convention for recording document version information in HTTP URLs, we must decide on the functional requirements that such a notation must, and must not, satisfy. Such a requirements analysis will allow the working group to quickly elminate those proposed notations that clearly fail to satisfy the requirements, and discuss the relative merits of the (hopefully several) contenders left in the light of a common framework.

The requirements listed in this document were condensed from the discussions held on the WWW Versioning Working Group.


Before starting in to the development of the requirements of any notation for embedding version information in URLs, the first question must be, "Is there a requirement that we be able to do so?" While the research group at NTT expressed some concern at the group's assumption that such a capability was necessary, the general concensus has been that the ability to embed hypertextual links to historical versions of documents is valuable.

Given that we want to be able to link to historical revisions of a document, there are two routes open to us: extend HTML to provide a way to store the information, perhaps as a new attribute for the HTML A tag; or embed such information in the URL itself. While the former method is conceptually more in keeping with the SGML way of doing things, it does have the drawback that existing Web clients will be unable to access the information in any meaningful way. Thus, we are limited to embedding version control information in the HTTP URL itself.

Requirements and Anti-Requirements

As well as listing the requirements that any notation must satisfy, it's useful to provide a list of anti-requirements. Anti-requirements describe functionality that the notation is explicity not required to support or, more strongly, is required to not support.

The version information is opaque to the client.
Because the notation will be required to operate in the version control environment prefered by the website maintainer, it must be able to properly contain arbitrary strings, which may be used by the VCS as version identifiers. While the version information will be explicable to the human operator, and perhaps to special-purpose clients, in the general case, we must assume that the client treats the URL as a black box.
It is not necessary to be able to decompose a URL into its consitutent resource URL and version identifier.
URLs have been defined as "magic cookies" that HTTP servers use to identify resources. Clients cannot, in general, decode a URL to determine how a server would interpret it.
Given a resource URL and a version identifier, version-aware clients must be able to construct a URL.
While existing URLs cannot be decomposed, the ability to construct a URL is essential for version-aware clients. This requirement parallels the ability of clients to submit queries against a page.
Any new notation must not cause problems for existing pages.
Roughly, this means that the notation cannot cause a version-aware server to interpret a pre-existing URL in a new way. For example, stating that version information is appended to a resource URL as a "special query", using the "?" URL syntax, will cause problems for existing forms that contain a "version" field.
The version notation is not a configuration notation.
The functionality provided by the basic version notation allows for the specification of a given revision of a single resource. The ability to "surf into the past", which requires the ability to retrieve the correct revisions of all of the embedding images and linked pages, may be (should be able to be?) built on top of the versioning URL notation.