New rev. of versioning requirements.

I'm not sure that I've gotten everything perfect (drawbacks of
procrastination). On the other hand, I think that it is close to
ready-to-go. I am including the HTML as an attachment to this mail, and a
plain text version as an attachment to the next mail.

  -- David

Comments to the list; I'll react and we can submit this next Monday.

	<TITLE>Functional Requirements and Framework for Versioning on the WWW</TITLE>

<H3>Changes from last version</H3>

<LI>removed lock durations</LI>
<LI>added more references</LI>
<LI>changed "style-free versioning" to "policy independent
<LI>cleaned up prose.</LI>

<H3>To Do</H3>

Spell check.

<pre size=+2>
HTTP Working Group                                 David G. Durand,
INTERNET-DRAFT                                     Boston University
&lt;draft-durand-www-versreq-00.txt>                  November 6, 1996

Expires March, 1997

<H1>Functional Requirements and Framework for Versioning on the WWW</H1>
<h2>David G. Durand and Fabio Vitali</h2>

<h2>Status of this Memo</h2>
<p>This document is an Internet draft.  Internet drafts are working
documents of the Internet Engineering Task Force (IETF), its areas and its
working groups.  Note that other groups may also distribute working
information as Internet drafts.

<p>Internet Drafts are draft documents valid for a maximum of six months
and can be updated, replaced or obsoleted by other documents at any
time. It is inappropriate to use Internet drafts as reference material
or to cite them as other than as "work in progress".

<p>To learn the current status of any Internet draft please check the
"lid-abstracts.txt" listing contained in the Internet drafts shadow
directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East coast) or
ftp.isi.edu (US West coast). Further information about the IETF can be
found at URL: http://www.ietf.org/

<p>Distribution of this document is unlimited. Please send comments to
the WWW Distributed Authoring and Versioning mailing list,
&lt;w3c-dist-auth@w3.org>, which may be joined by sending a message with
subject "subscribe" to &lt;w3c-dist-auth-request@w3.org>. Discussions are
archived at URL:
http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth/. The HTTP
working group at &lt;http-wg@cuckoo.hpl.hp.com> also discusses the HTTP
protocol.  Discussions of the HTTP working group are archived at URL:
http://www.ics.uci.edu/pub/ietf/http/. General discussions about HTTP
and the applications which use HTTP should take place on the
&lt;www-talk@w3.org> mailing list.


This document describes functional requirements for integrating
versioning into the WWW.  Versioning is the fundamental basis of
document management systems, with far reaching effects on the
semantics of document identity and meaningful operations.  This
document reflects the basic versioning needs for document management
and collaborative authoring, but does not define the
complete set of requirements for these domains where they extend
beyond the versioning of individual resources.

<h2>1. Introduction</h2>

<P>This document discusses why versioning is
needed on the WWW, and the functional requirements for full version
support.  It is divided into three main sections, in addition to this
introduction.  In Section 2, we briefly describe the rationale for versioning
on the web, enumerating the goals of versioning on the WWW. All specific
requirements should support (and certainly should not hinder) the
realization of these goals.  Section 3 describes global requirements for
protocol development.  These are high-level requirements that should be
addressed in order to fulfil the rationale.  These requirements are
separated, because their acceptance slready constrains the space within
which detaild functional requirements can be defined.
Finally, in Section 4, we list the specific low-level functional requirements
that satisfy the goals defined in section 2, while meeting the
requirements of section 3.

<p>This work is based on David Fiander's suggestion to separate
versioning and configuration requirements, and we assume a two-layer
architecture for versioning on the web.  The first layer, whose
requirements are defined in this document, addresses the problem of
<EM>handling multiple versions of single resources.</EM> The second layer
will address the thornier problems of configuration management for multiple
resources.  Some, but by no means all, of the requirements for Configuration
Management are enumerated in the internet-draft "Requirements on HTTP for
Distributed Content Editing" [1].

<H2>2. Rationale</H2>
<p>The problem of versioning, particularly in relation to hypertext
documents like those that make up the majority of web content, is a complex
one.  Link integity, document set consistency, and editorial factors all
have an influence.  The hypertext reserach community has already identified
many problems and possible solutions.  For instance [3, 4] give good
overviews of the special problems involved.

