[Docs] [txt|pdf] [Tracker] [Email] [Nits]
Versions: 00 draft-ietf-webdav-versioning
INTERNET DRAFT E. J. Whitehead, Jr., UC Irvine
<draft-whitehead-webdav-versioning-00>
Expires December, 1998 June 9, 1998
A Web Versioning Protocol
Status of this Memo
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 documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or made obsolete by other
documents at any time. It is inappropriate to use Internet-Drafts as
reference material or to cite them other than as "work in progress".
To learn the current status of any Internet-Draft, please check the
"1id-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), ftp.ietf.org (US East Coast), or
ftp.isi.edu (US West Coast).
Distribution of this document is unlimited. Please send comments to
the Distributed Authoring and Versioning (WEBDAV) working group at
<w3c-dist-auth@w3.org>, which may be joined by sending a message
with subject "subscribe" to <w3c-dist-auth-request@w3.org>.
Discussions of the WEBDAV working group are archived at
<URL:http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth>.
Copyright Notice
Copyright (C) The Internet Society (1998). All Rights Reserved.
Abstract
This document describes a set of methods, headers, and properties
which extend the HTTP and WebDAV protocols to support versioning and
variant authoring of Web resources. Operations are provided to
support differencing two resources, applying a difference to a
resource, checkin and checkout, along with creation, manipulation,
and listing a version and variant history graph.
draft-whitehead-webdav-versioning-00 [Page 1]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
Contents
STATUS OF THIS MEMO...................................................1
COPYRIGHT NOTICE......................................................1
ABSTRACT..............................................................1
CONTENTS..............................................................2
1 INTRODUCTION .......................................................4
2 NOTATIONAL CONVENTIONS .............................................4
3 VGRAPH - VERSION AND VARIANT GRAPH .................................4
4 MAPPING A VGRAPH INTO A HTTP URL NAMESPACE .........................5
4.1 Vhandle and Vportal .............................................6
4.2 Example of Vhandle and Vportal ..................................6
4.3 An Example of Vhandle and Vportal for Only Variants .............8
4.4 Alternate Approaches Considered, But Not Followed ...............9
4.4.1 Client Controlled Versioning ................................9
4.4.2 Ordered Collections ........................................10
5 HTTP METHODS FOR VERSIONING AND VARIANT AUTHORING .................11
5.1 CREATE .........................................................11
5.1.1 Example - CREATE a Vhandle to Existing Vgraph ..............12
5.1.2 Example - CREATE a Vhandle and a new Vgraph ................12
5.1.3 Example - CREATE a Vhandle, Vportal, and Vgraph ............13
5.2 DIFF ...........................................................13
5.2.1 Example - DIFF of Two Unversioned text Resources ...........14
5.2.2 Example - DIFF of Two Versioned text Resources .............14
5.2.3 Example - DIFF of Two Unversioned image Resources ..........15
5.2.4 Example - DIFF between an image and text Resource ..........15
5.3 PATCH ..........................................................15
5.4 DEFSET .........................................................16
5.4.1 Example - DEFSET to an Exact Version Identifier ............16
5.4.2 Example - DEFSET to the Latest Version .....................17
5.5 GRAPHOP ........................................................17
5.5.1 Example - GRAPHOP to Create Arcs and Nodes .................18
5.6 GRAPHGET .......................................................20
5.7 CHECKOUT .......................................................20
5.7.1 Example - CHECKOUT .........................................21
5.8 CHECKIN ........................................................22
5.8.1 Example - CHECKIN ..........................................23
6 OPERATION OF EXISTING HTTP AND WEBDAV METHODS ON VHANDLE AND VPORTAL
RESOURCES............................................................24
6.1 GET, HEAD ......................................................24
6.2 PUT ............................................................24
6.3 POST, TRACE ....................................................24
6.4 OPTIONS ........................................................24
6.5 DELETE .........................................................24
6.6 COPY ...........................................................24
6.7 MOVE ...........................................................24
draft-whitehead-webdav-versioning-00 [Page 2]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
6.8 PROPFIND/PROPPATCH .............................................25
6.9 LOCK/UNLOCK ....................................................25
6.10 MKCOL ..........................................................25
7 HTTP HEADERS FOR VERSIONING AND VARIANT AUTHORING .................25
7.1 Diff ...........................................................25
7.2 Videntifier ....................................................25
8 PROPERTIES ........................................................26
9 INTERNATIONALIZATION CONSIDERATIONS ...............................26
10 IANA CONSIDERATIONS .............................................26
11 SECURITY CONSIDERATIONS .........................................26
12 XML ELEMENT DEFINITIONS .........................................26
13 REFERENCES ......................................................26
14 AUTHOR'S ADDRESS ................................................27
draft-whitehead-webdav-versioning-00 [Page 3]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
1 Introduction
Change is ubiquitous, nowhere more evident than in Web content.
Whether to support collaborative authoring, tracking content
deliveries, efficient retrieval of resources by requesting a delta,
or retrieval of previous versions of a resource, versioning
functionality is a key infrastructure for manipulating Web resources
which change over time.
In a global information system, one type of content does not suit
all. People who use the Web typically prefer their content in a
specific human language, character set, and media type. The Web
currently supports retrieval of such resource variants via content
negotiation, but provides limited support for authoring them.
Variation and change are not orthogonal, since an abstract Web
resource may have multiple versions, changing over time, and each
version of the resource may have several variants, to satisfy many
consumers.
This document describes extensions to the WebDAV distributed
authoring protocol [WebDAV], itself an extension of the HTTP 1.1
protocol [RFC2068], for manipulating versioned resources, variants
of resources, and their combinations.
2 Notational Conventions
Since this document describes a set of extensions to the HTTP/1.1
protocol, the augmented BNF used herein to describe protocol
elements is exactly the same as described in section 2.1 of
[RFC2068]. Since this augmented BNF uses the basic production rules
provided in section 2.2 of [RFC2068], these rules apply to this
document as well.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
3 Vgraph - Version and Variant Graph
A Vgraph is a directed acyclic graph which models the versions and
variants of one conceptual resource. A Vgraph consists of resources
(nodes), and typed relationships (arcs). The "derived-from"
relationship models a later resource as a revision of another
resource. For example, a revision labeled "1.2" has a "derived-from"
relationship to revision "1.1". The "variant-of" relationship models
situations where one resource varies from another by human language,
charset, media type, or content coding. A resource which is a
German language variant has a "variant-of" relationship to the
original English language resource.
draft-whitehead-webdav-versioning-00 [Page 4]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
In this specification, every version and variant of a resource is
itself a separate resource, with a separate URI. So, if there is a
set of resources which are conceptually viewed as "hello.html", then
versions 1 and 2 of hello.html would each have their own URIs, and
the URI for version 1 would be different than the URI for version 2.
If there was a German language variant of version 1 of hello.html,
it would have a URI which is different than the URIs of English
language versions 1 and 2 of hello.html.
Nodes are referentially contained within a Vgraph, and are
identified by their URI. Both nodes and arcs can have descriptive
information associated with them, known as properties. Node
descriptive information has a 1:1 correspondence with WebDAV
properties, hence any property that can be retrieved from the Vgraph
can be retrieved from a property on the resource, assuming the
Vgraph and the resource are on the same server, and the resource
supports WebDAV properties (e.g., an FTP resource would not).
Relationships are binary only, corresponding directly to arcs in a
graph.
A Vgraph MUST have a globally unique identifier, which is a URI. No
operations are supported on this URI by default (like a property
name, it is just a unique identifier). Similarly, all elements of
the Vgraph have globally unique identifiers; nodes are uniquely
identified by their URI, and each arc MUST have a globally unique
identifier, which is a URI.
A Vgraph has sufficient expressiveness to represent version
histories which span multiple servers, and can contain resources in
multiple URI schemes. Since resources are not directly contained by
a Vgraph, the same resource may participate in multiple Vgraphs. A
Vgraph expresses derived-from and is-variant-of relationships
between resources of any media type, and the media type may vary
across resources in a Vgraph.
4 Mapping a Vgraph into a HTTP URL Namespace
One of the siren calls for Web versioning is mandating a single
mapping of a Vgraph into the HTTP URL namespace. A typical approach
is to specify a convention for adding a version identifier to a URL,
such as ",v{version id}". This approach has fatal drawbacks:
- It adds semantics to URLs, making them non-opaque, and subject to
namespace collisions with other such URL "munging" schemes.
- It hard-codes derived-from relationships into version identifiers,
limiting their expressiveness, for example, mandating "1.2" instead
of "Jim's interim version".
- Since a specific version's URL is constructed from a version
identifier appended to a base URL, it requires all revisions of a
draft-whitehead-webdav-versioning-00 [Page 5]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
resource to be located on the same server, and resources are limited
to membership in just a single Vgraph.
- The approach scales poorly for handling variants, since extra
information must be added to the URL for representing variants of a
specific version of a resource (e.g., ",v{version
id},var{en,application/pdf}").
- It confuses the distinction between a single Web resource, and all
of the resources contained within a Vgraph.
A far more flexible approach is have no mapping of a Vgraph into the
HTTP URL namespace, providing instead two abstractions, a Vhandle,
and a Vportal.
4.1 Vhandle and Vportal
A Vhandle is a location in the HTTP URL namespace which supports
operations on one Vgraph. A Vhandle can be created anywhere in the
HTTP URL namespace, and supports operations which manipulate the
graph structure of its Vgraph. Operations such as checkout,
checkin, add an arc, add a node, and retrieve graph contents are
applied to a Vhandle. When a Vhandle is created, the Vgraph it
operates upon is specified by the Vgraph's unique identifier.
A Vportal is a location in the HTTP URL namespace which supports
retrieval operations on one Vgraph. A Vportal can be created
anywhere in the HTTP URL namespace. Operations such as retrieve a
specific version, retrieve a specific variant (e.g., GET with Accept
headers), set the default version/variant for unspecified retrieval
(e.g. GET without content negotiation or a named version), and
retrieving a difference between two versions are applied to a
Vportal. When a Vportal is created, the Vgraph it operates upon is
specified by the Vgraph's unique identifier.
Any Vgraph MUST have at least 1 Vhandle, and MAY have more. There
may be 0 or more Vportals for any Vgraph. While Vhandles and
Vportals are distinct abstractions, a given URL MAY act as both a
Vhandle and a Vportal simultaneously.
4.2 Example of Vhandle and Vportal
In this example, there is a conceptual resource called
"datasheet.html", which has three revisions where each revision has
a Japanese language variant. The server which manages these
resources, "www.specs.com", reserves an area of its HTTP namespace
under "/vcache/" specifically for versions and variants of
resources, and this area is separate from the area of its namespace,
"/products/", where requests for information are made.
This server has chosen a scheme where it assigns a unique numeric
identifier to each version and variant of a resource, and so for
draft-whitehead-webdav-versioning-00 [Page 6]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
this server version 1 of datasheet.html is located at
"http://www.specs.com/vcache/52619.html" (52619 is a unique number
generated by the server according to its server-specific naming
scheme), version 2 is located at
"http://www.specs.com/vcache/43687.html", and version 3 is located
at "http://www.specs.com/vcache/68432.html". The Japanese language
variant of version 1 of datasheet.html is located at
"http://www.specs.com/vcache/59766.html", and the variants of
versions 2 and 3 are located at
"http://www.specs.com/vcache/12344.html" and
"http://www.specs.com/vcache/87663.html". Like for versions 1
through 3, the server's specific naming policy for version and
variants has been used to generate these names, and the semantics of
the names are only meaningful to the server.
The Vgraph has the unique URI, "vgraph:4A7F-52DE-5DFA29FE-12A0", and
the following relationships:
http://www.specs.com/vcache/68432.html derived-from
http://www.specs.com/vcache/43687.html
(That is, version 3 is derived from version 2.)
http://www.specs.com/vcache/43687.html derived-from
http://www.specs.com/vcache/52619.html
(Version 2 is derived from version 1.)
http://www.specs.com/vcache/59766.html is-variant-of
http://www.specs.com/vcache/52619.html
(The Japanese language variant of version 1.)
http://www.specs.com/vcache/12344.html is-variant-of
http://www.specs.com/vcache/43687.html
(The Japanese language variant of version 2.)
http://www.specs.com/vcache/87663.html is-variant-of
http://www.specs.com/vcache/68432.html
(The Japanese language variant of version 3.)
There is one Vportal for this Vgraph, located at
"http://www.specs.com/products/chips/6502". This Vportal has its
default retrieval set to return version 3.
The following HTTP 1.1 request:
GET /products/chips/6502 HTTP/1.1
Host: www.specs.com
Returns exactly the same entity as a GET (with no content
negotiation) of http://www.specs.com/vcache/68432.html, i.e., it
returns version 3.
Adding language content negotiation to the request:
draft-whitehead-webdav-versioning-00 [Page 7]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
GET /products/chips/6502 HTTP/1.1
Host: www.specs.com
Accept-language: jp
Returns exactly the same entity as a GET (with no content
negotiation) of http://www.specs.com/vcache/87663.html, i.e., it
returns the Japanese language variant of version 3.
A specific version could be requested:
GET /products/chips/6502 HTTP/1.1
Host: www.specs.com
Videntifier: 2
This returns http://www.specs.com/vcache/43687.html, which is
version 2.
The Vgraph in this example has a single Vhandle, which has the same
URL as the Vportal.
4.3 An Example of Vhandle and Vportal for Only Variants
The example features a conceptual resource called "vino.html",
located on server "http://www.vinomundial.com/", which is
unversioned and has three language variants, German, French, and
English, in addition to its Spanish source. This server uses the
naming scheme of placing the language code of the variant in the
URL.
The Vgraph has the unique URI, "vgraph:6B9A-86BE-5EA47610-8876", and
has the following relationships:
http://www.vinomundial.com/vino.de.html is-variant-of
http://www.vinomundial.com/vino.es.html
(The German language variant is a variant of the Spanish language
source.)
http://www.vinomundial.com/vino.fr.html is-variant-of
http://www.vinomundial.com/vino.es.html
(The French language variant is a variant of the Spanish language
source.)
http://www.vinomundial.com/vino.en.html is-variant-of
http://www.vinomundial.com/vino.es.html
(The English language variant is a variant of the Spanish language
source.)
The Vportal for this Vgraph is located at
http://www.vinomundial.com/vino.html, and is set so the default
draft-whitehead-webdav-versioning-00 [Page 8]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
resource retrieved from this URL is the Spanish language variant,
http://www.vinomundial.com/vino.es.html.
An example retrieval with content negotiation from the portal URL
is:
GET /vino.html HTTP/1.1
Host: www.vinomundial.com
Accept-language: de
This returns the German language variant of the resource, i.e., the
same entity returned by a GET without accept headers on
http://www.vinomundial.com/vino.de.html.
This site also maintains a German-only hierarchy at
"http://www.vinomundial.com/de/" where all of the resources are in
German. There is a second Vportal on the Vgraph located in this
hierarchy, at "http://www.vinomundial.com/de/vino.html" This
Vportal is set so the default resource retrieved from this URL is
the German language variant,
http://www.vinomundial.com/vino.de.html.
This site also maintains a separate authoring section, at
"http://www.vinomundial.com/authoring/", and the Vhandle for the
Vgraph is located there, at
"http://www.vinomundial.com/authoring/vino.html". Whereas the rest
of the site is open to all requests, access to the authoring section
of the site is protected using Digest authentication, and all access
must be authenticated.
4.4 Alternate Approaches Considered, But Not Followed
Two alternate approaches for mapping versioned resources into the
HTTP URL space have been considered, but not used in this draft.
However, a discussion of these alternate approaches, their strengths
and deficiencies is useful to distinguish the approach presented
here.
4.4.1 Client Controlled Versioning
In this approach, the client controls the mapping of versioned
resources into the HTTP URL space, and manages all versioning
operations, as well as the consistency maintenance of the
version/variant graph. The paper, "Version management with meta-
level links via HTTP/1.1", by K. Ota, K. Takahashi, K. Sekiya
(draft-http-ntt-version-00, expired, but available off
http://www.ics.uci.edu/pub/ietf/webdav/), is an example of this
approach.
As an example of client controlled versioning, a checkout translates
into operations to create a new resource, lock the resource, lock
the predecessor, update the link information (stored in properties)
draft-whitehead-webdav-versioning-00 [Page 9]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
on the predecessor to point to the checked-out resource, unlock the
predecessor, add comment information to the new resource. Since the
client is only using base WebDAV operations to perform the
versioning, the server is completely unaware of any versioning --
all versioning semantics are provided by the client.
The benefits of this approach are:
1) Versioning capability can be achieved with smarter clients
working against WebDAV servers, so no new server technology is
needed (except for programmatic access control).
2) Due to the flexibility of the approach, different versioning
styles can easily be accommodated -- a new style requires a new
client. However, interactions between versioning operation
conventions for different versioning styles would need to be
addressed.
3) Members of the version graph can be located anywhere in the HTTP
URL space, and the version graph can span multiple HTTP servers,
and could potentially span several protocols.
There are several drawbacks to this approach:
1) The server is unable to provide consistency maintenance for the
version graph. For example, if a client that is unaware of the
versioning conventions deletes an intermediate member of a
version graph, the graph will be inconsistent.
2) The server is unable to optimize the storage of versions by using
delta-based compression mechanisms.
3) Since there is only one mapping of the members of the version
graph into the HTTP URL hierarchy, it is difficult to provide a
"retrieve default member" operation, e.g., a GET on URL XYZ
always returns the most recent member of the version graph.
4) Either retrieval of the complete version graph is an expensive
operation, requiring traversal of the graph, or the client is
responsible for replicating is-derived-from links from the
resource which contains the complete version graph, and to
individual members of the version graph. Neither is desirable.
5) The technique does not handle versioning collections well.
4.4.2 Ordered Collections
This technique linearizes the version graph, placing an order on the
members of the graph, and then places all members of the version
graph into a collection with this ordering. Limiting the graph to
linear versioning simplifies this technique, since there then exists
a simple temporal mapping of members of the version graph into the
ordering maintained by the collection. Furthermore, in the linear
versioning case, the version graph can be implicitly encoded into
the ordering, and hence the server will automatically maintain the
consistency of the version graph.
draft-whitehead-webdav-versioning-00 [Page 10]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
So, using this technique, the versions of a resource called
"hello.java" would be placed into an ordered collection called
"hello.java", and the individual versions would be named following
some naming convention, such as "hello.java,v1", "hello.java,v2",
etc. So, to retrieve version 2 of hello.java, a GET would be
performed on "hello.java/hello.java,v2". Retrieval of a default
member of the collection is supported by creating a convention for
the response of GET on the collection, e.g., a GET on "hello.java/"
might always return the most recent member of the version
graph/collection.
A variation on this approach which uses non-ordered collections and
permits non-linear version graphs is shown in the slide presentation
at: <http://www.ics.uci.edu/pub/ietf/webdav/orem/versioning/>.
The benefits of this approach are:
1) A simple client can use the ordering characteristics of the
collection to implicitly encode the version graph (linear
versioning only).
2) The server will perform automatic consistency maintenance of the
collection, hence version graph.
3) Supports retrieval of a default member of a collection.
4) Versioning can be supported by a simple client, and a relatively
simple server.
The drawbacks to this approach are:
1) If the version graph is implicitly stored in the ordering, it
extends poorly to non-linear version graphs, or graphs which have
variant relationships.
2) It extends poorly to versioning collections, that is, the
technique only works for the leaves of a HTTP URL hierarchy.
3) A single resource cannot participate in multiple version graphs,
(or conventions involving referential collection members must be
created, with implications for consistency maintenance.)
4) Requires modifications to the existing HTTP URL hierarchy.
Of these criticisms, the most telling is the inability to handle
versioned collections, thus locking out a future mechanism for
configuration management.
5 HTTP Methods for Versioning and Variant Authoring
5.1 CREATE
The CREATE method is used to create a Vhandle, a Vportal, or a
combination Vhandle and Vportal resource at the Request-URI. When
CREATE is used to create a Vhandle, either the URI of an existing
Vgraph MUST be given, or a new Vgraph will be created along with the
Vhandle, and the Vhandle will point to the new Vgraph.
draft-whitehead-webdav-versioning-00 [Page 11]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
5.1.1 Example - CREATE a Vhandle to Existing Vgraph
CREATE /authoring/dav-handle HTTP/1.1
Host: www.ics.uci.edu
Content-Length: xxx
Content-Type: text/xml; charset="utf-8"
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:create>
<D:vhandle>
<D:href>
vgraph:4A7F-52DE-5DFA29FE-12A0
</D:href>
</D:vhandle>
</D:create>
HTTP/1.1 201 Created
This example shows the creation of the Vhandle at URL
http://www.ics.uci.edu/authoring/dav-handle/. This Vhandle permits
operations on the Vgraph with the unique identifier, vgraph:4A7F-
52DE-5DFA29FE-12A0.
5.1.2 Example - CREATE a Vhandle and a new Vgraph
CREATE /authoring/spec-handle HTTP/1.1
Host: www.ics.uci.edu
Content-Length: xxx
Content-Type: text/xml; charset="utf-8"
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:create>
<D:vhandle/>
</D:create>
HTTP/1.1 201 Created
Content-Length: xxx
Content-Type: text/xml; charset="utf-8"
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:vgraph>
<D:href>
vgraph:5FDE-A43D-7865FDEA-7654
</D:href>
</D:vgraph>
draft-whitehead-webdav-versioning-00 [Page 12]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
This example shows the creation of a new Vgraph, which has been
assigned the unique name, vgraph:5FDE-A43D-7865FDEA-7654, and the
creation of a new Vhandle for that Vgraph, at
http://www.ics.uci.edu/authoring/spec-handle.
5.1.3 Example - CREATE a Vhandle, Vportal, and Vgraph
CREATE /spec-sheets/widget.html HTTP/1.1
Host: www.prod.com
Content-Length: xxx
Content-Type: text/xml; charset="utf-8"
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:create>
<D:vhandle/><D:vportal/>
</D:create>
HTTP/1.1 201 Created
Content-Length: xxx
Content-Type: text/xml; charset="utf-8"
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:vgraph>
<D:href>
vgraph:A7D9-EAEA-54AFFDEA-7654
</D:href>
</D:vgraph>
This example shows the creation of a new Vgraph, with the unique
identifier, vgraph:A7D9-EAEA-54AFFDEA-7654, and a resource at
http://www.prod.com/spec-sheets/wideget.html which simultaneously
acts as both a Vhandle and a Vportal for the Vgraph.
5.2 DIFF
The response from this method is the difference between two
resources. Each of the two resources may be given as the URI of a
non-versioned resource, or the URI of a Vportal resource combined
with a version identifier. This supports differences between two
arbitrary resources, two resources in the same Vgraph, resources
from different Vgraphs, or between a versioned resource and a non-
versioned resource.
The first resource is specified by the Request-URI. If the Request-
URI is the URL of a Vportal, then the version identifier of a
draft-whitehead-webdav-versioning-00 [Page 13]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
specific member of the Vgraph may be specified with the Videntifier
header. The second resource is specified by the Diff header.
The entity response from DIFF represents the difference(s) between
the two request resources. A server MAY return the difference in
any format, however a server MUST minimally support the TBD
difference format for all media types, and MUST perform Accept
header processing of client diff format preferences.
The server MUST minimally supply differences between two instances
of the same media type, for all text media types encoded using the
same charset. Ideally, servers will support differences between all
media types, minimally providing an octet-level difference. The
server SHOULD supply differences between different instances of the
text media type, (e.g. text/html and text/xml), and MAY support
differences between media types from different top-level trees. For
example, supporting a difference between text/xml and
application/xml is possible and meaningful, while a difference
between text/xml and image/gif is not.
*** Design Issue: which diff format should be required?
5.2.1 Example - DIFF of Two Unversioned text Resources
DIFF /drafts/draft-01.txt HTTP/1.1
Host: www.npo.org
Diff: <http://www.npo.org/drafts/draft-00.txt>
HTTP/1.1 200 OK
Content-type: zzz/dav-required-diff-format
Content-length: xyx
{.... diff entity here ...}
In this example, two non-versioned resources,
http://www.npo.org/drafts/draft-00.txt and
http://www.npo.org/drafts/draft-01.txt, which are text/plain,
charset="us-ascii", are differenced. Since the difference format is
currently TBD, the exact difference between the two resources is not
shown in this example.
5.2.2 Example - DIFF of Two Versioned text Resources
DIFF /drafts/draft.txt HTTP/1.1
Videntifier: "1"
Host: www.npo.org
Diff: <http://www.npo.org/drafts/draft.txt>; "0"
draft-whitehead-webdav-versioning-00 [Page 14]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
HTTP/1.1 200 OK
Content-type: zzz/dav-required-diff-format
Content-length: xyx
{... diff entity here ...}
In this example, the URL http://www.npo.org/drafts/draft.txt
identifies a Vportal, hence the two resources being differenced are
the two members of the associated Vgraph with version identifiers
"0" and "1". In this example, both resources are text/plain,
charset="us-ascii". Since the difference format is currently TBD,
the exact difference between the two resources is not shown in this
example.
5.2.3 Example - DIFF of Two Unversioned image Resources
DIFF /images/new-logo.gif HTTP/1.1
Host: www.corp.com
Diff: <http://www.corp.com/images/old-logo.gif>
HTTP/1.1 200 OK
Content-type: zzz/dav-required-diff-format
Content-length: xyx
{... diff entity here ...}
This example shows two non-versioned GIF images (image/gif) being
compared, http://www.corp.com/images/new-logo.gif, and
http://www.corp.com/iamges/old-logo.gif.
5.2.4 Example - DIFF between an image and text Resource
DIFF /images/new-logo.gif HTTP/1.1
Host: www.corp.com
Diff: <http://www.corp.com/drafts/index.html>; "1.1"
HTTP/1.1 409 Conflict
This example shows two resources, one an unversioned GIF image at
http://www.corp.com/images/new-logo.gif, the other a versioned HTML
resource which has version "1.1" in the Vgraph associated with the
Vportal http://www.corp.com/drafts/index.html. Since the server
cann perform a diff between a text/html and an image/gif resource,
it responds with a 409 Conflict status code.
5.3 PATCH
draft-whitehead-webdav-versioning-00 [Page 15]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
The PATCH method is used to modify parts of the entity returned in
the response to a GET method.
The request entity of the PATCH method contains a list of
differences between the resource identified by the Request-URI and
the desired content of the resource after the PATCH action has been
applied. The list of differences is in a format defined by the
media type of the entity (e.g., "application/diff") and must include
sufficient information to allow the server to convert the original
version of the resource to the desired version. Processing
performed by PATCH is atomic. Hence all changes MUST be
successfully executed or the method fails. PATCH MUST fail
executed on a non-existent resource; i.e., PATCH does not create a
resource as a side effect.
If the request appears (at least initially) to be acceptable, the
server MUST transmit an interim 100 response message after receiving
the empty line terminating the request headers and continue
processing the request. Since the semantics of PATCH are non-
idempotent, responses to this method are not cacheable.
*** Design Issue: In what format should the patch be applied? There
needs to be one patch format which all compliant applications must
support.
5.4 DEFSET
This method sets the default resource for the Vportal specified by
the Request-URI. The default resource is specified by the
Videntifier header, and identifies the resource which responds to
HTTP GET and POST method invocations (without Accept headers) on the
Vportal URI.
5.4.1 Example - DEFSET to an Exact Version Identifier
DEFSET /drafts/pos-paper.html HTTP/1.1
Host: www.ics.uci.edu
Videntifier: "1.3"
HTTP/1.1 200 OK
GET /drafts/pos-paper.html HTTP/1.1
Host: www.ics.uci.edu
HTTP/1.1 200 OK
Content-type: text/html
Content-length: xyx
{ ... this is the entity body for version 1.3 of pos-paper.html ...}
draft-whitehead-webdav-versioning-00 [Page 16]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
This example of DEFSET sets the default resource for the Vportal
http://www.ics.uci.edu/drafts/pos-paper.html. The new default is
version 1.3 of the Vgraph associated with the Vportal. The GET
method invocation after the DEFSET shows that the Vportal
http://www.ics.uci.edu/drafts/pos-paper.html will respond to a GET
with no Accept headers by returning the entity body of the resource
which is version 1.3 of the Vgraph associated with this Vportal.
5.4.2 Example - DEFSET to the Latest Version
DEFSET /drafts/pos-paper.html HTTP/1.1
Host: www.ics.uci.edu
Videntifier: latest
HTTP/1.1 200 OK
GET /drafts/pos-paper.html HTTP/1.1
Host: www.ics.uci.edu
HTTP/1.1 200 OK
Content-type: text/html
Content-length: xyx
{ ... this is the entity body for the most recent member of the
Vgraph associated with the Vportal
http://www.ics.uci.edu/drafts/pos-paper.html ...}
This example of DEFSET sets the default resource for the Vportal
http://www.ics.uci.edu/drafts/pos-paper.html. The new default is
the most recent member of the Vgraph associated with the Vportal.
The GET method invocation after the DEFSET shows that the Vportal
http://www.ics.uci.edu/drafts/pos-paper.html will respond to a GET
with no Accept headers by returning the entity body of the resource
which is the most recent member (of any branch) of the Vgraph
associated with this Vportal.
5.5 GRAPHOP
The GRAPHOP method processes instructions specified in the request
body to add a node or remove a node or add an arc or remove an arc
from the Vgraph associated with the Vhandle specified by the
Request-URI. Instruction processing MUST occur in the order
instructions are received (i.e., from top to bottom). Instructions
MUST either all be executed, or none executed. Thus if any error
occurs during processing all executed instructions MUST be undone
and a proper error result returned.
draft-whitehead-webdav-versioning-00 [Page 17]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
After all instruction processing has completed, the server MUST
ensure the graph is consistent by removing all arcs which do not
have a node at each endpoint, and all nodes which are not connected
to at least one arc.
*** Design issue: if an arc in the middle of a graph is removed,
there could be multiple, disconnected graphs. Should these extra
arcs be pruned?
Since the Vgraph only contains nodes by-reference, and not by-value,
if a node is removed from a Vgraph it does not imply the resource
associated with that node is deleted.
All servers MUST support the addarc and addnode processing
instructions, and SHOULD support the delarc and delnode processing
instructions.
5.5.1 Example - GRAPHOP to Create Arcs and Nodes
GRAPHOP /project/src/Makefile HTTP/1.1
Host: www.code.com
Content-type: text/xml; charset="utf-8"
Content-length: xyx
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:graphop>
<D:addnode>
<D:href>http://www.code.com/vcache/Makefile?v=1.0</D:href>
<D:href>http://www.code.com/vcache/Makefile?v=1.1</D:href>
<D:href>http://www.code.com/vcache/Makefile?v=1.2</D:href>
</D:addnode>
<D:addarc>
<D:arc>
<D:href>http://www.code.com/vcache/Makefile?v=1.1</D:href>
<D:href>http://www.code.com/vcache/Makefile?v=1.0</D:href>
<D:arctype><isderivedfrom/></D:arctype>
</D:arc>
<D:arc>
<D:href>http://www.code.com/vcache/Makefile?v=1.2</D:href>
<D:href>http://www.code.com/vcache/Makefile?v=1.1</D:href>
<D:arctype><isderivedfrom/></D:arctype>
</D:arc>
</D:addarc>
</D:graphop>
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: zyz
draft-whitehead-webdav-versioning-00 [Page 18]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:multistatus>
<D:response>
<D:graphresponse>
<D:addnodestat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:addnodestat>
<D:addarcstat>
<D:arc>
<D:href>
http://www.code.com/vcache/Makefile?v=1.1
</D:href>
<D:href>
http://www.code.com/vcache/Makefile?v=1.0
</D:href>
<D:arctype><isderivedfrom/></D:arctype>
<D:arcid>arcid:4567-ae4f-78de54ad-6754</D:arcid>
</D:arc>
<D:arc>
<D:href>
http://www.code.com/vcache/Makefile?v=1.2
</D:href>
<D:href>
http://www.code.com/vcache/Makefile?v=1.1
</D:href>
<D:arctype><isderivedfrom/></D:arctype>
<D:arcid>arcid:4567-de21-432156d8-ad31</D:arcid>
</D:arc>
<D:status>HTTP/1.1 200 OK</D:status>
</D:addarcstat>
</D:graphresponse>
</D:response>
</D:multistatus>
This example shows a Vgraph being populated with three nodes and two
arcs. The following resources (which existed prior to the beginning
of GRAPHOP processing) were successfully added to the Vgraph:
http://www.code.com/vcache/Makefile?v=1.0
http://www.code.com/vcache/Makefile?v=1.1
http://www.code.com/vcache/Makefile?v=1.2
Two arcs were successfully added to the graph, and were assigned the
following unique identifiers:
http://www.code.com/vcache/Makefile?v=1.2 is-derived-from
http://www.code.com/vcache/Makefile?v=1.1
unique identifier: arcid:4567-ae4f-78de54ad-6754
draft-whitehead-webdav-versioning-00 [Page 19]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
http://www.code.com/vcache/Makefile?v=1.1 is-derived-from
http://www.code.com/vcache/Makefile?v=1.0
unique identifier: arcid:4567-de21-432156d8-ad31
Since the graph was consistent after adding these three nodes and
two arcs, the server was not required to perform any additional
processing to maintain the consistency of the Vgraph.
5.6 GRAPHGET
The GRAPHGET method returns an entity body listing the contents of
the Vgraph associated with the Vhandle specified by the Request-URI.
*** Design issue: How should the Vgraph entity be returned? RDF is
one solution, as is XML without RDF semantics.
*** Design issue: should comment (arbitrary property) information be
returned by GRAPHGET?
5.7 CHECKOUT
The CHECKOUT method performs the following operations on the Vgraph
associated with the Vportal at the Request-URI:
1) A new resource, known as the "working resource", is created at a
location determined by the server. This resource is acted upon
by authoring tools, accepting PUTs of intermediate and final
results, and allowing properties to be read and set on it.
2) The initial contents of the working resource are identical to the
resource whose version is given by the Videntifier header, if
specified, or the default resource if not.
3) An "is-derived-from" relationship is added to the Vgraph between
the working resource and the resource given by the Videntifier
header, if specified, or the default resource if not.
4) The working resource is write locked, with the type of the write
lock (exclusive or shared) determined by the server. By default,
the lock SHOULD be an exclusive write lock.
5) Any check-out comments submitted in the request body are stored
in the comments property on the working resource.
6) Access permissions MUST be set so the principal requesting the
check-out has read and write permission to the working resource.
All of these operations MUST be performed, or none are performed.
Thus, if any error occurs during processing, all operations
performed to that time MUST be undone and a proper error result
returned.
Since a lock is being created during normal CHECKOUT processing, the
Timeout header (specified in [WebDAV]) MAY be submitted with a
CHECKOUT method request, and is subject to normal Timeout header
processing as described in [WebDAV].
draft-whitehead-webdav-versioning-00 [Page 20]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
*** Design Issue: What should be the behavior if the lock times out?
*** Design Issue: Extending Checkout to work with Depth header to
check out a collection hierarchy with one operation.
A successful response to CHECKOUT will return a checkoutstat XML
element which contains the URL of the working resource, and a
lockdiscovery XML element that describes the lock created on the
working resource.
5.7.1 Example - CHECKOUT
>> Request
CHECKOUT /reports/1998/q1.doc HTTP/1.1
Host: www.funcorp.com
Content-type: text/xml; charset="utf-8"
Content-length: xxyx
Videntifier: "1.5"
Timeout: Infinite
Authorization: Digest username="craig.snider",
realm="reports@www.funcorp.com", nonce="...",
uri="/reports/1998/q1.doc", response="...", opaque="..."
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:checkoutinfo>
<D:comment>Checked-out to add new project expense numbers.
</D:comment>
<D:owner>Craig Snider</D:owner>
</D:checkoutinfo>
>> Response
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: zzyzx
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:checkoutstat>
<D:lockdiscovery>
<D:activelock>
<D:locktype><D:write/></D:locktype>
<D:lockscope><D:exclusive/></D:lockscope>
<D:depth>0</D:depth>
<D:owner>
Craig Snider
</D:owner>
<D:timeout>Infinite</D:timeout>
<D:locktoken>
draft-whitehead-webdav-versioning-00 [Page 21]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
<D:href>
opaquelocktoken:e5d7a3214-6da3-4432-5c39-fe98a34deaea
</D:href>
</D:locktoken>
</D:activelock>
<D:lockdiscovery>
<D:workingresource>
<D:href>
http://www.mycorp.com/vcache/q1.doc?v1.6
</D:href>
</D:workingresource>
</D:checkoutstat>
This example shows a CHECKOUT being performed on the Vgraph
associated with the Vportal at
http://www.funcorp.com/reports/1998/q1.doc. The checkout was
submitted with a Videntifier header of "1.5", meaning the checkout
is occurring off of version 1.5 of q1.doc. A comment was submited
with the checkout, giving rationale for the checkout operation, and
owner information was also submitted for the lock created during
checkout. A lock timeout value of "Infinite" was also requested,
expressing a desire for a lock which never times out.
The response from the CHECKOUT method lists the characteristics of
the lock, and the location of the working resource. In this case,
the lock is an exclusive write lock, that will never time out, and
affects affects the working resource. The lock token for the lock
is "opaquelocktoken:e5d7a3214-6da3-4432-5c39-fe98a34deaea", and the
owner information from the request has been associated with the
lock.
The location of the working resource is
"http://www.mycorp.com/vcache/q1.doc?v1.6".
In this example, the nonce, response, and opaque fields have not
been calculated in the Authorization request header.
5.8 CHECKIN
The CHECKIN method performs the following operations on the Vgraph
associated with the Vportal given by the Request-URI, and on the
working resource specified in the request body.
1) The working resource is unlocked.
2) The access control for the working resource is set such that no
principal has write access (i.e., it is frozen).
3) The server MAY set the version identifier for the working
resource to the version identifier specified in the request body.
All of these operations MUST be performed, or none are performed.
Thus, if any error occurs during processing, all operations
draft-whitehead-webdav-versioning-00 [Page 22]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
performed to that time MUST be undone and a proper error result
returned.
A valid CHECKIN request MUST include a Lock-Token header listing the
lock token of the working resource's lock.
5.8.1 Example - CHECKIN
>> Request
CHECKIN /reports/1998/q1.doc HTTP/1.1
Host: www.funcorp.com
Content-type: text/xml; charset="utf-8"
Content-length: zxyzx
Lock-Token: <opaquelocktoken:e5d7a3214-6da3-4432-5c39-fe98a34deaea>
Authorization: Digest username="craig.snider",
realm="reports@www.funcorp.com", nonce="...",
uri="/reports/1998/q1.doc", response="...", opaque="..."
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:checkininfo>
<D:comment>Added project expense numbers, fixed Figure 5,
made minor fixes from reviewer's feedback.
</D:comment>
<D:workingresource>
<D:href>
http://www.mycorp.com/vcache/q1.doc?v1.6
</D:href>
</D:workingresource>
<D:videntifier>
Stable release 1
</D:videntifier>
</D:checkininfo>
>> Response
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: zxyzx
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:checkinstat>
<D:videntifier>
Stable release 1
</D:videntifier>
</D:checkinstat>
draft-whitehead-webdav-versioning-00 [Page 23]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
This example shows a CHECKIN method which checks-in the working
resource "http://www.mycorp.com/vcache/q1.doc?v1.6" which is a
member of the Vgraph associated with the Vportal
http://www.funcorp.com/reports/1998/q1.doc. Comments have been
submitted with the checkin, as has a suggested version identifier
("Stable release 1").
The response from CHECKIN gives the actual version identifier
assigned by the server. In this case, the server accepted the
version identifier submitted by the user agent.
In this example, the nonce, response, and opaque fields have not
been calculated in the Authorization request header.
6 Operation of Existing HTTP and WebDAV Methods on Vhandle and Vportal
Resources
[Ed note: This section needs to be fleshed-out. These are my
initial views on how they should be defined.]
6.1 GET, HEAD
GET and HEAD on a Vportal are redirected to the default member of
the associated Vgraph. GET and HEAD on a Vhandle are not defined by
this specification.
6.2 PUT
PUT is not permitted to either a Vhandle or Vportal.
6.3 POST, TRACE
Same as in RFC 2068.
6.4 OPTIONS
Same as in RFC 2068 plus WebDAV extensions.
6.5 DELETE
Operates on the Vhandle and Vportal. Deleting the last Vhandle to a
Vgraph removes the Vgraph (and could leave dangling Vportals).
6.6 COPY
Operates on the Vhandle and Vportal (i.e., duplicates the Vhandle or
the Vportal in a new location in the namespace).
6.7 MOVE
Operates on the Vhandle and Vportal (i.e., moves the Vhandle or the
Vportal to a new location in the namespace).
draft-whitehead-webdav-versioning-00 [Page 24]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
6.8 PROPFIND/PROPPATCH
Operates on the properties of the Vhandle or the Vportal (i.e., both
a Vhandle and a Vportal have properties for each instance).
*** Design Issue: Since PROPFIND is used to list the members of a
collection, if this approach is extended to handle versioned
collections, there will need to be a way to pass the PROPFIND to the
default member of the Vgraph for the versioned collection to afford
a "list the members of the default member of the Vgraph for the
versioned collection."
6.9 LOCK/UNLOCK
A lock on a Vhandle affects the Vhandle and the Vgraph, but is not
propagated to the individual members of the Vgraph (the reference is
locked, not the actual resource). A lock on a Vportal affects only
the Vportal, but not the Vgraph.
6.10 MKCOL
Not allowed on a Vgraph or a Vportal.
7 HTTP Headers for Versioning and Variant Authoring
7.1 Diff
Diff = "Diff" ":" Coded-url [";" version-id] ; Coded-url from
Section 8.4 of [WebDAV]
versiod-id = quoted-string
The Diff header is used to specify one of the two URIs being
differenced by the DIFF method. If the Coded-url is the URL of a
Vportal, then the optional version-id specifies the version
identifier of a specific member of the Vgraph.
7.2 Videntifier
Videntifier = "Videntifier" ":" vspec
vspec = version-id | "latest" [branch-id]
branch-id = Coded-url
If the Request URI is a Vportal, this header specifies a member of
the Vgraph associated with that Vportal. The specification is
either an exact version identifier, or the most recent member of the
Vgraph ("latest"), or the most recent member of a branch of the
Vgraph ("latest" along with a branch identifier URI).
draft-whitehead-webdav-versioning-00 [Page 25]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
*** Design issue: Since version identifiers are human-readable
fields, need to have i18n support. This implies that version
identifiers should be marshalled in the request body.
8 Properties
Need properties for comments, version graph info, and arcs leading
to/from this node for all vgraphs the resource participates in (need
to get root, default, pred., succ.)
A Vportal and a Vhandle have properties associated with each
instance of the Vportal or Vhandle.
9 Internationalization Considerations
TBD.
Fields in the protocol that are human-readable:
- version identifier
- comments submitted on checkout and checkin
10 IANA Considerations
This protocol defines several new URI schemes:
- vgraph:, for globally unique version graph identifiers
- arcid:, for globally unique arc identifiers
11 Security Considerations
TBD.
12 XML Element Definitions
TBD. Some element definitions are reused from the WebDAV
Distributed Authoring Protocol specification [WebDAV].
13 References
[RFC2068] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-
Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. U.C.
Irvine, DEC, MIT/LCS. January, 1997.
[RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate
Requirement Levels." RFC 2119, BCP 14. Harvard University. March,
1997.
[WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter,
D. Jensen, "Extensions for Distributed Authoring on the World Wide
draft-whitehead-webdav-versioning-00 [Page 26]
INTERNET-DRAFT A Web Versioning Protocol June 9, 1998
Web -- WEBDAV". Microsoft, U.C. Irvine, Netscape, Novell.
Internet-draft, work-in-progress. <draft-ietf-webdav-protocol-08>
14 Author's Address
E. James Whitehead, Jr.
Dept. of Information and Computer Science
University of California, Irvine
Irvine, CA 92697-3425
Email: ejw@ics.uci.edu
draft-whitehead-webdav-versioning-00 [Page 27]
Html markup produced by rfcmarkup 1.129b, available from
https://tools.ietf.org/tools/rfcmarkup/
