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]