<P>Versioning in the context of the world-wide web offers a variety of

<dt><EM>It provides infrastructure for efficient and controlled
management of large evolving web sites.</EM>
<dd>Modern configuration management systems are built on some form of
repository that can track the revision history of individual resources, and
provide the higher-level tools to manage those saved versions. Basic
versioning capabilities are required to support such systems.

	  <dt><EM>It allows parallel development and update of single resources</EM>
<dd>Since versioning systems register change by creating new objects, they
enable simultaneous write access by allowing the creation of variant
versions. Many also provide merge support to ease the reverse operation.

	  <dt><EM>It provides a framework for access control over resources.</EM>
	  <dd>While specifics vary, most systems provide some method of
controlling or tracking access to enable collaborative resource

	  <dt><EM>It allows browsing through past and alternative versions of a
<dd>Frequently the modification and authorship history of a resource is
critical information in itself.

	  <dt><EM>It provides stable names that can support externally stored
links for annotation and link-server support.</EM><EM></EM>

<dd>Both annotation and link servers frequently need to store
stable references to portions of resources that are not under their
direct control. By providing stable states of resources, version
control systems allow not only stable pointers into those resources,
but also well-defined methods to determine the relationships of those
states of a resource.

<dt><EM>It allows explicit semantic representation of single
resources with multiple states</EM>
<dd>A versioning system directly
represents the fact that a resource has an explicit history, and a
persistent identity across the various states it has had during the
course of that history.

<H2>3. Global requirements</H2>

<P>This section covers the overarching constraints that must
inform and direct detailed requirements for versioning support.  They
encompass compatibility across different implementations, as well as
compatibility with current practice.  The following are general
requirements for WWW versioning:

	  <dt><em>1. Stableness of versions.</EM>
Most versioning systems are intended to enable an accurate record of the
history of evolution of a document.  This accuracy is ensured by the fact
that a version eventually becomes "frozen" and immutable.  Once a version
is frozen, further changes will create new versions rather than modifying
the original.  In order for caching and persistent references to be
properly maintained, a client must be able to determine that a version has
been frozen.  We require that unlocked resource versions be frozen.  This
enables the common practice of keeping unfrozen "working versions".  Any
successful attempt to retrieve a frozen version of a resource will always
retrieve exactly the same content, or return an error if that version (or
the resource itself) are no longer available.  Since URLs may be
reassigned at a server's discretion this requirement applies only for that
period of time during which a URL identifies the same resource.  HTTP 1.1's
Entity tags will need to integrated into the versioning strategy in order
for caching to work properly.
	  <dt><em>2. User Agent Interoperability.</EM>
All versioning clients should be able to work with any
versioning HTTP server.  It is acceptable for some client/server
combinations to provide special features that are not universally
available, but the protocol should be sufficient that a basic level of
functionality will be universal.  It should be possible for servers and
clients to negotiate the use of optional features.
<dt><em>3.  Policy-free Versioning</em>
Haake and Hicks [2] have identified the notion of versioning styles
(referred to here as versioning policies, to reflect the nature of
client/server interaction) as one way to think about the different policies
that versioning systems implement.  Versioning policies include decisions
on the shape of version histories (linear or branched), the granularity of
change tracking, locking requirements made by a server, etc.  The
protocol should not unnecessarily restrict version management policies to any
one paradigm.  For instance, locking and version number assignment should
be inter-operable across servers and clients, even if there are some
differences in their preferred models.

<dt><em>4.  Separation of resource retrieval and concurrency control</em>
The protocol must separate the reservation and release of versioned
resources from their access methods.  Provided that consistency constraints
are met before, during and after the modification of a versioned resource,
no single policy for accessing a resource should be enforced by the
protocol.  For instance, a user may declare an intention to write before or
after retrieveing a resource via GET, may PUT a resource without releasing
the lock, and might even request a lock via HTTP, but then retrieve
the document using another communication channel such as FTP.</LI>
<dt><em>5.  Data format compatibility.</EM>
The protocol should enable a versioning server to work with existing
resources and URLs.  Special versioning information should not become a
mandatory part of document formats.
<dt><em>6.  Legacy Client and Server Support.</EM>
Servers should make versioned resources accessible to non-versioning
clients in a format acceptable to them.  Special version information that
would break existing clients, such as new mandatory headers,
cannot therefore be required for GET (and possibly also for PUT).
<!-- I think we agreed to get rid of this, didn't we?

	  <dt><em>7. Specific named version URLs that are constructed from a URL
