INTERNET-DRAFT Geoffrey Clemm, Rational Software draft-ietf-deltav-versioning-07 Jim Amsden, IBM Chris Kaler, Microsoft Jim Whitehead, U.C. Irvine Expires February 9, 2001 August 9, 2000 Versioning Extensions to WebDAV Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 obsoleted 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract This document specifies a set of methods, headers, and resource-types that define the WebDAV Versioning extensions to the HTTP/1.1 protocol. WebDAV Versioning will minimize the complexity of clients so as to facilitate widespread deployment of applications capable of utilizing the WebDAV Versioning services. WebDAV Versioning includes: - Core versioning with automatic versioning for versioning-unaware clients, - Workspace, activity and baseline management, - URL namespace versioning. Clemm, et al. [Page 1] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Table of Contents 1 INTRODUCTION...........................................5 1.1 Relationship to DAV...................................6 1.2 Terms.................................................6 1.3 Notational Conventions................................8 2 WEBDAV VERSIONING SEMANTICS............................9 2.1 Creating and Modifying a Version-Controlled Resource..9 2.2 Changing the Target of a Version Selector............10 2.3 Labeling a Version...................................10 3 VERSIONING PROPERTIES BY RESOURCE TYPE................10 3.1 Common Property Values...............................11 3.1.1 boolean Syntax...................................11 3.1.2 label Syntax.....................................11 3.1.3 date-time Syntax.................................11 3.1.4 href XML Element.................................11 3.2 Resource Properties..................................11 3.2.1 DAV:creator-displayname..........................11 3.2.2 DAV:comment......................................12 3.3 Version Selector Properties..........................12 3.3.1 DAV:target (protected)...........................12 3.3.2 DAV:auto-version.................................12 3.3.3 DAV:version-name (protected).....................12 3.4 Version Properties...................................12 3.4.1 DAV:version (protected)..........................12 3.4.2 DAV:predecessor-set (protected)..................13 3.4.3 DAV:checkin-date (protected).....................13 3.4.4 DAV:label-name-set (protected)...................13 3.5 Working Resource Properties..........................13 3.5.1 DAV:checked-out (protected)......................13 4 VERSIONING HEADERS....................................13 4.1 Target-Selector......................................13 5 VERSIONING AND EXISTING METHODS.......................14 5.1 New Status Codes.....................................14 5.2 OPTIONS..............................................14 5.2.1 Example - OPTIONS................................14 5.3 GET..................................................15 5.4 PUT..................................................15 5.5 PROPFIND.............................................15 5.6 PROPPATCH............................................15 5.7 DELETE...............................................16 5.8 COPY.................................................16 5.9 MOVE.................................................16 5.10 LOCK...............................................16 6 VERSIONING METHODS....................................16 6.1 VERSION-CONTROL......................................16 6.1.1 Example - VERSION-CONTROL (creating a new version history) 18 6.1.2 Example - VERSION-CONTROL (using an existing version history) 18 Clemm, et al. [Page 2] INTERNET-DRAFT WebDAV Versioning August 9, 2000 6.2 CHECKOUT.............................................18 6.2.1 Example - CHECKOUT...............................19 6.3 CHECKIN..............................................20 6.3.1 Example - CHECKIN................................21 6.4 UNCHECKOUT...........................................21 6.4.1 Example - UNCHECKOUT.............................22 6.5 SET-TARGET...........................................22 6.5.1 Example - SET-TARGET.............................23 6.6 LABEL................................................23 6.6.1 Example - Replacing a label......................24 6.7 REPORT...............................................25 6.7.1 Example - REPORT.................................25 7 VERSIONING REPORTS....................................26 7.1 DAV:successor-report.................................26 7.1.1 Example - DAV:successor-report...................26 7.2 DAV:checkout-report..................................26 7.2.1 Example - DAV:checkout-report....................27 7.3 DAV:latest-checkin-report............................27 7.3.1 Example - DAV:latest-checkin-report..............27 7.4 DAV:version-tree-report..............................28 7.4.1 Example - DAV:version-tree-report................28 8 ADVANCED VERSIONING...................................30 8.1 Advanced Versioning Terms............................30 9 ADVANCED VERSIONING SEMANTICS.........................32 9.1 Workspaces...........................................32 9.2 Baselines............................................33 9.3 Activities, Change Sets, and Branches................33 9.4 Parallel Development and Merging.....................34 9.5 Version-Controlled Collections.......................34 9.6 Mutable Versions.....................................36 10 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE......37 10.1 Version Selector Properties........................37 10.1.1 DAV:version-history (protected)..................37 10.2 Version Properties.................................37 10.2.1 DAV:version-history (protected)..................37 10.2.2 DAV:activity-set.................................37 10.2.3 DAV:checkout-fork................................37 10.2.4 DAV:checkin-fork.................................38 10.2.5 DAV:mutable......................................38 10.3 Working Resource Properties........................38 10.3.1 DAV:version-history (protected)..................38 10.3.2 DAV:merge-set....................................38 10.3.3 DAV:auto-merge-set...............................39 10.3.4 DAV:unreserved...................................39 10.3.5 DAV:predecessor-set..............................39 10.3.6 DAV:activity-set.................................39 10.3.7 DAV:checkout-fork................................39 10.3.8 DAV:checkin-fork.................................39 10.3.9 DAV:mutable......................................40 10.4 Version History Properties.........................40 Clemm, et al. [Page 3] INTERNET-DRAFT WebDAV Versioning August 9, 2000 10.4.1 DAV:version-set (protected)......................40 10.4.2 DAV:initial-version (protected)..................40 10.4.3 DAV:working-resource-set (protected).............40 10.5 Workspace Properties...............................40 10.5.1 DAV:current-activity-set.........................40 10.5.2 DAV:parent-workspace (protected).................41 10.5.3 DAV:child-workspace-set (protected)..............41 10.6 Collection Properties..............................41 10.6.1 DAV:baseline-selector (protected)................41 10.7 Baseline Properties................................41 10.7.1 DAV:version-set (protected)......................41 10.8 Activity Properties................................42 10.8.1 DAV:version-set (protected)......................42 10.8.2 DAV:subactivity-set..............................42 11 ADVANCED VERSIONING HEADERS..........................42 11.1 Workspace..........................................42 12 ADVANCED VERSIONING AND EXISTING METHODS.............43 12.1 New Status Codes...................................43 12.2 OPTIONS............................................44 12.2.1 Example - OPTIONS................................44 12.3 GET................................................44 12.4 PUT................................................44 12.5 DELETE.............................................44 12.6 MKCOL..............................................45 12.7 COPY...............................................45 12.8 MOVE...............................................45 12.9 VERSION-CONTROL....................................45 12.10 CHECKOUT...........................................46 12.10.1........................Example - Advanced CHECKOUT 47 12.11 CHECKIN............................................48 12.12 UNCHECKOUT.........................................49 12.13 SET-TARGET.........................................49 13 ADVANCED VERSIONING METHODS..........................50 13.1 MKWORKSPACE........................................50 13.1.1 Example - MKWORKSPACE............................51 13.2 MKACTIVITY.........................................51 13.2.1 Example - MKACTIVITY.............................52 13.3 BASELINE-CONTROL...................................52 13.3.1 Example - BASELINE-CONTROL.......................53 13.4 MERGE..............................................53 13.4.1 Example - MERGE..................................55 14 ADVANCED VERSIONING REPORTS..........................56 14.1 DAV:property-report................................56 14.1.1 Example - DAV:property-report....................56 14.2 DAV:repository-report..............................58 14.3 DAV:workspace-url-report...........................58 14.3.1 Example - DAV:workspace-url-report...............58 14.4 DAV:baselined-collection-report....................59 14.4.1 Example - DAV:baselined-collection-report........59 14.5 DAV:merge-preview-report...........................60 Clemm, et al. [Page 4] INTERNET-DRAFT WebDAV Versioning August 9, 2000 14.5.1 Example - DAV:merge-preview-report...............60 14.6 DAV:compare-report.................................61 14.6.1 Example - DAV:compare-report.....................62 14.6.2 Example - DAV:repository-report..................63 14.7 DAV:current-workspace-report.......................63 14.7.1 Example - DAV:current-workspace-report...........63 14.8 DAV:version-selector-url-report....................64 14.8.1 Example - DAV:version-selector-url-report........64 15 INTERNATIONALIZATION CONSIDERATIONS..................64 16 SECURITY CONSIDERATIONS..............................65 17 SCALABILITY..........................................65 18 AUTHENTICATION.......................................65 19 IANA CONSIDERATIONS..................................65 20 INTELLECTUAL PROPERTY................................65 21 ACKNOWLEDGEMENTS.....................................66 22 INDEX................................................66 23 REFERENCES...........................................66 24 AUTHORS' ADDRESSES...................................67 25 APPENDICES...........................................67 26 OVERWRITE HEADER.....................................67 27 OPEN ISSUES AND PENDING CHANGES......................67 1 INTRODUCTION This document defines WebDAV Versioning extensions, an application of HTTP/1.1 for handling resource versioning in a WebDAV environment. [Goals] describes the motivation and requirements for these extensions. WebDAV Versioning defines two levels of versioning functionality: core versioning and advanced versioning. Core versioning provides versioning of largely independent resources. It allows authors to concurrently create, label, and access distinct versions of a resource, and provides automatic versioning for versioning-unaware clients. All core versioning functionality MUST be provided by a resource that supports versioning. Advanced versioning provides more sophisticated capabilities such as logical change tracking, workspace management, and versioning the URL namespace. A particular resource may support only a subset Clemm, et al. [Page 5] INTERNET-DRAFT WebDAV Versioning August 9, 2000 of the advanced versioning capabilities. The advanced versioning capabilities provided by a particular resource can be discovered with an OPTIONS request. This document will first define the terminology, semantics, properties, methods, and headers for core versioning, and then define the additional terminology, semantics, properties, and methods for advanced versioning. 1.1 Relationship to DAV To maximize interoperability and the use of existing protocol functionality, versioning support is designed as extensions to the WebDAV [RFC2518] protocol. The versioning extensions are designed to be orthogonal to most aspects of the HTTP and WebDAV protocols, except for specific interactions identified in sections 5 and 12. The semantics of version-controlled collections relies on the binding model defined by the WebDAV binding extensions [Binding]. 1.2 Terms This draft uses the terms defined in HTTP [RFC2616] and WebDAV [RFC2518]. In addition, the following terms are defined: Versionable Resource A "versionable resource" is a resource that can be put under version control. Version A "version" is an unmodifiable resource that contains the content and dead properties of a particular state of a resource under version control. A "version URL" is a URL chosen by the server to identify a particular version. Version History A "version history" is a resource created when a resource is put under version control to contain the versions of that resource. A "version history URL" is a URL chosen by the server to identify a version history resource. Version Selector A "version selector" is a resource that provides access to a version of a particular version history. When a versionable resource is put under version control, a new version history resource is created and the versionable resource is replaced with a version selector resource that selects the initial version of that version history. Clemm, et al. [Page 6] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Target The version selected by a version selector resource is called the "target" of that version selector. The content and dead properties displayed by a version selector are those of the target version. Working Resource A "working resource" is a modifiable resource that results from checking out a version selector resource. A "working resource URL" is a URL chosen by the server to identify a particular working resource. Version Label A "version label" is a string chosen by a client to identify a particular version of a version history. Initial Version An "initial version" is the first version of a version history. Predecessor, Successor, Ancestor, Descendant A "predecessor" of a version is another version that was checked out or merged to create the version. When a version is related to another version by one or more predecessor relations, it is called an "ancestor" of that version. The inverse of the predecessor and ancestor relations are the "successor" and "descendant" relations. Therefore, if X is a predecessor of Y, then Y is a successor of X, and if X is an ancestor of Y, then Y is a descendant of X. Clemm, et al. [Page 7] INTERNET-DRAFT WebDAV Versioning August 9, 2000 The following diagram illustrates several of the previous definitions. History of foo.html +---+ Initial Version ----> | | V1 +---+ | ^ | | +---+ | Label ------> "beta1" | | V2 | Ancestor +---+ | / \ | / \ | +---+ +---+ | | V3 | | V4 ^ +---+ +---+ | | | | Predecessor | | | | | +---+ +---+ | | | V5 | | V6 | Descendant | +---+ +---+ | Successor | \ / | | \ / v v +---+ | | V7 +---+ Fork When a second successor is added to a version, this creates a "fork" in the version history. In the preceding diagram, there is a fork at version V2. 1.3 Notational Conventions The augmented BNF used by this document to describe protocol elements is exactly the same as the one described in Section 2.1 of [RFC2068]. Because this augmented BNF uses the basic production rules provided in Section 2.2 of [RFC2068], those 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]. The term "protected" is placed in parentheses following the definition of a property that cannot be updated with a PROPPATCH request. Clemm, et al. [Page 8] INTERNET-DRAFT WebDAV Versioning August 9, 2000 A phrase of the form "the method XXX is applied to a yyy" means "the method XXX is applied to a URL that identifies a resource of type yyy". 2 WEBDAV VERSIONING SEMANTICS 2.1 Creating and Modifying a Version-Controlled Resource In order to track the history of the content and dead properties of a resource, an author can put the resource under version control. This creates a new version history resource, creates an initial version in that version history that contains the current content and dead properties of the versionable resource, and then replaces the versionable resource with a version selector resource that selects this initial version. ===VERSION-CONTROL==> | foo.html foo.html | foo.html History | +----+ | +----+ +----+ | S1 | | | ----------> | S1 | +----+ | +----+ +----+ In order to modify the content or dead properties of a version selector resource, an author must first check it out to create a working resource. The author can then modify the state of the working resource by setting its content or properties any number of times. When the author determines the working resource is in a state that should be retained, the author checks it in to create a new version in the version history. The version that was checked out is remembered as the predecessor of the new version. Unless the server supports mutable versions, an author cannot modify the content or dead properties of a version, but instead must create descendants of that version. Clemm, et al. [Page 9] INTERNET-DRAFT WebDAV Versioning August 9, 2000 The following diagram illustrates the effect of the checkout/checkin process on a version history resource. ===CHECKOUT==> ===CHECKIN==> foo.html | foo.html | foo.html History | History | History | | +----+ | +----+ | +----+ | S1 | V1 | | S1 | V1 | | S1 | V1 +----+ | +----+ | +----+ | | | | | | | | | | +----+ | +----+ | +----+ | S2 | V2 | | S2 | V2 | | S2 | V2 +----+ | +----+ | +----+ | | | | | | | +----+ | +----+ | | WR | | | S3 | V3 | +----+ | +----+ 2.2 Changing the Target of a Version Selector Another way to modify the state of a version selector is to use a SET-TARGET request to select another version to be the target of that version selector. The SET-TARGET request will set the content and dead properties of the version selector to be those of the specified version. 2.3 Labeling a Version At any time, a version can be given a client-assigned label in order to provide a meaningful name for that version. A given version label can be assigned to at most one version of a given version history, but may be reassigned to another version at any time. Note that although a given label cannot be applied to more than one version from the same version history, the same label can be applied to versions from different version histories. For certain methods, a Target-Selector request header can be used to make a version selector display the content and properties of the version selected by the Target-Selector label, instead of those of the target of that version selector. 3 VERSIONING PROPERTIES BY RESOURCE TYPE This section defines the new resource types and properties introduced by WebDAV versioning. When a property cannot be updated Clemm, et al. [Page 10] INTERNET-DRAFT WebDAV Versioning August 9, 2000 by a PROPPATCH request, it is identified in this document as a "protected" property. Unless an initial value of a property of a given type is defined by this document, the initial value of a property of that type is server-defined. 3.1 Common Property Values 3.1.1boolean Syntax Some properties take a Boolean value. boolean = "F" | "T" 3.1.2label Syntax A label is a sequence of characters. When a label is marshaled in the header of an HTTP request, the characters are encoded using the UTF-8 encoding scheme. 3.1.3date-time Syntax Some properties take a date or time value. The syntax of date-time is defined in section 23.2 of [RFC2518]. 3.1.4DAV:href XML Element The DAV:href XML element is defined in section 12.3 of [RFC2518]. 3.2 Resource Properties WebDAV versioning introduces the following dead properties for a resource. These properties can be placed on any resource, and are defined here only to provide a standard name for a property containing this type of information about a resource. 3.2.1DAV:creator-displayname This property contains a description of the creator of the resource that is suitable for presentation to a user. The DAV:creator- displayname of a version can be used to indicate who created that version. Clemm, et al. [Page 11] INTERNET-DRAFT WebDAV Versioning August 9, 2000 3.2.2DAV:comment This property is used to track a brief comment about a resource that is suitable for presentation to a user. The DAV:comment of a version can be used to indicate why that version was created. 3.3 Version Selector Properties WebDAV versioning introduces the following properties for a version selector. 3.3.1DAV:target (protected) This property contains the version URL of the version that is the target of this version selector. This property can be modified by the CHECKIN and SET-TARGET methods. 3.3.2DAV:auto-version When the DAV:auto-version property of a version selector is set, a request that attempts to modify that version selector (such as PUT/PROPPATCH) is automatically preceded by a CHECKOUT and automatically followed by a CHECKIN. This allows a versioning- unaware client to modify a version selector. PCDATA value: boolean 3.3.3DAV:version-name (protected) This property contains a server-defined string that is different for each version in a given version history. 3.4 Version Properties WebDAV versioning introduces the following properties for a version. 3.4.1DAV:version (protected) This property contains the version URL for this version. Clemm, et al. [Page 12] INTERNET-DRAFT WebDAV Versioning August 9, 2000 3.4.2DAV:predecessor-set (protected) This property contains a version URL for each predecessor of this version. Except for the initial version, which has no predecessors, there is either the single predecessor that was checked out to create the version, or there are the multiple predecessors that were merged to create the version. 3.4.3DAV:checkin-date (protected) This property contains the date on the server when the version was checked in. This property MUST NOT be created by a server that cannot provide a reasonable approximation of the current time. PCDATA value: date-time 3.4.4DAV:label-name-set (protected) This property contains the labels that currently select this version. PCDATA value: label-name 3.5 Working Resource Properties WebDAV versioning introduces the following properties for a working resource. 3.5.1DAV:checked-out (protected) This property contains the version URL of the version that defined the initial state of the working resource. 4 VERSIONING HEADERS 4.1 Target-Selector The following defines the BNF for the Target-Selector header: Target-Selector := "Target-Selector" ":" label An example of a Target-Selector header is: Target-Selector: released Clemm, et al. [Page 13] INTERNET-DRAFT WebDAV Versioning August 9, 2000 When a method supports the Target-Selector header, if the request- URL identifies a version selector, the request MUST act as if the content and dead properties of the version selector were that of the version identified by the label specified in the Target- Selector header. A Target-Selector header has no effect on a request-URL that does not identify a version selector. In particular, it has no effect on a version URL, a working resource URL, or a version history URL. A server MUST return a Vary header containing Target-Selector in a response to a cacheable request (e.g. GET, PROPFIND) that includes a Target-Selector header. 5 VERSIONING AND EXISTING METHODS For any method that updates the content or dead properties of a resource, when that method is applied to a version selector, the method MUST fail unless the version selector has a DAV:auto-version property. If the version selector has a DAV:auto-version property, the version selector is checked out, the update is applied to the resulting working resource, and the working resource is checked in. This functionality allows a versioning unaware client to modify a version selector. If any part of the checkout/update/checkin sequence fails, the status from the failed part of the request MUST be returned, and the server state preceding the request sequence MUST be restored. 5.1 New Status Codes 4xx (No Version Selected): The label specified in a Target-Selector header selects no version of this version selector. 4xx (Cannot modify content or property of a version) 5.2 OPTIONS When a resource supports core versioning, the DAV response header for an OPTIONS request MUST contain "core-versioning". 5.2.1Example - OPTIONS >>REQUEST OPTIONS /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE Clemm, et al. [Page 14] INTERNET-DRAFT WebDAV Versioning August 9, 2000 HTTP/1.1 200 OK DAV: 1, 2, core-versioning Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, VERSION-CONTROL 5.3 GET Additional Marshalling: A Target-Selector request header MAY be specified. Additional Postconditions: If the request URL identifies a version selector, the response will contain the content of the target of the version selector. 5.4 PUT Additional Preconditions: If the request URL identifies a version selector, the PUT MUST fail unless DAV:auto-version is set for that version selector. If the request URL identifies a version, the PUT MUST fail. Additional Postconditions: If the PUT creates a new resource, it is server defined whether it is under version control. 5.5 PROPFIND Additional Marshalling: A Target-Selector request header MAY be specified. Additional Postconditions: If the request-URL identifies a version selector, the response will contain both the live properties of the version selector and the dead properties of the target of the version selector. 5.6 PROPPATCH Additional Preconditions: If the request URL identifies a version selector, an attempt to modify a dead property MUST fail unless DAV:auto-version is set for that version selector. If the request-URL identifies a version, the PROPPATCH MUST fail. Clemm, et al. [Page 15] INTERNET-DRAFT WebDAV Versioning August 9, 2000 An attempt to modify a property (either core or advanced) defined by this document as being protected MUST fail. An attempt to modify a property (either core or advanced) whose semantics defined by this document are not enforced by the server MUST fail. This helps ensure that a client will be notified when it is trying to use a property whose semantics are not supported by the server. 5.7 DELETE Additional Preconditions: If the request-URL identifies a version or a working resource, the result is undefined. The CHECKIN and UNCHECKOUT methods can be used to delete a working resource. 5.8 COPY Additional Marshalling: A Target-Selector request header MAY be specified. Additional Postconditions: It is server defined whether the new resource created at the Destination is under version control. 5.9 MOVE Additional Preconditions: If the request-URL is a version URL, the request MUST fail. 5.10LOCK Additional Preconditions: If a LOCK request includes a Target-Selector request header, the result is undefined. 6 VERSIONING METHODS 6.1 VERSION-CONTROL A VERSION-CONTROL request can be used to create a version controlled resource at the request-URL. Clemm, et al. [Page 16] INTERNET-DRAFT WebDAV Versioning August 9, 2000 If the request-URL identifies a versionable resource, a new version history resource is created, an initial version is created whose content and dead properties are that of the versionable resource, and the versionable resource is replaced by a version selector resource whose target is the initial version of the new version history. If the request body identifies a version, the request-URL MUST identify a null resource, and a new version selector whose target is the specified version is created at the request-URL. If a VERSION-CONTROL request fails, the server state preceding the request MUST be restored. Marshalling: The request body MUST be a DAV:version-control XML element. The response MUST include a Cache-Control:no-cache header. Preconditions: The request-URL MUST identify a versionable resource, a null resource, or a version selector. If the request-URL identifies a versionable resource or a version selector, the DAV:version-control request body element MUST be empty. If the request-URL identifies a null resource, the DAV:version- control request body element must contain a version URL. Return Status Codes: 200 (OK): A version selector resource already exists at the request-URL. 201 (Created): A new version selector resource was created at the request-URL. Postconditions: If the request-URL identified a version selector at the time of the request, the VERSION-CONTROL request MUST NOT change the state of that version selector. If the request-URL identified a versionable resource at the time of the request, a new version history is created, a copy of the versionable resource is made the initial version of the new version selector, and the versionable resource is replaced by a new version selector resource whose DAV:target identifies the initial version of the new version history. The DAV:predecessor-set of the initial Clemm, et al. [Page 17] INTERNET-DRAFT WebDAV Versioning August 9, 2000 version is empty, and the DAV:checkin-date is the current date on the server. If the request-URL identified a null resource, a new version selector resource is created at the request-URL whose target is the version specified in the request body. 6.1.1Example - VERSION-CONTROL (creating a new version history) >>REQUEST VERSION-CONTROL /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 201 Created 6.1.2Example - VERSION-CONTROL (using an existing version history) >>REQUEST VERSION-CONTROL /bar.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://repo.webdav.org/his/12/rev/V3 >>RESPONSE HTTP/1.1 201 Created 6.2 CHECKOUT A CHECKOUT request can be applied to a version selector to create a new working resource. The content and properties of the working resource are a copy of a version selected by the CHECKOUT request. If a version is specified in the CHECKOUT request body, that is the selected version; otherwise, if a version is selected by a Target- Selector request header, that is the selected version; otherwise, the target of the version selector is the selected version. If a CHECKOUT request fails, the server state preceding the request MUST be restored. Marshalling: Clemm, et al. [Page 18] INTERNET-DRAFT WebDAV Versioning August 9, 2000 If a request body is included, it MUST be a DAV:checkout XML element. The request MAY include a Target-Selector header. The response MUST include a Location header. The response MUST include a Cache-Control:no-cache header. Preconditions: The request-URL MUST identify a version selector. If a version is specified in the CHECKOUT request body, it MUST be a version in the same version history as the current target of the version selector. If a label is specified in a Target-Selector header, it MUST select a version in the version history of the target of the version selector. If the version selector is locked, the lock token MUST be specified in the CHECKOUT request. Response Status Codes: 201 (Created): The server created a new working resource. 405 (Method Not Allowed): The request-URL did not identify a version selector. Postconditions: The Location response header MUST contain the URL of the new working resource. The DAV:checked-out property of the new working resource identifies the selected version. The content and dead properties of the working resource are the same as the content and dead properties of the selected version. The DAV:version-history property of the working resource is the same as that of the selected version. 6.2.1Example - CHECKOUT >>REQUEST CHECKOUT /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 Clemm, et al. [Page 19] INTERNET-DRAFT WebDAV Versioning August 9, 2000 >>RESPONSE HTTP/1.1 200 OK Location: http://www.webdav.org/ws/core/3/foo.html 6.3 CHECKIN A CHECKIN request can be applied to a working resource to produce a new version that is a copy of the working resource. If a CHECKIN request fails, the server state preceding the request MUST be restored. Marshalling: If a request body is included, it MUST be a DAV:checkin XML element. The response MUST include a Location header. The response MUST include a Cache-Control:no-cache header. Preconditions: The request-URL MUST identify a working resource. If the version selector is write-locked, then the appropriate lock token MUST be included in the request. Response Status Codes: 201 (Created): The version was successfully created. 405 (Method Not Allowed): The request-URL did not identify a working resource. 409 (Conflict): A precondition was violated. Postconditions: A new version in the version history of the version selector is created. The DAV:version of the new version is set to a server-defined URL. The DAV:predecessor-set of the new version is set to the DAV:checked-out property of the working resource. The DAV:checkin-date of the new version is set to the current date on the server. Clemm, et al. [Page 20] INTERNET-DRAFT WebDAV Versioning August 9, 2000 The content and dead properties of the working resource are copied into the new version. Unless DAV:keep-checked-out is specified, the working resource is deleted. If DAV:keep-checked-out is specified, the DAV:checked-out property of the working resource is set to be the version URL of the new version. The DAV:target of the version selector is set to contain the version URL of the new version. The version URL for the new version is returned in a Location response header. 6.3.1Example - CHECKIN >>REQUEST CHECKIN /ws/core/3/foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 201 Created Location: http://repo.webdav.org/his/23/rev/32 6.4 UNCHECKOUT An UNCHECKOUT request can be applied to a working resource to cancel the CHECKOUT. If an UNCHECKOUT request fails, the server state preceding the request MUST be restored. Marshalling: The response MUST include a Cache-Control:no-cache header. Preconditions: The request-URL MUST identify a working resource. If the request-URL is write-locked, the UNCHECKOUT request MUST include the appropriate lock token. Response Status Codes: 200 (OK): The checkout was successfully cancelled. 405 (Method Not Allowed): The URL did not identify a working resource. Clemm, et al. [Page 21] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Postconditions: The working resource is deleted. 6.4.1Example - UNCHECKOUT >>REQUEST UNCHECKOUT /ws/core/3/foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 200 OK 6.5 SET-TARGET A SET-TARGET request can be applied to a version selector to change the DAV:target of that version selector. A SET-TARGET can be applied to a collection with a Depth header even if the collection is not a version selector, in order to perform the SET-TARGET on all its version selector members. Use of a version element in a Depth SET-TARGET does not make sense since the SET-TARGET would succeed on only one of the version selectors. Marshalling: The SET-TARGET request body MUST be a DAV:set-target XML element. The request MAY include a Depth header. The response MUST include a Cache-Control:no-cache header. Preconditions: The request-URL MUST identify a version selector. If a version is specified in the SET-TARGET request body, it MUST be a version in the same version history as the current target of the version selector. If a label is specified in a Target-Selector header, it MUST select a version in the version history of the target of the version selector. If the request-URL is write-locked, the SET-TARGET request MUST include the appropriate lock token. Clemm, et al. [Page 22] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Response Status Codes: 200 (OK): The version selector was successfully updated. 207 (Multi-status): The SET-TARGET was applied to a collection. 400 (Bad Request): The request body was invalid. 405 (Method Not Allowed): The request-URL did not identify a version selector. Postconditions: The DAV:target of the version selector MUST be set to the specified version. If a Depth header is specified, the SET-TARGET request is applied separately to the collection and to each of the members of the collection that satisfy the depth constraint. 6.5.1Example - SET-TARGET >>REQUEST SET-TARGET /foo.html HTTP/1.1 Host: www.webdav.org Content-type: text/xml; charset="utf-8" Content-Length: xxxx stable >>RESPONSE HTTP/1.1 200 OK 6.6 LABEL A LABEL request can be applied to a version to modify or list the labels on that version. If a LABEL request is applied to a version selector, the operation is applied to the target of that version selector unless a Target-Selector header is specified. Marshalling: The request body MUST be a DAV:label element. Clemm, et al. [Page 23] INTERNET-DRAFT WebDAV Versioning August 9, 2000 PCDATA value: label-name The request MAY include a Target-Selector header. The request MAY include a Depth header. The response MUST include a Cache-Control:no-cache header. Preconditions: The request-URL MUST identify a version or a version selector. If DAV:add is specified, the specified label MUST NOT currently select a version of the version history of that version selector. If DAV:remove is specified, the specified label MUST select that version. Response Status Codes: 200 (OK): The label modification was successful. 400 (Bad Request): The body of the request was not valid. 405 (Method Not Allowed): The request-URL did not identify a version or a version selector. Postconditions: If DAV:add or DAV:replace is specified, the specified label selects the version. If DAV:remove is specified, the specified label no longer selects any version of the version history of the version selector. 6.6.1Example - Replacing a label >>REQUEST LABEL /foo.html HTTP/1.1 Host: www.webdav.org Content-type: text/xml; charset="utf-8" Content-Length: xxxx released >>RESPONSE HTTP/1.1 200 OK Clemm, et al. [Page 24] INTERNET-DRAFT WebDAV Versioning August 9, 2000 6.7 REPORT A REPORT request is an extensible mechanism for obtaining information about resources. Unlike a resource property, a report can depend on the state of resources in addition to the one identified by the request-URL. The REPORT method MUST NOT change the state of any resource managed by the server. The request body of a REPORT request specifies which report is being requested. The response body of a REPORT request contains the requested report. Every resource MUST support DAV:available-report, which lists the reports supported at the request-URL. The response body of DAV:available-report is a DAV:report-set element containing empty XML elements identifying the reports available at that request URL. 6.7.1Example - REPORT Following is an example of a DAV:available-report: >>REQUEST REPORT /myCollection HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 200 OK Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Clemm, et al. [Page 25] INTERNET-DRAFT WebDAV Versioning August 9, 2000 7 VERSIONING REPORTS Versioning introduces the following reports (the REPORT method is defined in section 6.7). 7.1 DAV:successor-report This report can be applied to a version or a version selector, and lists the version URL of each version whose DAV:predecessor-set contains the selected version. The request MAY include a Target-Selector header. The response body of a DAV:successor-report MUST be a DAV:successor-set element. 7.1.1Example - DAV:successor-report >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://repo.webdav.org/his/23/rev/2 http://repo.webdav.org/his/23/rev/2.1.1 7.2 DAV:checkout-report This report can be applied to a version or a version selector, and lists all working resources whose DAV:checked-out property identifies the selected version. The request MAY include a Target-Selector header. Clemm, et al. [Page 26] INTERNET-DRAFT WebDAV Versioning August 9, 2000 The response body of a DAV:checkout-report MUST be a DAV:working- resource-set element. 7.2.1Example - DAV:checkout-report >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://repo.webdav.org/ws/1/foo.html http://repo.webdav.org/ws/3/foo.html 7.3 DAV:latest-checkin-report This report can be applied to a version selector, and returns the version URL of the version with the latest DAV:checkin-date from the version history of the version selector. If the version history does not maintain DAV:checkin-date properties, no version will be identified. If multiple versions contain the latest DAV:checkin- date, the server arbitrarily picks one to identify as the latest. The response body of a DAV:latest-checkin-report MUST be a DAV:href element. 7.3.1Example - DAV:latest-checkin-report >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Clemm, et al. [Page 27] INTERNET-DRAFT WebDAV Versioning August 9, 2000 >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://repo.webdav.org/his/23/rev/5 7.4 DAV:version-tree-report The DAV:version-tree-report describes all the versions of the version history of a version selector in the form of a nested tree of versions. The response body of a DAV:version-tree-report MUST be a DAV:version-tree element. A DAV:version-tree element contains a version URL followed by the DAV:creator-displayname, DAV:comment, DAV:predecessor-set, DAV:checkin-date, and DAV:label-name-set properties of that version, the DAV:working-resource-set resulting from a DAV:checkout-report for that version, and a DAV:version-tree for each successor of that version. A server MAY omit all elements other than DAV:version for a version that has previously appeared in the DAV:version-tree element. This can provide significant space savings when a version has multiple predecessors. 7.4.1Example - DAV:version-tree-report The version tree drawn below would produce the following version tree report. foo.html History +---+ | | V1 +---+ / \ / \ Clemm, et al. [Page 28] INTERNET-DRAFT WebDAV Versioning August 9, 2000 +---+ +---+ | | V2 | | V2.1.1 +---+ +---+ >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://repo.webdav.org/his/23/rev/V1 Fred get it started http://repo.webdav.org/his/23/rev/V2 Fred Fix the spelling http://repo.webdav.org/his/23/rev/V1 http://repo.webdav.org/his/23/rev/V2.1.1 Sally Translate into French http://repo.webdav.org/his/23/rev/V1 Clemm, et al. [Page 29] INTERNET-DRAFT WebDAV Versioning August 9, 2000 8 ADVANCED VERSIONING 8.1 Advanced Versioning Terms Workspace A "workspace " is a collection that contains a set of related versionable resources, version selectors, and working resources. Clemm, et al. [Page 30] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Baseline A baseline is a resource associated with a collection that captures the target of each version selector that is a member of that collection. In the following diagram, /x/a.html, /x/y/b.html, and /x/y/c.html are members of /x, and the baseline B1.1 of /x selects versions V1, V3, and V5. /x/a.html /x/y/b.html /x/y/c.html History History History +---+ | | V2 +---+ | | +------------------|-------------------------------+ | | | | +---+ +---+ +---+ Baseline | | | | V1 | | V3 | | V5 B1.1 | | +---+ +---+ +---+ | | | | | +------------------|------------|------------------+ | | | | +---+ +---+ | | V4 | | V6 +---+ +---+ Merging "Merging" is a mechanism for updating a collection with a specified set of versions. For each version to be merged, the version selector in the collection whose version history contains that version is identified. If the specified version is a descendant of the target of the identified version selector, the merge changes the target of the version selector to be the specified version. If the specified version is an ancestor of the target of the identified version selector, the merge leaves that version selector unchanged. If the specified version is neither a descendant nor an ancestor of the target of the identified version selector, the merge checks out the version selector, and the client is then responsible for updating the resulting working resource so that its state corresponds to the logical merge of the specified version with the checked out version. Clemm, et al. [Page 31] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Activity An "activity" is a non-versionable resource that selects a set of versions that are on a single "line of descent", where a line of descent is a sequence of versions connected by successor relationships. If an activity selects versions from multiple version histories, the versions selected in each version history must be on a single line of descent. An activity will often correspond to some unit of work or conceptual change. The following diagram illustrates activities. Version V5 is the latest version of foo.html selected by activity Act-2, and version V8 is the latest version of bar.html selected by activity Act-2. foo.html History bar.html History +---+ +---+ Act-1| |V1 Act-1| |V6 +---+ +---+ | | | | +---+ +---+ Act-1| |V2 Act-2| |V7 +---+ +---+ / \ | / \ | +---+ +---+ +---+ Act-1| | Act-2| |V4 Act-2| |V8 +---+ +---+ +---+ | | | | +---+ +---+ Act-2| |V5 Act-3| |V9 +---+ +---+ 9 ADVANCED VERSIONING SEMANTICS 9.1 Workspaces In core versioning, working resources are identified by server defined URL's. In order to allow a client to associate user meaningful names with a related set of working resources, advanced versioning provides a "workspace" resource. A workspace is a collection whose members are a set of related versionable resources, version selectors, and working resources. When a version selector that is a member of a workspace is checked out, it is replaced by the new working resource. When a working resource that is a member of a workspace is checked in, it is replaced by a version selector that selects the new version as its target. Clemm, et al. [Page 32] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Initially, an empty workspace can be created. Versionable resources can then be added to the workspace with standard WebDAV requests such as PUT and MKCOL. As resources are identified whose history should be tracked, they can be put under version control. Alternatively, a workspace can be initialized by the state of an existing workspace. In this case, a version selector is created in the new workspace corresponding to each version selector in the existing workspace, where corresponding version selectors in different workspaces will share the same version history. In order to ensure unambiguous merging and baselining semantics, a workspace may contain at most one version selector for a given version history (although a server may support multiple bindings in a workspace to the same version selector). In order to expose multiple views of a set of related version selectors in the URL namespace, multiple workspaces must be used. In order to make a change made to a version selector in one workspace visible in another workspace, that version selector must be checked in, and then the corresponding version selector in the other workspace can be updated to select the new version. 9.2 Baselines A workspace that contains a large number of version selectors can consume a large amount of space on a server. This can make it prohibitively expensive to remember the state of an existing workspace by creating a copy of that workspace. A "baseline" resource provides a mechanism to efficiently capture the state of a workspace. In order to allow efficient baseline implementation, the state of a baseline is limited to be a set of versions, and the operations on a baseline are limited to the creation of a baseline from a workspace, and restoring or merging the baseline back into a workspace. 9.3 Activities, Change Sets, and Branches It is often desirable to perform several different logical changes in a single workspace, and then selectively merge a subset of those logical changes to other workspaces. An "activity" can be used to represents a single logical change, where an activity tracks all the resources that were modified to effect that single logical change. When a version selector is checked out, the author specifies which activity should be associated with a new version that will be created when that version selector is checked in. It is then possible to select a subset of the logical changes for merging into another workspace, by specifying the appropriate activities in a MERGE request. Another common problem is that although a resource under version control may need to have multiple lines of descent, all work done by members of a given team must be on a single line of descent (to Clemm, et al. [Page 33] INTERNET-DRAFT WebDAV Versioning August 9, 2000 avoid merging between team members). An activity resource provides the mechanism for addressing this problem. When a version selector is checked out, a client can request that an existing activity be used or that a new activity be created. Activity semantics then ensures that all versions in a given version history that are associated with an activity are on a single line of descent. If all members of a team share a common activity (or sub-activities of a common activity), then all changes made by members of that team will be on a single line of descent. Activities appear under a variety of names in existing versioning systems. When an activity is used to capture a logical change, it is commonly called a "change set". When an activity is used to capture a line of descent, it is commonly called a "branch". 9.4 Parallel Development and Merging When an author wants to accept the changes made in another workspace, it is important to not just select those versions as the targets of the corresponding version selectors in the author's workspace, since this would hide any changes made to those version selectors in the author's workspace. Instead, the versions created in another workspace should be "merged" into the author's workspace. The version history of a version selector provides the information needed to determine what should be the result of the merge. In particular, the merge should select whichever version is later in the line of descent from the initial version. In case the versions to be merged are on different lines of descent (neither version is an ancestor of the other), neither version should be selected, but instead, a new version should be created that contains the logical merge of the content and properties of those versions. The MERGE request can be used to check out each version selector with such a conflict, and set the DAV:merge-set property of each new working resource to identify the versions to be merged. The author is responsible for modifying the content of a working resource so that it represents the logical merge of those versions, and then adding the versions that were successfully merged to the DAV:predecessor- set of the working resource. If the server is capable of automatically performing the MERGE, it MAY update the content of the working resource and the DAV:predecessor set itself. An automatic merge is indicated by the absence of a DAV:merge-set. Before checking in the working resource, the author is responsible for verifying that the automatic merge is correct. 9.5 Version-Controlled Collections The state of a collection consists of a set of properties and a set of named bindings to internal members of that collection. When a Clemm, et al. [Page 34] INTERNET-DRAFT WebDAV Versioning August 9, 2000 collection is put under version control, the collection is replaced by a version selector, and a history resource is created to contain versions for that collection. The only bindings captured by a collection version are those to version-controlled resources. This not only preserves standard versioning semantics (a version of a collection should not be modifiable), but also provides for significant implementation optimizations (version history URL's can be used to capture the state of the collection bindings). A collection version selector MAY contain bindings to unversioned resources, but these bindings are not captured in the collection version history, and can be changed without checking out the collection version selector. This feature is essential for the support of lock null resources, since a lock null resource is a temporary member of a collection that should only exist for the duration of the lock, and should not be captured in the version history of that collection. A SET-TARGET or MERGE request can add a binding to collection version selector that has the same name as an existing binding to a non-versioned member. In this case, the existing binding takes precedence and is said to "eclipse" the new binding to a versioned member. If the existing binding is removed (e.g. by a DELETE or MOVE), the binding to the versioned member is exposed. A collection version contains bindings to version histories rather than to versions, so that creating a new version of a resource does not require creating a new version of all the collections that contain that resource, and so that activities in a workspace do not become entangled. For example, suppose a "feature-12" activity created a new version of /x/y/a.html. If a collection version contained bindings to versions of its members, a new version of /x/y would have to be created to contain the new version of /x/y/a.html, and a new version of /x would have to be created to contain the new version of /x/y. Now suppose a "bugfix-47" activity created a new version of /x/z/b.html. Again, a new version of /x/z and a new version of /x would have to be created to contain the new version of /x/y/b.html. But now it is impossible to merge just "bugfix-47" into another workspace without "feature- 12", because the version of /x that contains the desired version of /x/z/b.html also contains version of /x/y/a.html created for "feature-12". But if a collection version instead contains bindings to version histories, changing the version selected by a member of that collection would not require a new version of the collection (the new version is still in the same version history so no new collection version is required), and therefore "feature-12" and "bugfix-47" would not become entangled. Clemm, et al. [Page 35] INTERNET-DRAFT WebDAV Versioning August 9, 2000 In the following example, there are three version histories, named VH14, VH19, and VH24. The versions of VH14 are collections, and version V2 of VH14 has two bindings, one named "a" to VH19, and the other named "b" to VH24. The collection /x is a version selector for VH14 whose target is V2. The bindings of V2 have induced corresponding bindings in /x. In particular, /x/a is a version selector for VH19 (whose target currently is V4), and /x/b is a version selector for VH24 (whose target currently is V8). VH19 +---------+ | +---+ | | | |V4 | | +---+ | | | | | | | | +---+ | | | |V5 | VH14 | +---+ | +---------+ | | | | +---+ | | | | a +---+ | | |V1 | | +---+ | ---->| | Target=V4 | +---+ | a | | |V6 | / +---+ | | ------>| +---+ | / | | / | +---------+ +---+ | +---+ | /x | | Target=V2 | | |V2 | +---+ | +---+ | VH24 \ | | \ | b +---------+ \ b +---+ | | ------>| +---+ | ---->| | Target=V8 | +---+ | | | |V7 | +---+ | | |V3 | | +---+ | | +---+ | | | | +---------+ | | | | +---+ | | | |V8 | | +---+ | | | | | | | | +---+ | | | |V9 | | +---+ | +---------+ 9.6 Mutable Versions Normally, a version cannot be changed and provides a reliable environment for state recovery, change tracking, stable workspaces, and merging. If a server supports mutable versions, the client may request that a checkin should overwrite the version that was Clemm, et al. [Page 36] INTERNET-DRAFT WebDAV Versioning August 9, 2000 checked out, instead of creating a new version. This can be an advantage when a simple history is more important than the benefits provided by an immutable version history, but does introduce a significant performance penalty in distributed environments, because the state of a mutable version cannot be reliably cached. 10 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE This section defines the new resource types and properties introduced by WebDAV advanced versioning. 10.1Version Selector Properties WebDAV advanced versioning introduces the following properties for a version selector. 10.1.1 DAV:version-history (protected) This property contains a version history URL for the version history for this version selector. 10.2Version Properties WebDAV advanced versioning introduces the following properties for a version: 10.2.1 DAV:version-history (protected) This property contains a version history URL for the version history associated with this version. 10.2.2 DAV:activity-set This property contains the URL's for the activities that indicate what lines of descent this version appears on. A server MAY restrict the DAV:activity-set to contain a single activity. 10.2.3 DAV:checkout-fork This property controls the behavior of CHECKOUT when a version already is checked out or has a successor. If the DAV:checkout-fork of a version is DAV:forbidden, a CHECKOUT request MUST fail if it would result in that version appearing in the DAV:predecessor-set or DAV:checked-out property of more than one version or working Clemm, et al. [Page 37] INTERNET-DRAFT WebDAV Versioning August 9, 2000 resource. If DAV:checkout-fork is DAV:discouraged, such a CHECKOUT request MUST fail unless DAV:fork-ok is specified in the CHECKOUT request body. 10.2.4 DAV:checkin-fork This property controls the behavior of CHECKIN when a version already has a successor. If the DAV:checkin-fork of a version is DAV:forbidden, a CHECKIN request MUST fail if it would result in that version appearing in the DAV:predecessor-set of more than one version. If DAV:checkin-fork is DAV:discouraged, such a CHECKIN request MUST fail unless DAV:fork-ok is specified in the CHECKIN request body. 10.2.5 DAV:mutable This property indicates whether the version can be updated by a CHECKIN with DAV:overwrite. PCDATA value: boolean 10.3Working Resource Properties WebDAV advanced versioning introduces the following properties for a working resource: 10.3.1 DAV:version-history (protected) This property contains a version history URL for the version history associated with this working resource. 10.3.2 DAV:merge-set The DAV:merge-set of a working resource contains a version URL for each version that is to be merged into this working resource. Clemm, et al. [Page 38] INTERNET-DRAFT WebDAV Versioning August 9, 2000 10.3.3 DAV:auto-merge-set The DAV:auto-merge-set of a working resource contains a version URL for each version that the server has merged into this working resource. The client should confirm that the merge has been performed correctly before moving a version URL from the DAV:auto- merge-set to the DAV:predecessor-set of a working resource. 10.3.4 DAV:unreserved This property indicates whether the DAV:activity-set of another working resource associated with the version history of this working resource can have an activity that is in the DAV:activity- set property of this working resource. If multiple working resources for a given version history are checked out unreserved into a single activity, only the first CHECKIN will succeed. Before the other working resources can be checked in, the author will have to merge the latest version of that activity into the working resource and then modify the DAV:predecessor-set of that working resource. PCDATA value: boolean 10.3.5 DAV:predecessor-set This property determines the DAV:predecessor-set property of the version that results from checking in this working resource. The order of the DAV:href elements in DAV:predecessor-set MUST be maintained by the server. 10.3.6 DAV:activity-set This property determines the DAV:activity-set property of the version that results from checking in this working resource. 10.3.7 DAV:checkout-fork This property determines the DAV:checkout-fork property of the version that results from checking in this working resource. 10.3.8 DAV:checkin-fork This property determines the DAV:checkin-fork property of the version that results from checking in this working resource. Clemm, et al. [Page 39] INTERNET-DRAFT WebDAV Versioning August 9, 2000 10.3.9 DAV:mutable This property determines the DAV:mutable property of the version that results from checking in this working resource. 10.4Version History Properties The DAV:resourcetype of a version history MUST be DAV:version- history. WebDAV advanced versioning introduces the following properties for a version history: 10.4.1 DAV:version-set (protected) This property contains a version URL for each version of this version history. 10.4.2 DAV:initial-version (protected) This property contains a version URL for the initial version of this version history. 10.4.3 DAV:working-resource-set (protected) This property contains a URL for each working resource whose DAV:version-history property identifies this version history. 10.5Workspace Properties The DAV:resourcetype of a workspace MUST be DAV:collection. WebDAV advanced versioning introduces the following properties for a workspace: 10.5.1 DAV:current-activity-set This property identifies the activities that currently are being performed in this workspace. When a member of this workspace is checked out, if no activity is specified in the checkout request, the DAV:current-activity-set will be used. This allows an activity-unaware client to update a workspace in which activity tracking is required. Clemm, et al. [Page 40] INTERNET-DRAFT WebDAV Versioning August 9, 2000 10.5.2 DAV:parent-workspace (protected) This property identifies the workspace that was used to initialize this workspace. 10.5.3 DAV:child-workspace-set (protected) This property identifies the workspaces whose DAV:parent-workspace identify this workspace. 10.6Collection Properties WebDAV advanced versioning introduces the following properties for a collection: 10.6.1 DAV:baseline-selector (protected) This property contains the URL of a baseline selector that is used to track baselines of this collection. A server MAY automatically assign a DAV:baseline-selector property to a collection when it is created, or a client can use the BASELINE-CONTROL method to request that a baseline selector be created for a specified collection. When the baseline selector of a collection is checked out, the resulting working baseline tracks the target of each version selector that is a member of the collection. When the working baseline is checked in, its state is captured by a new baseline in the baseline history. 10.7Baseline Properties The DAV:resourcetype of a baseline MUST be DAV:baseline. WebDAV advanced versioning introduces the following properties for a baseline. 10.7.1 DAV:version-set (protected) This property contains a version URL for each version selected by the baseline. At most one version of a given version history can be selected by a baseline's DAV:version-set property. Clemm, et al. [Page 41] INTERNET-DRAFT WebDAV Versioning August 9, 2000 10.8Activity Properties The DAV:resourcetype of an activity MUST be DAV:activity. WebDAV advanced versioning introduces the following properties for an activity: 10.8.1 DAV:version-set (protected) This property contains a version URL for each version whose DAV:activity-set property contains this activity. Multiple versions of a single version history can be selected by an activity's DAV:version-set property, but all DAV:version-set versions from a given version history must be on a single line of descent from the initial version of that version history. 10.8.2 DAV:subactivity-set This property contains a URL for each activity that forms a part of the logical change being captured by this activity. An activity behaves as if its DAV:version-set is extended by the DAV:version- set of each activity specified in the DAV:subactivity-set. In particular, the versions in this extended set MUST be on a single line of descent, and when an activity selects a version for merging into a workspace, the latest version in this extended set is the one that will be merged. 11 ADVANCED VERSIONING HEADERS 11.1Workspace The following defines the BNF for the Workspace header: Workspace := "Workspace" ":" URL A Workspace header provides a convenient mechanism for making "workspace relative" requests. When a Workspace header is included in a request, the internal members of that workspace are treated by that request as if they were internal members of "/". For example, the following two requests are equivalent: COPY /doc/index.html HTTP/1.1 Host: www.webdav.org Destination: /newdoc/index.html Workspace: /workspace/mywksp COPY /workspace/mywksp/doc/index.html HTTP/1.1 Host: www.webdav.org Destination: /workspace/mywksp/newdoc/index.html Clemm, et al. [Page 42] INTERNET-DRAFT WebDAV Versioning August 9, 2000 When a Workspace header is included in a request to create a new internal members of "/", a new internal member is added to the workspace instead of "/". For example, the following two requests are equivalent: MKCOL /src HTTP/1.1 Host: www.webdav.org Workspace: /workspace/mywksp MKCOL /workspace/mywksp/src HTTP/1.1 Host: www.webdav.org A request that includes a Workspace header MUST fail if an internal member of the specified workspace has the same name as an internal member of "/". A response to a cacheable request (e.g. GET, PROPFIND) that includes a Workspace header MUST include a Vary header containing "Workspace". 12 ADVANCED VERSIONING AND EXISTING METHODS For any request that includes a Workspace header, the request-URL and every request header URL must be treated as if it were prefixed with the workspace URL specified in the Workspace header. For any method that modifies the bindings of a collection (e.g. DELETE, MOVE, COPY), when that collection is a collection version selector and when the binding is to a version selector, the method MUST fail unless the collection version selector has a DAV:auto- version property. If the collection version selector has a DAV:auto-version property, the collection version selector is checked out, the update is applied to the resulting working collection, and the working collection is checked in. This functionality allows a versioning unaware client to add a version to the collection version history. If any part of the checkout- update-checkin sequence fails, the server state preceding the request MUST be restored. 12.1New Status Codes 4xx (Cannot CHECKOUT without DAV:fork-ok, version already checked out) 4xx (Cannot CHECKOUT, version already checked out) 4xx (Cannot CHECKIN without DAV:fork-ok, version already has a successor) 4xx (Cannot CHECKIN, version already has a successor) Clemm, et al. [Page 43] INTERNET-DRAFT WebDAV Versioning August 9, 2000 12.2OPTIONS When a resource supports advanced versioning, the DAV response header for an OPTIONS request MUST indicate which advanced versioning extensions are supported. The possible extensions are: "property-report", "workspace", "mkworkspace", "workspace-header", "workspace-url-report", "version-selector-url-report", "baseline", "baseline-control", "activity", "mkactivity", "workspace-current- activity", "subactivity", "working-resource-unreserved", "working- resource-predecessor-set", "working-resource-merge-set", "merge", "merge-preview-report", "collection-versioning", "checkout-fork", "checkin-fork", "mutable-version". 12.2.1 Example - OPTIONS >>REQUEST OPTIONS /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 200 OK DAV: 1, 2, core-versioning, workspace, merge Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, CHECKOUT, MERGE 12.3GET Additional Preconditions: If the request URL identifies a version history, an activity, or a baseline, the result is undefined. 12.4PUT Additional Preconditions: If the request URL identifies a version history, an activity, or a baseline, the result is undefined. 12.5DELETE Additional Preconditions: If the request-URL identifies a version selector, the DELETE MUST fail when the collection containing the version selector is a collection version selector, unless DAV:auto-version is set for that collection version selector. Additional Postconditions: Clemm, et al. [Page 44] INTERNET-DRAFT WebDAV Versioning August 9, 2000 If the request-URL identifies a version history, the result is undefined. 12.6MKCOL Additional Postconditions: It is server defined whether the new collection is under version control and whether it is under baseline control. 12.7COPY Additional Preconditions: If the request-URL identifies a version history, the request MUST fail. In order to create another version history with a similar history, the appropriate sequence of VERSION-CONTROL, CHECKOUT, PUT, PROPPATCH, and CHECKIN requests must be made. Additional Postconditions: It is server defined whether any new resource created by COPY is under version control, and whether any new collection created by COPY is under baseline control. If a COPY creates a new version selector at the destination, it MUST create a new version history to be associated with that new version selector. 12.8MOVE Additional Preconditions: If the request-URL identifies a version selector, the request MUST fail when the collection containing the version selector is a collection version selector, unless DAV:auto-version is set for that collection version selector. If the request-URL identifies a version selector, the request MUST fail when the collection containing the destination is a collection version selector, unless DAV:auto-version is set for that collection version selector. If the request-URL identifies a version history, an activity, or a baseline, the request MUST fail. 12.9VERSION-CONTROL Additional Preconditions: Clemm, et al. [Page 45] INTERNET-DRAFT WebDAV Versioning August 9, 2000 If the DAV:version-control request body identifies a version, and if the request-URL is a member of a workspace, then there MUST NOT be another member of that workspace whose DAV:version-history property specifies the version history that contains that version. If the collection containing the request-URL is a collection version selector, the request MUST fail unless DAV:auto-version is set for that collection version selector. Additional Postconditions: If the request body specifies a version, the DAV:version-history of the new version selector identifies the version history that contains that version. If a new version history is created and if the version selector is a member of a workspace, the DAV:activity-set of the initial version of the new version history is the DAV:current-activity-set of that workspace. 12.10 CHECKOUT When activities are supported, a CHECKOUT request MAY specify a request activity set in the request body. If the version selector is a member of a workspace, and no activity is specified in the request body, the DAV:current-activity-set of the workspace is the request activity set. Additional Marshalling: Additional Preconditions: If there is a request activity set, unless DAV:unreserved is specified, another working resource for that version history MUST NOT select an activity in that activity set, and the selected version MUST be a descendant of all other versions of that version history that select that activity. If DAV:unreserved is specified, all other working resources of that version history whose DAV:activity-set contains one of the request activities MUST have a DAV:unreserved property whose value is "T". If the DAV:checkout-fork property of the version being checked out is DAV:forbidden, the request MUST fail if a version contains that version in its DAV:predecessor-set or if a working resource Clemm, et al. [Page 46] INTERNET-DRAFT WebDAV Versioning August 9, 2000 contains that version in its DAV:checkout property. If the value is DAV:discouraged, such a request MUST fail unless DAV:fork-ok is specified in the request. Additional Postconditions: The URL of the working resource is added to the DAV:working- resource-set property of its version history. If a Workspace request header is specified, the version selector at the request-URL MUST be replaced by the new working resource. If the version selector was a baseline selector, the version selector at the request-URL MUST be replaced by the new working resource. If the version selector was a collection, the new working collection MUST contain bindings to all members of that collection version selector. The DAV:predecessor-set property of the new working resource is initialized to be the same version as the DAV:checked-out property. The DAV:activity-set of the new working resource is set as follows: if DAV:new is specified as the DAV:activity-set in the request body, then a new activity created by the server is used; otherwise, if activities are specified in the request body, then those activities are used; otherwise, if the version selector is a member of a workspace and the DAV:current-activity-set of the workspace is set, then those activities are used; otherwise, the DAV:activity- set of the checked out version is used. If DAV:unreserved was specified in the CHECKOUT request body, then the DAV:unreserved property of the working resource MUST be "T". 12.10.1 Example - Advanced CHECKOUT >>REQUEST CHECKOUT /ws/public/foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://repo.webdav.org/act/fix-bug-23 >>RESPONSE Clemm, et al. [Page 47] INTERNET-DRAFT WebDAV Versioning August 9, 2000 HTTP/1.1 201 Created Location: http://www.webdav.org/ws/public/foo.html 12.11 CHECKIN Normally, a CHECKIN request will create a new version. If a server supports mutable versions and if DAV:overwrite is specified, then instead of creating a new version, CHECKIN will overwrite the value of the version identified by the DAV:checked-out property of the working resource. Additional Marshalling: Additional Preconditions: Each version in DAV:predecessor-set of the working resource MUST have the same DAV:version-history value as the working resource. Any version in the version history of the working resource whose DAV:activity-set contains an activity from the DAV:activity-set of the working resource MUST be in the DAV:predecessor-set or an ancestor of a version in the DAV:predecessor-set of the working resource. The DAV:merge-set and DAV:auto-merge-set of the working resource MUST be empty. A CHECKIN request MUST fail if it would cause a version whose DAV:checkin-fork is DAV:forbidden to appear in the DAV:predecessor- set of more than one version. If DAV:checkin-fork is DAV:discouraged, such a CHECKIN request MUST fail unless DAV:fork- ok is specified in the CHECKIN request body. If DAV:overwrite is specified, the request MUST fail unless the DAV:mutable property of the DAV:checked-out version is "T". Additional Postconditions: If the DAV:predecessor-set property of the working resource is non- empty, the DAV:predecessor-set of the new version is set to that value instead of the value of the DAV:checked-out property. The DAV:version-history of the new version is the DAV:version- history of the working resource. The DAV:version-set of the version history is updated to include the new version. Clemm, et al. [Page 48] INTERNET-DRAFT WebDAV Versioning August 9, 2000 If the working resource was a member of a workspace, it is replaced by a version selector whose DAV:target specifies the new version created by the CHECKIN. If the working resource was a collection, the bindings of the working collection are moved to the collection version selector that replaces it. If the working resource was a collection, then the new collection version contains bindings to the version histories of the version selector members of the working collection. If DAV:keep-checked-out is not specified, the URL of the working resource is removed from the DAV:working-resource-set property of its version history. The DAV:activity-set of the new version is the DAV:activity-set of the working resource. For each activity in the DAV:activity-set property of the new version, a version URL for the new version is added to the DAV:version-set property of that activity. If DAV:hidden is specified, the DAV:target of the version selector is not changed by the CHECKIN request. If DAV:overwrite is specified, a new version is not created, but instead the content and properties of the working resource replace those of the DAV:checked-out version. 12.12 UNCHECKOUT Additional Postconditions: The URL of the working resource is removed from the DAV:working- resource-set property of its version history. If the working resource is a member of a workspace, it is replaced by a version selector whose DAV:version-history is that of the working resource, and whose DAV:target is the DAV:checked-out version of the working resource. .If the request-URL identifies a working collection, then the private bindings of the working collection are moved to the collection version selector that replaces it. 12.13 SET-TARGET Additional Postconditions: Clemm, et al. [Page 49] INTERNET-DRAFT WebDAV Versioning August 9, 2000 If the request-URL identifies a baseline selector for a collection, then the target of each version selector that is a member of that collection is modified to be the version selected by that baseline. If the SET-TARGET request modifies the DAV:target of a collection version selector, then all bindings in that collection version selector to version selectors are replaced by the bindings specified by the new target. In particular, bindings are deleted for version selectors whose version histories are not a member of the new target version, bindings are renamed for version selectors whose version histories have been renamed in the new target version, and bindings are created to version selectors whose version histories have been added to the new target version. If a new binding identifies a version selector that was not previously a member of that workspace, then a new version selector is created whose DAV:target is the initial version of that version history. 13 ADVANCED VERSIONING METHODS 13.1MKWORKSPACE A MKWORKSPACE request creates a new workspace resource. A server may restrict workspace creation to a particular collection, but a client can determine the location of this collection with a repository REPORT (see section 14.2). The MKWORKSPACE request body can be used to initialize the workspace with version selectors whose targets are the versions of a specified baseline or the version selector targets of another specified workspace. If a MKWORKSPACE request fails, the server state preceding the request MUST be restored. Marshalling: The request body MUST be a DAV:mkworkspace XML element. The response MUST include a Cache-Control:no-cache header. Preconditions: A resource MUST NOT exist at the Request-URL. If a DAV:parent-workspace is included in the request body, it MUST identify a workspace. Clemm, et al. [Page 50] INTERNET-DRAFT WebDAV Versioning August 9, 2000 If a DAV:baseline is included in the request body, it MUST identify a baseline. Return Status Codes: 201 (Created): The new workspace was successfully created. 403 (Forbidden): The server does not allow the creation of a workspace at the requested location. Postconditions: A new workspace exists at the request-URL. If the request body contains a DAV:parent-workspace element, the DAV:parent-workspace of the new workspace is set to be the specified workspace, and the URL of the new workspace is added to the DAV:child-workspace-set of the specified workspace. For each version selector that is a member of the parent workspace, a new version selector with the same DAV:version-history property will be created in the new workspace. The new version selector will have the same name relative to the new workspace as the existing version selector has relative to the parent workspace. Any collections that are needed in the new workspace to provide the appropriate name for a version selector will be created. 13.1.1 Example - MKWORKSPACE >>REQUEST MKWORKSPACE /ws/public HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 201 Created 13.2MKACTIVITY A MKACTIVITY request creates a new activity resource. If a server restricts the creation of activities to a server-defined collection, a client can determine the location of this collection with a repository REPORT (see section 14.2). Marshalling: The response MUST include a Cache-Control:no-cache header. Preconditions: A resource MUST NOT exist at the request-URL. Clemm, et al. [Page 51] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Return Status Codes: 201 (Created): The new activity was successfully created. Postconditions: A new activity exists at the request-URL. 13.2.1 Example - MKACTIVITY >>REQUEST MKACTIVITY /repo/activity/test-23 HTTP/1.1 Host: www.webdav.org >>RESPONSE HTTP/1.1 201 Created 13.3BASELINE-CONTROL A collection can be placed under baseline control with a BASELINE- CONTROL request. When a collection is placed under baseline control, the DAV:baseline-selector property of the collection is set to identify a new baseline selector. This baseline selector can be checked out and then checked in to create a new baseline for that collection. If a baseline history is specified in the BASELINE-CONTROL request body, the target of the new baseline selector will be the initial version of that baseline history. If no baseline history is specified, a new baseline history is created whose initial version is an empty baseline (i.e. its DAV:version-set is empty). Marshalling: The request body MUST be a DAV:baseline-control XML element. Preconditions: The request-URL MUST identify a collection whose DAV:baseline- control property is empty. If the DAV:baseline-control request body element is not empty, the DAV:href MUST identify a baseline history. If the request-URL identifies a workspace or a member of a workspace, and if the DAV:baseline-control element identifies a baseline history, then there MUST NOT be another member of that workspace whose DAV:baseline-selector property identifies a baseline selector for that baseline history. Clemm, et al. [Page 52] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Return Status Codes: 200 (OK): The collection was successfully placed under baseline control. Postconditions: A new baseline selector resource is created and associated with the baseline history specified in the DAV:baseline-control request body element. If no baseline history is specified in the request body, a new baseline history with an empty initial version is created at a server-defined URL. The DAV:baseline-selector of the collection identifies the new baseline selector. The DAV:target of the new baseline selector identifies the initial baseline of the baseline history. 13.3.1 Example - BASELINE-CONTROL >>REQUEST BASELINE-CONTROL /src HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://repo.webdav.org/his/22 >>RESPONSE HTTP/1.1 201 Created 13.4MERGE The MERGE method performs a logical merge of a specified version into a specified version selector or working resource. In general, a MERGE request specifies a set of versions (the "request versions") and a collection of version selectors and working resources (the "merge destination"), and the MERGE method is responsible for determining which version selector or working resource in that collection (if any) should be the destination of each request version. If the request URL identifies a version, that version is the request version. If the request URL identifies a version selector, and a Target- Selector request header is specified, the version selected by that Clemm, et al. [Page 53] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Target-Selector is the request version; otherwise the target of that version selector is the request version. If the request-URL identifies a collection and a Depth:infinity header is specified, the target of each version selector in that collection is a request version. If the request URL identifies a baseline, each version selected by that baseline is a request version. If the request URL identifies an activity, then for each version history containing a version selected by that activity, the latest version selected by that activity is a request version. Note that the versions selected by an activity are the versions in its DAV:version-set unioned with the versions selected by the activities in its DAV:subactivity-set. For each request version, the server determines the "merge destination" for that request version. The merge destination is the member of the destination collection that is a version selector or working resource whose DAV:version-history is the same as that of the request version. If a request version has no merge destination, that request version is ignored by the MERGE. Marshalling: The request body MUST be a DAV:merge element. The request MUST include a Destination header. The request MAY include a Depth header. The response body MUST contain a DAV:merge-response element. The response MUST include a Cache-Control:no-cache header. Preconditions: The request-URL MUST NOT identify a working resource. If the request-URL identifies a collection, the collection MUST NOT have a member that is a working resource. The Destination header MUST identify a version selector, a working resource, or a collection. If the MERGE request modifies a write-locked version selector or working resource, the request MUST include the appropriate lock token. Clemm, et al. [Page 54] INTERNET-DRAFT WebDAV Versioning August 9, 2000 The checkouts performed to resolve conflicts MUST NOT violate any of the pre-conditions of the CHECKOUT operation. Response Status Codes: 200 (OK): The merge was performed. 2xx (Partial Merge): Only part of the requested merge could be performed. Postconditions: The result of a merge depends on the relationship between the request version and it's merge destination. If the merge destination is a working resource, the request version is added to the DAV:merge-set of the working resource. If the merge destination is a version selector whose target is a descendant of the request version, the merge destination is unaffected by the MERGE. If the merge destination is a version selector whose target is an ancestor of the request version, the DAV:target of the merge destination is modified to select the request version. The merge destination URL MUST appear in the DAV:update-set. If the merge destination is a version selector whose target is neither a descendant nor an ancestor of the request version, the merge destination is checked out and the DAV:merge-set of the new working resource is set to contain the request version. The merge destination URL MUST appear in the DAV:update-set. If a request version has no merge destination, the version URL of the request version MUST appear in the DAV:ignored-set. If DAV:no-auto-merge is specified in the request body, the request MUST NOT set or modify the DAV:auto-merge-set property of any working resource, including ones created by the MERGE request. 13.4.1 Example - MERGE >>REQUEST MERGE /act/fix-parser-bug HTTP/1.1 Host: repo.webdav.org Destination: http://www.webdav.org/ws/public Content-Length: 0 >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Clemm, et al. [Page 55] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Content-Length: xxxx http://www.webdav.org/ws/public/src/parse.c http://www.webdav.org/ws/public/src/inc/parse.h http://www.webdav.org/ws/public/doc/parse.html 14 ADVANCED VERSIONING REPORTS Advanced versioning introduces the following reports (the REPORT method is defined in section 6.7). 14.1DAV:property-report Many properties consist of a set of one or more DAV:href elements. The DAV:property-report provides a mechanism for retrieving in one request the properties from the resources identified by those DAV:href elements. The elements of a DAV:property-report identify which properties of a resource are to be reported. If a property element is empty, then just the value of that property is returned. If a property element contains a list of properties, then the specified properties of each resource identified by a DAV:href in the specified property is returned as well. The property elements in the nested property lists can in turn contain property lists, so that multiple levels of DAV:href expansion can be requested. The response body of a DAV:property-request is a DAV:multistatus element as returned by a PROPFIND request. If the DAV:property- report indicates that each DAV:href in a particular property value is to be expanded, the DAV:href element that normally would be returned by PROPFIND is replaced by a DAV:response element that contains those properties. 14.1.1 Example - DAV:property-report This example describes how to query a version selector to determine the DAV:creator-display-name and DAV:activity-set of every version in the version history of that version selector. Clemm, et al. [Page 56] INTERNET-DRAFT WebDAV Versioning August 9, 2000 >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.webdav.org/foo.html http://repo.webdav.org/his/23 http://repo.webdav.org/his/23/rev/1 Fred http://repo.webdav.org/act/fix-parser- bug HTTP/1.1 200 OK http://repo.webdav.org/his/23/rev/2 Clemm, et al. [Page 57] INTERNET-DRAFT WebDAV Versioning August 9, 2000 Sally http://repo.webdav.org/act/add-refresh- cmd HTTP/1.1 200 OK HTTP/1.1 200 OK HTTP/1.1 200 OK 14.2DAV:repository-report Often a versioning implementation requires that workspaces and activities be located in server specified collections. When such a constraint exists, the DAV:repository-report can be used to determine the URL's of these collections. A DAV:repository-report response is a DAV:repository-set element that contains a DAV:href for each server-defined collection in which the specified type of resource can be located. Since different servers can control different parts of the URL namespace, the value of a DAV:repository response will depend on the request- URL. A server MAY allow the client to create sub-collections in the collections specified in the DAV:repository-set. The collections specified in the DAV:repository-set MAY be located on different hosts from the request-URL and each other. 14.3DAV:workspace-url-report The DAV:workspace-url-report identifies the longest prefix of the request-URL that identifies a workspace (if any). If no prefix of the request-URL identifies a workspace, a 404 response status is returned. 14.3.1 Example - DAV:workspace-url-report >>REQUEST Clemm, et al. [Page 58] INTERNET-DRAFT WebDAV Versioning August 9, 2000 REPORT /ws/public/myCollection/foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.webdav.org/ws/public 14.4DAV:baselined-collection-report This report can be applied to a workspace, and lists all collections whose DAV:baseline-selector property is set. The response body of a DAV:baselined-collection-report MUST be a DAV:baselined-collection-set element. 14.4.1 Example - DAV:baselined-collection-report >>REQUEST REPORT /ws/public HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.webdav.org/ws/public/src http://www.webdav.org/ws/public/doc/help Clemm, et al. [Page 59] INTERNET-DRAFT WebDAV Versioning August 9, 2000 14.5DAV:merge-preview-report A merge preview describes the changes that would result if the versions specified by the request-URL were merged into the destination workspace. The destination workspace is specified in a Destination request header. A DAV:merge-preview-report response contains a DAV:merge-preview- response element, which contains the list of version selectors and working resources that would be modified by the merge, and the list of versions ignored by the merge. The DAV:conflict element contains the URL of a version selector or working resource that requires a merge. It also contains a DAV:common-ancestor for the conflict, and two DAV:contributor elements for the conflict. The DAV:common-ancestor element contains a version URL for a version that is a common ancestor of all the DAV:contributor elements for a particular conflict. The first DAV:contributor element contains a version URL for the version selected by the workspace. The remaining DAV:contributor elements identify the version selected by the request-URL. The DAV:update element contains the URL of a version selector whose target would change as a result of the merge, and contains the version URL for the new target. The DAV:ignored-set element contains the version URL's of each version that would be ignored by the merge. Response Status Codes: 200 (OK): The merge was performed. 2xx (Partial Merge): Only part of the requested merge could be performed. 14.5.1 Example - DAV:merge-preview-report >>REQUEST Clemm, et al. [Page 60] INTERNET-DRAFT WebDAV Versioning August 9, 2000 REPORT /act/fix-it HTTP/1.1 Host: repo.webdav.org Destination: http://www.webdav.org/ws/public Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.webdav.org/ws/public/foo.html http://repo.webdav.org/his/23/rev/18 http://repo.webdav.org/his/23/rev/42 http://repo.webdav.org/his/23/rev/56 http://www.webdav.org/ws/public/bar.html http://www.repo/his/42/rev/3 14.6DAV:compare-report A DAV:compare-report identifies the differences between the resource identified by the request-URL (base) and the resources specified in the body of the request (contributors). The comparison is carried out transitively on any children of the resources according to the value of the Depth header. If the Depth header is not specified, the value infinity is assumed. Resources appearing in a contributor but not in the base are described by DAV:added elements, resources appearing in the base but not a contributor are described by DAV:deleted elements, and resources appearing in both base and contributor but having different states are described by DAV:changed elements. Resource content comparison is not specified, though servers MAY provide it. A DAV:compare-report contains the URL's of the resources to be compared with the resource identified by the request URL. Clemm, et al. [Page 61] INTERNET-DRAFT WebDAV Versioning August 9, 2000 The body of DAV:compare-report response is a DAV:comparison element, which contains DAV:added, DAV:deleted, and DAV:changed elements. For example, if a DAV:compare-report is applied to two baselines, the DAV:compare-report response will contain the versions that are selected by one baseline but not the other. A DAV:added element identifies something that appears in a particular contributor resource but not in the base. A DAV:deleted element identifies something that appears in the base resource but not in a particular contributor. A DAV:changed element identifies information that is in both the base and the contributor but that has changed in some way. For example, when two baselines are being compared, a DAV:changed element will identify a version history if the baselines select different versions of that version history. 14.6.1 Example - DAV:compare-report >>REQUEST REPORT /myCollection HTTP/1.1 Host: www.foo.com Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.foo.com/myOtherCollection >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.foo.com/myOtherCollection http://www.foo.com/myOtherCollection/foo.html Clemm, et al. [Page 62] INTERNET-DRAFT WebDAV Versioning August 9, 2000 http://www.foo.com/myCollection/bar.html 14.6.2 Example - DAV:repository-report >>REQUEST REPORT /myCollection HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://repo.webdav.org/act 14.7DAV:current-workspace-report This report can be applied to an activity, and lists the URL of each workspace whose DAV:current-activity-set contains the specified activity. 14.7.1 Example - DAV:current-workspace-report >>REQUEST REPORT /act/fix-bug-23 HTTP/1.1 Host: repo.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Clemm, et al. [Page 63] INTERNET-DRAFT WebDAV Versioning August 9, 2000 >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.webdav.org/ws/public 14.8DAV:version-selector-url-report The request URL of this report MUST be a version URL, and the result is a URL of a version selector whose target has the same DAV:version-history value as that version. The request MAY specify the URL of a workspace, in which case the version selector MUST be a member of that workspace. If an appropriate version selector is not visible in the specified workspace, a "404 (Not Found)" response status is returned. 14.8.1 Example - DAV:version-selector-url-report >>REQUEST REPORT /his/23/rev/173 HTTP/1.1 Host: repo.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.webdav.org/ws/public >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.webdav.org/ws/public/mycollection/test.html 15 INTERNATIONALIZATION CONSIDERATIONS To be supplied. Clemm, et al. [Page 64] INTERNET-DRAFT WebDAV Versioning August 9, 2000 16 SECURITY CONSIDERATIONS For security reasons, a LABEL request MAY report only a subset of the labels that select this version. 17 SCALABILITY To be supplied. 18 AUTHENTICATION Authentication mechanisms defined in WebDAV will also apply to WebDAV Versioning. 19 IANA CONSIDERATIONS This document uses the namespace defined by [RFC2518] for XML elements. All other IANA considerations mentioned in [RFC2518] are also applicable to WebDAV Versioning. 20 INTELLECTUAL PROPERTY The following notice is copied from RFC 2026, section 10.4, and describes the position of the IETF concerning intellectual property claims made against this document. The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use other technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the procedures of the IETF with respect to rights in standards- track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Clemm, et al. [Page 65] INTERNET-DRAFT WebDAV Versioning August 9, 2000 21 ACKNOWLEDGEMENTS This protocol is the collaborative product of the Delta-V design team: Jim Amsden (IBM, DeltaV Chair), Geoffrey Clemm (Rational), Bruce Cragun (Novell), Jim Doubek (Macromedia), David Durand (INSO), Tim Ellison (OTI), Henry Harbury (Merant), Chris Kaler (Microsoft), Jeff McAffer (OTI), Bradley Sergeant, and Jim Whitehead (UC Irvine). We would like to acknowledge the foundation laid for us by the authors of the WebDAV and HTTP protocols upon which this protocol is layered, and the invaluable feedback from the WebDAV and DeltaV working groups. 22 INDEX To be supplied. 23 REFERENCES [RFC2026] S.Bradner, "The Internet Standards Process", Harvard, 1996, . [RFC2119] S.Bradner, "Key words for use in RFCs to Indicate Requirement Levels", Harvard, 1997, . [RFC2396] T.Berners-Lee, R.Fielding, L.Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", MIT, U.C. Irvine, Xerox, 1998, . [RFC2518] Y. Goland, E.Whitehead, A.Faizi, S.R.Carter, D.Jensen, "HTTP Extensions for Distributed Authoring - WEBDAV", Microsoft, U.C.Irvine, Netscape, Novell, 1999 . [RFC2616] R.Fielding, J.Gettys, J.C.Mogul, H.Frystyk, L.Masinter, P.Leach, and T.Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, U.C.Irvine, Compaq,Xerox,Microsoft, MIT/LCS, 1999, . [Binding] J.Slein, E.Whitehead, J.Davis, G.Clemm, C.Fay, J.Crawford, T.Chihaya, "WebDAV Bindings", Xerox, U.C.Irvine, CourseNet, Rational, FileNet, DataChannel, 1999, [Goals] J.Amsden, C.Kaler, J.Stracke, "Goals for Web Versioning", IBM, Microsoft, Netscape, 1999, Clemm, et al. [Page 66] INTERNET-DRAFT WebDAV Versioning August 9, 2000 24 AUTHORS' ADDRESSES Geoffrey Clemm Rational Software 20 Maguire Road, Lexington, MA 02421 Email: geoffrey.clemm@rational.com Jim Amsden IBM 3039 Cornwallis, Research Triangle Park, NC 27709 Email: jamsden@us.ibm.com Christopher Kaler Microsoft One Microsoft Way, Redmond, WA 90852 Email: ckaler@microsoft.com Jim Whitehead University of California, Irvine Irvine, CA 92697 Email:ejw@ics.uci.edu 25 APPENDICES 26 OVERWRITE HEADER 27 OPEN ISSUES AND PENDING CHANGES The following list identifies open issues and pending changes against this document: . Add a "mandatory" attribute that says all these elements "MUST" be recognized or the request MUST fail. . Move the Response-Status information into the Precondition clauses (i.e. associate a status with each precondition indicating the status returned when that precondition is violated). Do a consistency pass making the use of status returns uniform. . Add goals/motivation paragraph to the introduction (like WebDAV/Mime/HTTP intros) . Define marshalling of labels in XML and more on marshalling in headers (esp. white space) . Define labels as being case-preserving . Add comment text for every example Clemm, et al. [Page 67] INTERNET-DRAFT WebDAV Versioning August 9, 2000 . Replace "server state restored" with something more specific/constrained . Extend the Overwrite header to take an "update" value. This means that the Destination should be updated rather than being deleted and a new resource created. . Indicate that a server can place versioning metadata on either the same server as the version selector, or on a different server, so a client should be prepared for either. . Mention that: if that label in a Target-Selector identifies no version of that version selector, a 4xx (No Version Selected) response status MUST be returned. . Add table that indicates what headers are supported by which methods. Clemm, et al. [Page 68]