and an opaque version string</EM>
Because the notation will be required to operate in the version
control environment preferred by the web site maintainer, it must be
able to properly contain arbitrary strings, which may be used by the
Version Control System as version identifiers.  While version
information may be intelligible to the human operator, and perhaps to
special-purpose clients, the client must be able to treat the version
specifier as a black box.

<H2>4. Functional requirements</H2>
The following functional requirements are intended to satisfy the
global requirements of Section 3 and enable the benefits listed in
Section 2.  In the description of some of the requirements, the names
of proposed semantic operations are capitalized to distinguish them
from plain text.  While HTTP methods are also capitalized, these
colliding conventions are not intended to suggest that any of the new
operations must be implemented by an HTTP method.

<P>The protocol should provide:</P>

	  <dt><em>1. Access to specific versions via a URL</em>
For each version of a resource, on a server, there should be a URL to
refer to that version.
This is required for version-specific linking, and for non-versioning client
	  <dt><em>2. A URL to denote a versioned resource itself, rather than specific
versions of it</em>
This identifier is needed for queries about the versioning status of a
resource, that do not apply only to one version of that resource.  This is
used to perform operations (such as adjusting attributes, changing locks,
or reassigning URLs) that affect all versions of a resource, rather than
any specific version.
	  <dt><em>3. Direct access to a server-defined "default", "current"
or "tip" version of a resource</EM>
This is one of the simplest ways to guarantee non-versioning client
compatibility.  If no special version information is provided, the server
will provide a default.  This does not rule out the possibility of a server
returning an error when no sensible default exists, but it does provide
a standard way to support non-versioning clients, and one of the most
common version access disciplines.
	  <dt><em>4. A way to access common related URLs from a versioned
URL,</em> whether by server query, URL computation, or some other way:
		  <LI>root version(s) of this document</LI>
		  <LI>predecessor version(s) of this document</LI>
		  <LI>successor version(s) of this document</LI>
		  <LI>default version of this document</LI>
It must be possible in some way
for a versioning client to access related versions to a resource whose URL
it has.  Possible methods of accessing such information, include, but are not
limited to: the server automatically adding header fields to a versioned
URL specifying the URL of the common related versions, the server providing
one or more query methods ("who is the previous version to this URL?"), or
a standardized way to compute related URLs when given a versioned URL.  In
particular,  access to the "default" version of a resource is an extremely
important operation, that a client should be able to perform at any time
that a versioned URL is seen.
	  <dt><em>5. A way to retrieve the complete version topology for this
There should be a way to retrieve information about all versions of a
resource.  The format for this information must be standardized so that the
basic information can be used by all clients.  Other specialized formats
should be accomodated, for servers and clients that require information
that cannot be included in the standard topology.</LI>
<dt><em>6.  Some way to determine that a URL points to a named version of a
This might be implemented as part of the URL format, a server query or
additional headers.
	  <dt><em>7. Some way to determine a version identification and a resource
identification for a versioned resource, given its URL</EM>
This requirement describes the ability to take the URL of a version of a
resource and determine:
	<li>a URL for the resource</li>
	<li>a version identifier for the resource.</li>
Note that this kind of facility supports only some comparison operations: It
enables the determination that two version-containing URLs designate
versions of the same resource.  However, given the phenomenon of URL
aliasing, it is insufficient to determine that they are <EM>not</EM>
versions of the same resource.
This is sort of a minimal "browsing
through time" requirement.  This requirement allows a client to tell that a
versioned resource has been accessed and then to invoke special versioning
or configuration management operations on the resource.  While client
performance will be best if this can be done via URL computation (i.e.
mangling) it could also be done by an extra query and round-trip to
the server.</DD>
	  <dt><em>8. A way to request exclusive access to a version of a resource
Since not all systems implement lock-based access, there open questions as
to how this should be implemented.  Client use of this method could be
optional, allowing some relatively strong guarantee on the meaning of
acquiring a lock.  Alternatively, clients could be expected to take a lock,
but servers might implement different locking policies.
	  <dt><em>10. A way to release exclusive access to a resource (UNLOCK)</EM>
This is the inverse of LOCK.</DD>
	  <dt><em>11. A way for a client to declare an intention to modify a resource
This operation is required before any versioned update.  Its effects may
vary depending on server policy, from locking a resource, to forking a new
variant, to a NOP on servers that do not track sessions or restrict
updates.  If this operation returns a version number, the client is
required to make sure that it uses a copy of the data associated with that
version number of the resource for any update operations it carries out.
Servers that wish to enforce a mandatory GET operation before update, should
simply use a fresh version identifier on the return from this operation.
<dt><em>12.  A way to declare the end of an intention to write a resource
This is the inverse of RESERVE.  Typically, servers will commit
updates at this time, and return a final version identifier if possible
and if it was not already returned.</DD>
	  <dt><em>13. A way to submit a new version of a resource (PUT)</EM>
The server should be able to attach it to the correct part of the version
tree, based on the version number associated with the resource before its

	  <dt><em>14. A way for a client to request a version identifier for a checked
out version.</em>
Such an identifier will not be used by any other client in the meantime.
The server may refuse the request.</DD>

	  <dt><em>15. A way for a client to propose a version identifier upon
submitting a version of a resource</EM>
The server may refuse to to use the client's suggested version identifier.

	  <dt><em>16. A way for a Client to supply metadata to be associated with a
The kinds of data supplied here might be simple textual comments or more
structured data.  An ability to attach arbitrary fields and content is
probably required, but a standard set of attributes that would enable
inter-operation would be useful.  For basic versioning we need only specify,
for example, that comments are attached as the message-body of the operation
that releases a write intention.  The special formats for structured metadata
can then be handled by using content-type negotiation, and the
content-types defined as part of the Configuration Management layer.
	  <dt><em>17. A way for a server to provide a version identifier to be
used for a
resource in further operations</em>
This general requirement notes that versioning clients are responsible
for providing the appropriate version identifier for a resource that is
being manipulated.  In particular, if a resource is being modified, any
server provided version must be used when submitting an update.  This
allows servers to track active sessions (however they may be implemented by
the server) by assigning version identifiers when documents are retrieved,
locked, or reserved.
<DT><em>18.  A way to track resources that have been RESERVE'ed (Session
<DD>This must be done by some kind of information transfer from the
server to the client (a "token"), when a resource is reserved.  The client
must then send the appropriate token on other operations on that same
resource.  This allows a matching of user's with their operations. of matching

<h2>Discussion of locking and reservation</h2>
<p>This section discusses some possible implementation strategies that take
advantage of the structure of the requirements listed above</p>

<p>The requirements on RESERVE and PUT take care of some key global
requirements: version access is logically separated from concurrency control
(RESERVE/RELEASE) and updating.  In terms of traditional CM systems, a
CHECKOUT is a RESERVE followed by a GET and a CHECKIN is a PUT followed by
an RELEASE.  By separating concurrency control (locking and unlocking of
resources) from modification of resources, and from data transfer operations
we can achieve versioning policy independence.

<p>This separation also allows us to meet requirement 18 (Session tracking),
using the negotiation of version identifiers top provide "tokens" for
outstanding operation.  The version identifier of a new resource can now be
negotiated at several different points in time:

<LI>When a resource is RESERVE'ed</LI>
<LI>When a resource is LOCK'ed</LI>
<LI>When a resource is PUT</LI>
<LI>When a resource is RELEASE'ed</LI>
At each of these points in time both client and server can transmit a
version identifier in the request.  Session tracking can be implemented by
using special version identifiers to track the outstanding sessions.  The
requirement on clients is that if they are provided a version number by the
server in the reply to any of these operations, that same version must be
used in subsequent requests to take action on that resource, if they are
intended to be part of the same session.
<p>While a client is always free to request a version identifier, a server
is never constrained to use a client's suggestion.  This session tracking
mechanism does not require more overhead than is already needed for other
version-aware operations.

<H2>Security Considerations</H2>

<P> These requirements do not directly address security issues.  We do not
believe that versioning has any special security requirements other than
authentication and session-level security.  We therefore expect that for
basic versioning, no special facilities will be required over those already
under development in the WWW. Full configuration management systems built
on the basic versioning support may require additional specialized security
methods built on top authenticated secure connections.

<p>This document is a result of the vigorous and valuable discussion on the
Versioning on the Web <A HREF="mailto:www-vers-wg-request@ics.uci.edu">
&lt;www-vers-wg-request@ics.uci.edu&gt;</A>, and the Distributed Authoring
mailing lists.  All the the interactions on these lists have been helpful,
as have several conversations.
David Fiander's initial requirements got us started and clarified several
points.  Jim Whitehead provided useful criticism, some new points, and
impetus to get this thing out the door.  Yaron Golan and Christopher
Seiwald provided extensive commentary and discussion.
<p>The following list include the above and others who have also helped
either with their postings, personal email or face-to-face discussions:

Dan Connolly, World Wide Web Consortium, connolly@w3.org<br>
Ron Fein, Microsoft, ronfe@microsoft.com<br>
David Fiander, Mortice Kern Systems, davidf@mks.com<br>
Roy Fielding, U.C. Irvine, fielding@ics.uci.edu<br>
Yaron Goland, Microsoft, yarong@microsoft.com<br>
Dave Long, America Online, dave@sb.aol.com<br>
Henrik Frystyk Nielsen, World Wide Web Consortium, frystyk@w3.org<br>
Larry Masinter, Xerox PARC, masinter@parc.xerox.com<br>
Murray Maloney, SoftQuad, murray@sq.com<br>
Christopher Seiwald, Perforce Software, seiwald@perforce.com<br>
Judith Slein, Xerox, slein@wrc.xeroc.com<br>

[1] "VerSE: Towards Hypertext Versioning Styles", Anja Haake and David
Hicks, Proc. Hypertext'96, the Seventh ACM Conference on Hypertext,
1996, pages 224-234.</p>
[2] "Requirements on HTTP for Distributed Content Editing"
,E. J. Whitehead, Work in Progress, IETF working draft
draft-whitehead-http-distreq-00.txt. September 1996

<p>[3] "Structural and Congitive Problems in Providing Version Control for
Hypertext", Kaspar &Oslash;sterbye, Proceedings of the ACM Conference on
Hypertext, Milano, Italy, 1992, pp 33-42.
<p>[4] "Version Control in Hypermedia Databases" Technical report
TAMU-HRL-91-004, Hypertext Research Lab, Texas A&M University. 1991.
$Id: draft-durand-versreq-00.html,v 1.3 1996/11/06 15:51:55 David Exp $
<!-- $Log: draft-durand-versreq-00.html,v $
 * Revision 1.3  1996/11/06  15:51:55  David
 * Fixed a few more typos, and HTML formatting errors.
 * Revision 1.2  1996/11/06  15:44:26  David
 * Next to final revision. Will require a spell-check, and removal of
 * changelog, but ready to go out to the list for final commentary.
 * Revision 1.1  1996/11/06  14:13:19  David
 * Versionig requirements document, W3c
 * Versioning reset by change of platforms

 # Revision 1.3 1996/09/16 08:25:19 david
 # Added missing destination for bibliographic references.
 # Revision 1.2 1996/09/16 08:03:18 david
 # Initial spell-checked version.
 # Disctributed at W3C meeting -->


David Durand              dgd@cs.bu.edu  \  david@dynamicDiagrams.com
Boston University Computer Science        \  Sr. Analyst
http://www.cs.bu.edu/students/grads/dgd/   \  Dynamic Diagrams
--------------------------------------------\  http://dynamicDiagrams.com/
MAPA: mapping for the WWW                    \__________________________