INTERNET-DRAFT Geoffrey Clemm, Rational Software draft-ietf-deltav-versioning-05 Jim Amsden, IBM Chris Kaler, Microsoft Jim Whitehead, U.C. Irvine Expires December 19, 2000 June 19, 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, - Activity and workspace management, - URL namespace versioning. Clemm, et al. [Page 1]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Table of Contents 1 INTRODUCTION...........................................5 1.1 Relationship to DAV...................................6 1.2 Terms.................................................6 1.3 Notational Conventions................................7 2 WEBDAV VERSIONING SEMANTICS............................8 2.1 Creating and Modifying a Versioned Resource...........8 2.2 Changing the Target of a Versioned Resource...........8 2.3 Labeling a Revision...................................9 3 VERSIONING PROPERTIES BY RESOURCE TYPE.................9 3.1 Common Property Values................................9 3.1.1 boolean Syntax....................................9 3.1.2 label Syntax......................................9 3.1.3 date-time Syntax..................................9 3.1.4 href XML Element..................................9 3.2 Resource Properties..................................10 3.2.1 DAV:creator-displayname..........................10 3.2.2 DAV:comment......................................10 3.3 Versioned Resource Properties........................10 3.3.1 DAV:default-target (protected)...................10 3.3.2 DAV:auto-version.................................10 3.4 Revision Properties..................................10 3.4.1 DAV:revision (protected).........................11 3.4.2 DAV:predecessor-set (protected)..................11 3.4.3 DAV:checkin-date (protected).....................11 3.5 Working Resource Properties..........................11 3.5.1 DAV:checked-out (protected)......................11 4 VERSIONING HEADERS....................................11 4.1 Target-Selector......................................11 5 VERSIONING AND EXISTING METHODS.......................12 5.1 New Status Codes.....................................12 5.2 OPTIONS..............................................12 5.2.1 Example - OPTIONS................................12 5.3 GET..................................................13 5.4 PUT..................................................13 5.5 PROPFIND.............................................13 5.6 PROPPATCH............................................13 5.7 DELETE...............................................13 5.8 COPY.................................................13 5.9 MOVE.................................................14 5.10 LOCK...............................................14 6 VERSIONING METHODS....................................14 6.1 VERSION..............................................14 6.1.1 Example - VERSION................................15 6.2 CHECKOUT.............................................15 6.2.1 Example - CHECKOUT...............................16 6.3 CHECKIN..............................................16 Clemm, et al. [Page 2]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 6.3.1 Example - CHECKIN................................17 6.4 UNCHECKOUT...........................................17 6.4.1 Example - UNCHECKOUT.............................18 6.5 SET-TARGET...........................................18 6.5.1 Example - SET-TARGET.............................19 6.6 LABEL................................................19 6.6.1 Example - Replacing a label......................20 6.6.2 Example - Reporting labels.......................20 6.7 REPORT...............................................21 6.7.1 Example - REPORT.................................21 7 VERSIONING REPORTS....................................22 7.1 DAV:successor-report.................................22 7.1.1 Example - DAV:successor-report...................22 7.2 DAV:checkout-report..................................22 7.2.1 Example - DAV:checkout-report....................23 7.3 DAV:latest-checkin-report............................23 7.3.1 Example - DAV:latest-checkin-report..............23 7.4 DAV:revision-tree-report.............................24 7.4.1 Example - DAV:revison-tree-report................24 8 ADVANCED VERSIONING...................................25 8.1 Advanced Versioning Terms............................25 9 ADVANCED VERSIONING SEMANTICS.........................27 9.1 Workspaces...........................................27 9.2 Baselines............................................28 9.3 Activities...........................................28 9.4 Parallel Development and Merging.....................29 9.5 Versioned Collections................................29 9.6 Mutable Revisions....................................30 10 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE......30 10.1 Versioned Resource Properties......................30 10.1.1 DAV:history (protected)..........................30 10.2 Revision Properties................................31 10.2.1 DAV:history (protected)..........................31 10.2.2 DAV:activity.....................................31 10.2.3 DAV:checkout-branch..............................31 10.2.4 DAV:checkin-branch...............................31 10.2.5 DAV:mutable......................................31 10.3 Working Resource Properties........................32 10.3.1 DAV:history (protected)..........................32 10.3.2 DAV:merge-set....................................32 10.3.3 DAV:unreserved...................................32 10.3.4 DAV:predecessor-set, DAV:activity, DAV:checkout-branch, DAV:checkin-branch, DAV:mutable.........................32 10.4 History Resource Properties........................32 10.4.1 DAV:revision-set (protected).....................32 10.4.2 DAV:initial-revision (protected).................32 10.4.3 DAV:working-resource-set (protected).............33 10.4.4 DAV:versioned-bindings (protected)...............33 10.5 Workspace Properties...............................33 10.5.1 DAV:current-activity.............................33 Clemm, et al. [Page 3]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 10.5.2 DAV:parent-workspace (protected).................33 10.5.3 DAV:child-workspace-set (protected)..............33 10.5.4 DAV:versioned-baseline (protected)...............34 10.6 Baseline Properties................................34 10.6.1 DAV:revision-set (protected).....................34 10.7 Activity Properties................................34 10.7.1 DAV:revision-set (protected).....................34 10.7.2 DAV:subactivity-set..............................34 11 ADVANCED VERSIONING HEADERS..........................35 11.1 Workspace..........................................35 12 ADVANCED VERSIONING AND EXISTING METHODS.............35 12.1 New Status Codes...................................35 12.2 OPTIONS............................................36 12.2.1 Example - OPTIONS................................36 12.3 GET................................................36 12.4 PUT................................................36 12.5 DELETE.............................................36 12.6 COPY...............................................37 12.7 MOVE...............................................37 12.8 VERSION............................................37 12.8.1 Example - VERSION................................38 12.9 CHECKOUT...........................................38 12.9.1 Example - Advanced CHECKOUT......................39 12.10 CHECKIN............................................40 12.11 UNCHECKOUT.........................................41 12.12 SET-TARGET.........................................41 13 ADVANCED VERSIONING METHODS..........................42 13.1 MKWORKSPACE........................................42 13.1.1 Example - MKWORKSPACE............................43 13.2 MERGE..............................................43 13.2.1 Example - MERGE..................................45 13.3 UNVERSION..........................................45 13.3.1 Example - UNVERSION..............................46 14 ADVANCED VERSIONING REPORTS..........................46 14.1 DAV:property-report................................46 14.1.1 Example - DAV:property-report....................47 14.2 DAV:workspace-url-report...........................48 14.2.1 Example - DAV:workspace-url-report...............48 14.3 DAV:versioned-resource-url-report..................49 14.3.1 Example - DAV:versioned-resource-url-report......49 14.4 DAV:merge-preview-report...........................49 14.4.1 Example - DAV:merge-preview-report...............50 14.5 DAV:compare-report.................................51 14.5.1 Example - DAV:compare-report.....................51 14.6 DAV:repository-report..............................52 14.6.1 Example - DAV:repository-report..................52 14.7 DAV:current-workspace-report.......................53 14.7.1 Example - DAV:current-workspace-report...........53 15 INTERNATIONALIZATION CONSIDERATIONS..................54 Clemm, et al. [Page 4]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 16 SECURITY CONSIDERATIONS..............................54 17 SCALABILITY..........................................54 18 AUTHENTICATION.......................................54 19 IANA CONSIDERATIONS..................................54 20 INTELLECTUAL PROPERTY................................54 21 ACKNOWLEDGEMENTS.....................................55 22 INDEX................................................55 23 REFERENCES...........................................55 24 AUTHORS' ADDRESSES...................................55 25 APPENDICES...........................................56 26 OVERWRITE HEADER.....................................56 27 OPEN ISSUES AND PENDING CHANGES......................56 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 revisions 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 versioned resource may support only a subset of the advanced versioning capabilities. The advanced versioning capabilities provided by a particular versioned 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. Clemm, et al. [Page 5]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 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 versioned collections relies on the binding model defined by the WebDAV binding extensions [Binding]. 1.2 Terms This draft uses the terms defined in HTTP [RFC2068] 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. Versioned Resource A "versioned resource" is a resource that has been put under version control. A versioned resource MUST be "checked out" in order to modify it. A "versioned resource URL" is a URL chosen by the client to identify a versioned resource. Working Resource A "working resource" is the result of checking out a versioned resource. A "working resource URL" is a URL chosen by the server to identify a particular working resource of a versioned resource. Revision A "revision" is a resource created by "checking in" a working resource. The content and properties of a revision are a copy of the current content and properties of the working resource. A "revision URL" is a URL chosen by the server to identify a particular revision of a versioned resource. Default Target Unless a Target-Selector header is specified, the content and properties displayed by a versioned resource are those of a particular revision of the versioned resource. This revision is called the "default target" of the versioned resource. Revision Label A "revision label" is a string chosen by a client to identify a particular revision of a versioned resource. Initial Revision An "initial revision" is the first revision of a versioned resource. Predecessor, Successor, Ancestor, Descendent Clemm, et al. [Page 6]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 A "predecessor" of a revision is a previous revision that was checked out or merged to create the revision. When a revision is related to another revision by one or more predecessor relations, it is called an "ancestor" of that revision. The inverse of the predecessor and ancestor relations are the "successor" and "descendent" 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 descendent of X. The following diagram illustrates several of the previous definitions. History of Foo.html +----+ Initial Revision ---> | V1 | +----+ | ^ | | +----+ | Label ------> "beta1" | V2 | | Ancestor +----+ | / \ | / \ | +----+ +----+ | V3 | | V4 | +----+ +----+ ^ | | | Predecessor | | | | | +----+ +----+ | | V5 | | V6 | | Descendent +----+ +----+ | | \ / | Successor | \ / v v +----+ | V7 | +----+ 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 7]
INTERNET-DRAFT WebDAV Versioning June 15, 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 Versioned Resource In order to track the history of the content and properties of a versionable resource, it can be put under version control. In order to modify a versioned resource, it must first be checked out. When a versioned resource is checked out, a working resource for that versioned resource is created. The state of the working resource can then be modified by setting its content or properties any number of times. When the working resource is in a state that should be retained, it is checked in to create a new revision in the versioned resource history. The revision that was checked out is remembered as the predecessor of the new revision. Unless the server supports mutable revisions, the content and properties of a revision cannot be modified, but instead, changes appear as descendents of that revision. The following diagram illustrates the checkout/checkin process. ===CHECKOUT==> ===CHECKIN==> Foo.html | Foo.html | Foo.html History | History | History | | +----+ | +----+ | +----+ | V1 | | | V1 | | | V1 | +----+ | +----+ | +----+ | | | | | | | | | | +----+ | +----+ | +----+ | V2 | | | V2 | | | V2 | +----+ | +----+ | +----+ | | | | | | | | | +----+ | +----+ | | WR | | | V3 | | +----+ | +----+ 2.2 Changing the Target of a Versioned Resource Another way to modify the state of a versioned resource is to use a SET-TARGET request to select another revision to be the default target of that versioned resource. The SET-TARGET request will Clemm, et al. [Page 8]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 cause the versioned resource to display the content and properties of the specified revision. 2.3 Labeling a Revision At any time, a revision can be given a client assigned label in order to provide a meaningful name for that revision. A given revision label can be assigned to at most one revision of a given versioned resource, but may be reassigned to another revision at any time. Note that although a given label cannot be applied to two revisions from the same versioned resource, the same label can be given to two revisions from different versioned resources. For certain methods, a Target-Selector request header can be used to make a versioned resource display the content and properties of the revision selected by the Target-Selector label, instead of those of the default target of that versioned resource. 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 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.4href XML Element The href XML element is defined in section 12.3 of [RFC2518]. Clemm, et al. [Page 9]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 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 revision can be used to indicate who created that revision. 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 revision can be used to indicate why that revision was created. 3.3 Versioned Resource Properties WebDAV versioning introduces the following properties for a versioned resource. 3.3.1DAV:default-target (protected) This property contains the revision URL of the revision that is the default target of this versioned resource when no Target-Selector header is specified. <!ELEMENT default-target (href)> This property can be modified by the SET-TARGET method. 3.3.2DAV:auto-version When the DAV:auto-version property of a versioned resource is set, a request that attempts to modify that versioned resource (such as PUT/PROPPATCH) is automatically preceded by a CHECKOUT and automatically followed by a CHECKIN. This allows a versioning- unaware client to add revisions to the history of a versioned resource. <!ELEMENT auto-version (#PCDATA)> PCDATA value: boolean 3.4 Revision Properties WebDAV versioning introduces the following properties for a revision. Clemm, et al. [Page 10]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 3.4.1DAV:revision (protected) This property contains the revision URL for this revision. <!ELEMENT revision (href)> 3.4.2DAV:predecessor-set (protected) This property contains a revision URL for each predecessor of this revision. Except for the initial revision, which has no predecessors, there is either the single predecessor that was checked out to create the revision, or there are the multiple predecessors that were merged to create the revision. <!ELEMENT predecessor-set (href*)> 3.4.3DAV:checkin-date (protected) This property contains the date when the revision selected by the versioned resource was checked in. This property MUST NOT be created by a server that cannot provide a reasonable approximation of the current time. <!ELEMENT checkin-date (#PCDATA)> PCDATA value: date-time 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 revision URL of the revision that defined the initial state of the working resource. <!ELEMENT checked-out (revision)> <!ELEMENT revision (href)> 4 VERSIONING HEADERS 4.1 Target-Selector The following defines the BNF for the Target-Selector header: Target-Selector := "Target-Selector" ":" *LWS label An example of a Target-Selector header is: Target-Selector: released When a method supports the Target-Selector header, if the request- URL identifies a versioned resource and a label is specified in a Target-Selector request header, the request MUST act as if the state of the versioned resource was a copy of the revision identified by that label. If that label identifies no revision of Clemm, et al. [Page 11]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 that versioned resource, a 4xx (No Revision Selected) response status MUST be returned. A Target-Selector header has no affect on a request-URL that does not identify a versioned resource. In particular, it has no affect on a revision URL or a working resource 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 request that includes a Target-Selector header, if the request method supports a Target-Selector header and if the request-URL identifies a versioned resource, the request MUST act as if the state of the versioned resource was a copy of the revision selected by the Target-Selector header. For any method that updates a resource (e.g. PUT, PROPPATCH), when that method is applied to a versioned resource, the method MUST fail unless the versioned resource has a DAV:auto-version property. If the versioned resource has a DAV:auto-version property, the versioned resource 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 add a revision to the history of a versioned resource. 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 Revision Selected): The label specified in a Target- Selector header selects no revision of this versioned resource. 4xx (Cannot modify content or property of a revision) 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 HTTP/1.1 200 OK Clemm, et al. [Page 12]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 DAV: 1, 2, core-versioning Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, VERSION 5.3 GET Additional Marshalling: A Target-Selector request header MAY be specified. 5.4 PUT Additional Preconditions: If the request URL identifies a versioned resource, the PUT MUST fail unless DAV:auto-version is set for that versioned resource. If the request URL identifies a revision, the PUT MUST fail. 5.5 PROPFIND Additional Marshalling: A Target-Selector request header MAY be specified. 5.6 PROPPATCH Additional Preconditions: If the request URL identifies a versioned resource, an attempt to modify a dead property MUST fail unless DAV:auto-version is set for that versioned resource. If the request-URL identifies a revision, the PROPPATCH MUST fail. 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 revision 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. Clemm, et al. [Page 13]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Additional Postconditions: If the request-URL identifies a versioned resource or a revision, it is server defined whether the new resource created at the Destination is a versioned or versionable resource. 5.9 MOVE Additional Preconditions: If the request-URL is a revision 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 A VERSION request can be applied to a versionable resource to put it under version control. The initial version of the versioned resource captures the current state of the versionable resource, and the initial DAV:default-target of the versioned resource is the initial revision. A VERSION response MUST NOT be cached. If a VERSION request fails, the server state preceding the request MUST be restored. Preconditions: The request-URL MUST identify a versionable resource or a versioned resource. Return Status Codes: 200 (OK): The resource is under version control. 405 (Method Not Allowed): The request-URL does not identify a versionable resource. Postconditions: If the request-URL identified a versioned resource at the time of the request, the VERSION request MUST NOT change the state of that versioned resource. If the request-URL identified a versionable resource at the time of the request, a new versioned resource is created at the request- URL, and a copy of the versionable resource is made the initial revision of the new versioned resource. The DAV:revision of the initial revision is a revision URL that identifies this revision, the DAV:predecessor-set is empty, and the DAV:checkin-date is the Clemm, et al. [Page 14]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 current date on the server. The DAV:default-target of the new versioned resource is the initial revision. 6.1.1Example - VERSION >>REQUEST VERSION /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 200 OK 6.2 CHECKOUT A CHECKOUT request can be applied to a versioned resource to create a new working resource. The content and properties of the working resource are a copy of a revision selected by the CHECKOUT request. If a revision is specified in the CHECKOUT request body, that is the selected revision; otherwise, if a revision is selected by a Target-Selector request header, that is the selected revision; otherwise, the default target of the versioned resource is the selected revision. A CHECKOUT response MUST NOT be cached. If a CHECKOUT request fails, the server state preceding the request MUST be restored. Marshalling: If a request body is included, it MUST be a DAV:checkout XML element. <!ELEMENT checkout (revision?)> <!ELEMENT revision (href)> A Target-Selector request header MAY be specified. A Location response header MUST be returned. Preconditions: The request-URL MUST identify a versioned resource. If a revision is specified in the CHECKOUT request body, it MUST be a revision of the versioned resource identified by the request-URL. If a label is specified in a Target-Selector header, it MUST select a revision of the versioned resource identified by the request-URL. If the versioned resource is locked, the lock token MUST be specified in the CHECKOUT request. Response Status Codes: 201 (Created): The server created a new working resource. Clemm, et al. [Page 15]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 405 (Method Not Allowed): The request-URL did not identify a versioned resource. 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 revision. The content and other properties of the working resource are the same as the content and properties of the selected revision, except that it has no DAV:revision, DAV:predecessor-set, or DAV:checkin-date property. 6.2.1Example - CHECKOUT >>REQUEST CHECKOUT /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>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 revision that is a copy of the working resource. A CHECKIN response MUST NOT be cached. 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. <!ELEMENT checkin (keep-checked-out?) > <!ELEMENT keep-checked-out EMPTY> If DAV:keep-checked-out is specified, the versioned resource is immediately checked out again. The request MAY include a Target-Selector header. The response MUST include a Location header. Preconditions: The request-URL MUST identify a working resource. If the versioned resource is write-locked, then the appropriate lock token MUST be included in the request. Response Status Codes: 201 (Created): The revision was successfully created. Clemm, et al. [Page 16]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 405 (Method Not Allowed): The request-URL did not identify a versioned resource. 409 (Conflict): A precondition was violated. Postconditions: A new revision of the versioned resource is created. The DAV:revision of the new revision is set to a server-defined URL. The DAV:predecessor-set of the new revision is set to the DAV:checked-out property of the working resource. The DAV:checkin-date of the new revision is set to the current date on the server. The content and dead properties of the working resource are copied into the new revision. 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 revision URL of the new revision. The DAV:default-target of the versioned resource is set to contain the revision URL of the new revision. The revision URL for the new revision 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. An UNCHECKOUT response MUST NOT be cached. If an UNCHECKOUT request fails, the server state preceding the request MUST be restored. 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. Clemm, et al. [Page 17]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Response Status Codes: 200 (OK): The checkout was successfully cancelled. 405 (Method Not Allowed): The URL did not identify a working resource. 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 versioned resource to change the default target of that versioned resource. A SET-TARGET response MUST NOT be cached. Marshalling: The SET-TARGET request body MUST be a DAV:set-target XML element. <!ELEMENT set-target (label | revision)) <!ELEMENT label (#PCDATA)> <!ELEMENT revision (href)> A Depth header MAY be specified for a SET-TARGET request. Preconditions: The request-URL MUST identify a versioned resource. The DAV:set-target value MUST specify either a label that selects a revision of the request versioned resource or a revision URL that identifies a revision of the versioned resource. If the request-URL is write-locked, the SET-TARGET request MUST include the appropriate lock token. Response Status Codes: 200 (OK): The versioned resource 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 versioned resource. Postconditions: Clemm, et al. [Page 18]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 The DAV:default-target of the versioned resource MUST be set to the specified revision. 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 <?xml version="1.0" encoding="utf-8" ?> <D:set-target xmlns:D="DAV:"> <D:label-name>stable</D:label-name> </D:set-target> >>RESPONSE HTTP/1.1 200 OK 6.6 LABEL A LABEL request can be applied to a revision to modify or list the labels on that revision. If a LABEL request is applied to a versioned resource, the operation is applied to the default target of that versioned resource unless a Target-Selector header is specified. A LABEL response MUST NOT be cached. Marshalling: The request body MUST be a DAV:label element. <!ELEMENT label (add|replace|remove|report)> <!ELEMENT add (label-name)> <!ELEMENT replace (label-name)> <!ELEMENT remove (label-name)> <!ELEMENT report EMPTY> The request MAY include a Target-Selector header. If the request body contains DAV:report, the response body MUST be a DAV:label-name-set element. <!ELEMENT label-name-set (label-name*)> <!ELEMENT label-name (#PCDATA)> PCDATA value: label-name Preconditions: The request-URL MUST identify a revision or a versioned resource. If DAV:add is specified, the specified label MUST NOT currently select a revision of that versioned resource. Clemm, et al. [Page 19]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 If DAV:remove is specified, the specified label MUST select that revision of the versioned resource. Response Status Codes: 200 (OK): The label add, replace, remove, or report was successful. 400 (Bad Request): The body of the request was not valid. 405 (Method Not Allowed): The request-URL did not identify a revision or a versioned resource. Postconditions: If DAV:add or DAV:replace is specified, the specified label selects the revision. If DAV:remove is specified, the specified label no longer selects any revision of the versioned resource. If DAV:report is specified, the labels that select the specified revision are listed in a DAV:label-name-set element in the response body. 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 <?xml version="1.0" encoding="utf-8" ?> <D:label xmlns:D="DAV:"> <D:replace> <D:label-name> released </D:label-name> </D:replace> </D:label> >>RESPONSE HTTP/1.1 200 OK 6.6.2Example - Reporting labels >>REQUEST LABEL /foo.html HTTP/1.1 Host: www.webdav.org Content-type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:label xmlns:D="DAV:"> <D:report/> </D:label> >>RESPONSE HTTP/1.1 200 OK Clemm, et al. [Page 20]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:label-name-set xmlns:D="DAV:"> <D:label-name> stable </D:label-name> <D:label-name> release-2.0 </D:label-name> </D:label-name-set> 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. <!ELEMENT available-report EMPTY> 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. <!ELEMENT report-set (ANY*)> 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 <?xml version="1.0" encoding="utf-8" ?> <D:available-report xmlns:D="DAV:"/> >>RESPONSE HTTP/1.1 200 OK Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:report-set xmlns:D="DAV:"> <D:available-report/> <D:history-report/> Clemm, et al. [Page 21]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 <D:successor-report/> </D:report-set> 7 VERSIONING REPORTS Versioning introduces the following reports (the REPORT method is defined in section 6.6.2). 7.1 DAV:successor-report This report can be applied to a revision or a versioned resource, and lists the revision URL of each revision whose DAV:predecessor- set contains the selected revision. The request MAY include a Target-Selector header. <!ELEMENT successor-report EMPTY> The response body of a DAV:successor-report MUST be a DAV:successor-set element. <!ELEMENT successor-set (href*)> 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 <?xml version="1.0" encoding="utf-8" ?> <D:successor-report xmlns:D="DAV:"/> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:successor-set xmlns:D="DAV:"/> <D:href>http://repo.webdav.org/his/23/rev/2</D:href> <D:href>http://repo.webdav.org/his/23/rev/2.1.1</D:href> </D:successor-set> 7.2 DAV:checkout-report This report can be applied to a revision or a versioned resource, and lists all working resources whose DAV:checked-out property identifies the selected revision. The request MAY include a Target-Selector header. <!ELEMENT checkout-report EMPTY> Clemm, et al. [Page 22]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 The response body of a DAV:checkout-report MUST be a DAV:working- resource-set element. <!ELEMENT working-resource-set (href*)> 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 <?xml version="1.0" encoding="utf-8" ?> <D:checkout-report xmlns:D="DAV:"/> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:working-resource-set xmlns:D="DAV:"/> <D:href>http://repo.webdav.org/ws/1/foo.html</D:href> <D:href>http://repo.webdav.org/ws/3/foo.html</D:href> </D:working-resource-set> 7.3 DAV:latest-checkin-report This report can be applied to a versioned resource, and returns the revision URL of the revision of that versioned resource with the latest DAV:checkin-time. If the versioned resource revisions do not have a DAV:checkin-time property, no revision will be identified. If multiple revisions contain the latest DAV:checkin-time, all those revisions will be identified. <!ELEMENT latest-checkin-report EMPTY> The response body of a DAV:latest-checkin-report MUST be a DAV:revision-set element. <!ELEMENT revision-set (href*)> 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 <?xml version="1.0" encoding="utf-8" ?> <D:latest-checkin-report xmlns:D="DAV:"/> Clemm, et al. [Page 23]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:revision-set xmlns:D="DAV:"/> <D:href>http://repo.webdav.org/his/23/rev/5</D:href> </D:revision-set> 7.4 DAV:revision-tree-report The DAV:revision-tree-report describes all the revisions of a versioned resource in the form of a nested tree of revisions. <!ELEMENT revision-tree-report EMPTY> The response body of a DAV:revision-tree-report MUST be a DAV:revision-tree element. <!ELEMENT revision-tree (revision, creator-displayname?, comment?, checkin-date?, label- set?, predecessor-set?, working-resource-set?, revision-tree*)> A DAV:revision tree element contains a revision URL followed by the DAV:creator-displayname, DAV:comment, DAV:predecessor-set, and DAV:checkin-date properties of that revision, the DAV:label-name- set resulting from a LABEL report for that revision, the DAV:working-resource-set resulting from a DAV:checkout-report for that revision, and a DAV:revision tree for each successor of that revision. A server MAY omit all elements other than DAV:revision for a revision that has previously appeared in the DAV:revision-tree element. This can provide significant space savings when a revision has multiple predecessors. 7.4.1Example - DAV:revison-tree-report >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:revision-tree-report xmlns:D="DAV:"/> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Clemm, et al. [Page 24]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 <?xml version="1.0" encoding="utf-8" ?> <D:revision-tree xmlns:D="DAV:"/> <D:revision> <D:href>http://repo.webdav.org/his/23/rev/1</D:href> </D:revision> <D:creator-displayname>Fred</D:creator-displayname> <D:comment> get it started </D:comment> <D:revision-tree> <D:revision> <D:href>http://repo.webdav.org/his/23/rev/2</D:href> <D:revision/> <D:creator-displayname>Fred</D:creator-displayname> <D:comment> Fix the spelling </D:comment> <D:predecessor-set> <D:href>http://repo.webdav.org/his/23/rev/1</D:href> </D:predecessor-set> </D:revision-tree> <D:revision-tree> <D:revision> <D:href>http://repo.webdav.org/his/23/rev/2.1.1</D:href> </D:revision> <D:creator-displayname>Sally</D:creator-displayname> <D:comment> Translate into French </D:comment> <D:predecessor-set> <D:href>http://repo.webdav.org/his/23/rev/1</D:href> </D:predecessor-set> </D:revision-tree> </D:revision-tree> 8 ADVANCED VERSIONING 8.1 Advanced Versioning Terms History A "history" is a resource that provides access to the metadata associated with a versioned resource, such as the list of revisions and working resources for that versioned resource. A "history URL" is a URL chosen by the server to identify a history resource. Workspace A "workspace " is a collection that contains a set of related versionable resources, versioned resources, and working resources. Baseline A baseline is a resource associated with a workspace that captures the default revision of each versioned resource that is a member of that workspace. The following diagram illustrates a baseline B1.1 of the workspace /WS that selects revision V1 of /WS/A.html, revision V3 of /WS/X/B.html, and revision V5 of /WS/X/C.html. Clemm, et al. [Page 25]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 /WS/A.html /WS/X/B.html /WS/X/C.html History History History +----+ | V2 | +----+ | | +-------------------|-------------------------------+ | | | | +----+ +----+ +----+ Baseline | | | V1 | | V3 | | V5 | B1.1 | | +----+ +----+ +----+ | | | | | +-------------------|------------|------------------+ | | | | +----+ +----+ | V4 | | V6 | +----+ +----+ Merging "Merging" is a mechanism for updating a workspace with a specified set of revisions. For each revision to be merged, the versioned resource in the workspace whose history contains that revision is identified. If the specified revision is a descendent of the default target of the identified versioned resource, the merge changes the default target of the versioned resource to be the specified revision. If the specified revision is an ancestor of the default target of the identified versioned resource, the merge leaves that versioned resource unchanged. If the specified revision is neither a descendent nor an ancestor of the default target of the identified versioned resource, the merge checks out the versioned resource, and the client is then responsible for updating the resulting working resource so that its state corresponds to the logical merge of the specified revision with the checked out revision. Activity An "activity" is a non-versionable resource that selects a set of revisions that are on a single "line of descent", where a line of descent is a sequence of revisions connected by successor relationships. If an activity selects revisions from multiple history resources, the revisions selected in each history resource 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. Revision V5 is the latest revision of Foo.html selected by activity Act-2, and revision V8 is the latest revision of Bar.html selected by activity Act-2. Clemm, et al. [Page 26]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Foo.html History Bar.html History +----+ +----+ Act-1| V1 | Act-1| V6 | +----+ +----+ | | | | +----+ +----+ Act-1| V2 | Act-2| V7 | +----+ +----+ / \ | / \ | +----+ +----+ +----+ Act-1| V3 | Act-2| V4 | Act-2| V8 | +----+ +----+ +----+ | | | | +----+ +----+ Act-2| V5 | Act-3| V9 | +----+ +----+ Branch When a second successor is added to a revision of a versioned resource, this creates a "branch" in the history of the versioned resource. Versioned Collection A "versioned collection" is a versioned resource that tracks properties and bindings of a collection. 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, versioned resources, and working resources. When a versioned resource 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 versioned resource that selects the new revision as its default target. 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. Clemm, et al. [Page 27]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Alternatively, a workspace can be initialized by the state of an existing workspace. In this case, a versioned resource is created in the new workspace corresponding to each versioned resource in the existing workspace, where corresponding versioned resources in different workspaces will share the same history resource. In order to ensure unambiguous merging and baselining semantics, a workspace may contain at most one versioned resources for a given history resource (although a server may support multiple bindings in a workspace to the same versioned resource). In order to expose multiple views of a set of a set of related versioned resources in the URL namespace, multiple workspaces must be used. In order to make a change made to a versioned resource in one workspace visible in another workspace, that versioned resource must be checked in, and then the corresponding versioned resource in the other workspace can be updated to select the new revision. 9.2 Baselines A workspace that contains a large number of versioned resources 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 versioned resource revisions, 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 A common problem is that although a versioned resource may need to have separate lines of development in separate projects, no branching is to be permitted within a project. An "activity" resource provides the mechanism for addressing this problem. When a versioned resource 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 versioned resource revisions associated with an activity are on a single line of descent in the history of that versioned resource. If a project identifies an activity that is to be associated with all revisions created by that project, then all changes made in that project will be on a single line of descent. Another use for activities is to perform several different logical changes in a single workspace, and then selectively merge a subset of those logical changes to other workspaces. Each activity can be used to represents a single logical change, although many resources might need to be modified to effect that single logical change. When a versioned resource is checked out, the author specifies which activity should be associated with a new revision that will be created when that versioned resource is checked in. It is then possible to select a subset of the logical changes for merging into Clemm, et al. [Page 28]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 another workspace, by specifying the appropriate activities in a MERGE request. 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 revisions as the default targets of the corresponding versioned resources in the author's workspace, since this would hide any changes made to those versioned resources in the author's workspace. Instead, the revisions created in another workspace should be "merged" into the author's workspace. The revision history of a versioned resource provides the information needed to determine what should be the result of the merge. In particular, the merge should select whichever revision is later in the line of descent from the initial revision. In case the revisions to be merged are on different lines of descent (neither revision is an ancestor of the other), neither revision should be selected, but instead, a new revision should be created that contains the logical merge of the content and properties of those revisions. The MERGE request can be used to check out each versioned resource with such a conflict, and set the DAV:merge-set property of each new working resource to identify the revisions to be merged. The author is responsible for modifying the content of a working resource so that it represents the logical merge of those revisions, and then adding the revisions 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 Versioned Collections The state of a collection consists of a set of properties and a set of named bindings to the internal members of that collection. A collection in a workspace can be put under version control so that the properties and bindings can be tracked by the revisions of the versioned collection. Normally, only some of the bindings in a versioned collection should be stored in the history of that collection. For example, it is often useful to temporarily store a dynamically derived resource (such as a particular presentation of a compound document) in the same collection as one of the source resources used to produce it, but the binding to that derived resource should not be stored in the collection history since it needs to be recomputed on demand. Another example would be a lock null resource created to reserve a name in a collection. A lock null member of a collection should be a temporary resource that is removed when its timeout Clemm, et al. [Page 29]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 expires or when it is explicitly unlocked, and should not be stored persistently in a revision of that collection. A binding that is stored in the history of a versioned collection is called a "public" binding; a binding that is not stored in the history is called a "private" binding. A simple strategy for defining what bindings are public is to define bindings to versioned resources to be public and to define all other bindings as private. This provides an intuitive model (you put a binding to a particular internal member under version control by versioning that member) and a simple implementation (a binding to a versioned resource can be stored as a binding name and a history URL for that versioned resource). When a SET-TARGET selects a new revision for a versioned collection, the bindings from the new revision replace the bindings from the previously selected revision. If one of the bindings in the new revision has the same name as an existing private binding in that versioned collection, that versioned collection will have two bindings (one private, one public) with the same name. In this case, the private binding takes precedence over the public binding, and the private binding is said to "eclipse" the public binding. When the private binding is removed (e.g. by a DELETE or a MOVE), the public binding will be exposed. 9.6 Mutable Revisions Normally, a revision cannot be changed and provides a reliable environment for state recovery, change tracking, stable workspaces, and merging. If a server supports mutable revisions, the client may request that a checkin should overwrite the revision that was checked out, instead of creating a new revision. This can be an advantage when a simple history is more important than the benefits provided by an immutable revision history, but does introduce a significant performance penalty in distributed environments, because the state of a mutable revision 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.1Versioned Resource Properties WebDAV advanced versioning introduces the following properties for a versioned resource. 10.1.1 DAV:history (protected) This property contains a history URL for the history resource for this versioned resource. <!ELEMENT history (href)> Clemm, et al. [Page 30]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 10.2Revision Properties WebDAV advanced versioning introduces the following properties for a revision: 10.2.1 DAV:history (protected) This property contains a history URL for the history resource associated with this revision. <!ELEMENT history (href)> 10.2.2 DAV:activity This property contains a URL for the activity that indicates the line of descent for this revision. <!ELEMENT activity (href)> 10.2.3 DAV:checkout-branch This property controls the behavior of CHECKOUT when a revision already is checked out or has a successor. If the DAV:checkout- branch of a revision is DAV:forbidden, a CHECKOUT request MUST fail if it would result in that revision appearing in the DAV:predecessor-set or DAV:checked-out property of more than one revision or working resource. If DAV:checkout-branch is DAV:discouraged, such a CHECKOUT request MUST fail unless DAV:branch-ok is specified in the CHECKOUT request body. <!ELEMENT checkout-branch (ok|discouraged|forbidden)> <!ELEMENT ok EMPTY> <!ELEMENT discouraged EMPTY> <!ELEMENT forbidden EMPTY> 10.2.4 DAV:checkin-branch This property controls the behavior of CHECKIN when a revision already has a successor. If the DAV:checkin-branch of a revision is DAV:forbidden, a CHECKIN request MUST fail if it would result in that revision appearing in the DAV:predecessor-set of more than one revision. If DAV:checkin-branch is DAV:discouraged, such a CHECKIN request MUST fail unless DAV:branch-ok is specified in the CHECKIN request body. <!ELEMENT checkin-branch (ok|discouraged|forbidden)> <!ELEMENT ok EMPTY> <!ELEMENT discouraged EMPTY> <!ELEMENT forbidden EMPTY> 10.2.5 DAV:mutable This property indicates whether the revision can be updated by a CHECKIN with DAV:overwrite. <!ELEMENT mutable #PCDATA> Clemm, et al. [Page 31]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 PCDATA value: boolean 10.3Working Resource Properties WebDAV advanced versioning introduces the following properties for a working resource: 10.3.1 DAV:history (protected) This property contains a history URL for the history resource associated with this working resource. <!ELEMENT history (href)> 10.3.2 DAV:merge-set The DAV:merge-set of a working resource contains a revision URL for each revision that is to be merged into this working resource. <!ELEMENT merge-set (href*)> 10.3.3 DAV:unreserved This property indicates whether other working resources associated with the history resource of this working resource can have the same DAV:activity property as this working resource. <!ELEMENT unreserved (#PCDATA)> PCDATA value: boolean 10.3.4 DAV:predecessor-set, DAV:activity, DAV:checkout-branch, DAV:checkin-branch, DAV:mutable These properties determine the values of the corresponding properties of the revision that results from checking in this working resource. 10.4History Resource Properties The DAV:resourcetype of a history resource MUST be DAV:history. WebDAV advanced versioning introduces the following properties for a history resource: 10.4.1 DAV:revision-set (protected) This property contains a revision URL for each revision of this history resource. <!ELEMENT revision-set (href+)> 10.4.2 DAV:initial-revision (protected) This property contains a revision URL for the initial revision of this history resource. Clemm, et al. [Page 32]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 <!ELEMENT initial-revision (href)> 10.4.3 DAV:working-resource-set (protected) This property contains a URL for each working resource whose DAV:history property identifies this history resource. <!ELEMENT working-resource-set (href*)> 10.4.4 DAV:versioned-bindings (protected) This property MUST appear on the history resource for a versioned collection, and indicates whether bindings to versioned resources are being tracked by that history resource. If DAV:versioned- bindings is "F", only properties of the versioned collection are captured in a versioned collection revision. If DAV:versioned- bindings is "T", both properties and bindings to versioned resources are captured in a versioned collection revision. In particular, each versioned resource binding in the versioned collection is captured as a history resource binding in the collection revision. <!ELEMENT versioned-bindings (#PCDATA)> PCDATA value: boolean 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 This property identifies the activity that is currently 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 will be used. This allows an activity- unaware client to update a workspace in which activity tracking is required. <!ELEMENT current-activity (href)> 10.5.2 DAV:parent-workspace (protected) This property identifies the workspace that was used to initialize this workspace. <!ELEMENT parent-workspace (href?)> 10.5.3 DAV:child-workspace-set (protected) This property identifies the workspaces whose DAV:parent-workspace identify this workspace. <!ELEMENT child-workspace-set (href*)> Clemm, et al. [Page 33]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 10.5.4 DAV:versioned-baseline (protected) If baselines are supported for a workspace, the workspace MUST have a DAV:versioned-baseline property. This property contains the URL of a versioned baseline that is used to track baselines of that workspace. When the versioned baseline of a workspace is checked out, the resulting working baseline tracks the default target of each versioned resources that is a member of the workspace. When the working baseline is checked in, its state is captured by a new baseline of the versioned baseline. <!ELEMENT versioned-baseline (href)> 10.6Baseline Properties The DAV:resourcetype of a baseline MUST be DAV:baseline. WebDAV advanced versioning introduces the following properties for a baseline. 10.6.1 DAV:revision-set (protected) This property contains a revision URL for each revision selected by the baseline. At most one revision of a given versioned resource can be selected by a baseline's DAV:revision-set property. <!ELEMENT revision-set (href*)> 10.7Activity Properties The DAV:resourcetype of an activity MUST be DAV:activity. WebDAV advanced versioning introduces the following properties for an activity: 10.7.1 DAV:revision-set (protected) This property contains a revision URL for each revision whose DAV:activity property identifies this activity. Multiple revisions of a single history resource can be selected by an activity's DAV:revision-set property, but all revisions of a given history resource must be on a single line of descent from the initial revision of that history resource. <!ELEMENT revision-set (href*)> 10.7.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:revision-set is extended by the DAV:revision- set of each activity specified in the DAV:subactivity-set. In particular, the revisions in this extended set MUST be on a single line of descent, and when an activity selects a revision for merging into a workspace, the latest revision in this extended set is the one that will be merged. Clemm, et al. [Page 34]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 <!ELEMENT subactivity-set (href*)> 11 ADVANCED VERSIONING HEADERS 11.1Workspace The following defines the BNF for the Workspace header: Workspace := "Workspace" ":" *LWS URL A workspace header provides a convenient mechanism for making "workspace relative" requests. The URL specified in the Workspace header is concatenated with the request-URL to form the effective request-URL, and with each request header URL to form the effective request header URL. 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 A server MUST return a Vary header containing "Workspace" in a response to a cacheable request (e.g. GET, PROPFIND) that includes a Workspace header. 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 versioned collection and when the binding is to a versioned resource, the method MUST fail unless the versioned collection has a DAV:auto-version property. If the versioned collection has a DAV:auto-version property, the versioned collection 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 revision to the versioned collection 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:branch-ok, revision already checked out) 4xx (Cannot CHECKOUT, revision already checked out) Clemm, et al. [Page 35]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 4xx (Cannot CHECKIN without DAV:branch-ok, revision already has a successor) 4xx (Cannot CHECKIN, revision already has a successor) 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: "workspace", "baseline", "merge", "activity", "versioned- collection", and "mutable-revision". 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 history resource, an activity, or a baseline, the result is undefined. 12.4PUT Additional Preconditions: If the request URL identifies a history resource, an activity, or a baseline, the result is undefined. 12.5DELETE Additional Preconditions: If the request-URL identifies a versioned resource, the DELETE MUST fail when the collection containing the versioned resource is a versioned collection, unless DAV:auto-version is set for that versioned collection. Additional Postconditions: If the request-URL identifies a history resource, the result is undefined. Clemm, et al. [Page 36]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 12.6COPY Additional Preconditions: If the request-URL identifies a history resource, the request MUST fail. In order to create another history resource with a similar history, the appropriate sequence of VERSION, CHECKOUT, PUT, PROPPATCH, and CHECKIN requests must be made. 12.7MOVE Additional Preconditions: If the request-URL identifies a versioned resource, the request MUST fail when the collection containing the versioned resource is a versioned collection, unless DAV:auto-version is set for that versioned collection. If the request-URL identifies a versioned resource, the request MUST fail when the collection containing the destination is a versioned collection, unless DAV:auto-version is set for that versioned collection. If the request-URL identifies a history resource, an activity, or a baseline, the request MUST fail. 12.8VERSION If a history resource is specified in the request body, the request-URL MUST identify a null resource, and a new versioned resource associated with the specified history resource is created at the request-URL. If no history resource is specified, a new history resource is allocated for the new versioned resource at a server-defined location. Additional Marshalling: If a request body is included, it MUST be a DAV:version XML element. <!ELEMENT version (href?) > Additional Preconditions: If the DAV:version request body element is not empty, the DAV:href MUST identify a history resource. If the DAV:version request body identifies a history resource, and if the request-URL is a member of a workspace, then there MUST NOT be another member of that workspace whose DAV:history property specifies that history resource. If the collection containing the request-URL is a versioned collection, the request MUST fail unless DAV:auto-version is set for that versioned collection. Additional Return Status Codes: 201 (Created): The server created a new versioned resource. Clemm, et al. [Page 37]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Additional Postconditions: If no history resource is specified in the request body, a new history resource is created at a server-defined URL and a copy of the versionable resource is made the initial revision of that history resource. If the versioned resource is a member of a workspace, the DAV:activity of the initial revision is the DAV:current-activity of that workspace. The DAV:history of the new versioned resource identifies the specified history resource. The DAV:default-target of the new versioned resource identifies the initial revision of the history resource. 12.8.1 Example - VERSION >>REQUEST VERSION /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:version xmlns:D="DAV:"> <D:href>http://repo.webdav.org/his/12</D:href> </D:version> >>RESPONSE HTTP/1.1 201 Created 12.9CHECKOUT When activities are supported, a CHECKOUT request MAY specify a request activity in the request body. If the versioned resource is a member of a workspace, and no activity is specified in the request body, the DAV:current-activity of the workspace is the request activity. Additional Marshalling: <!ELEMENT checkout (revision?, activity?, unreserved?, branch-ok?) > <!ELEMENT revision (href)> <!ELEMENT activity (href|new)> <!ELEMENT new EMPTY> <!ELEMENT unreserved EMPTY> <!ELEMENT branch-ok EMPTY> Additional Preconditions: If there is a request activity, the selected revision MUST be a descendent of all other revisions of that versioned resource that have that activity as their DAV:activity. Clemm, et al. [Page 38]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Unless DAV:unreserved is specified, all other working resources of that history resource whose DAV:activity identifies the request activity MUST have a DAV:unreserved property whose value is "T". If the DAV:checkout-branch property of the revision being checked out is DAV:forbidden, the request MUST fail if a revision contains that revision in its DAV:predecessor-set or if a working resource contains that revision in its DAV:checkout property. If the value is DAV:discouraged, such a request MUST fail unless DAV:branch-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 history resource. If the versioned resource was a member of a workspace, the working resource URL returned in the Location response header MUST be the URL that identified the versioned resource. If the versioned resource was a versioned baseline, the working resource URL returned in the Location response header MUST be the request-URL. If the versioned resource was a collection, the new working collection MUST contain bindings to all members of that versioned collection. The DAV:predecessor-set property of the new working resource is initialized to be the same revision as the DAV:checked-out property. The DAV:activity of the new working resource is set as follows: if DAV:new is specified as the DAV:activity in the request body, then a new activity created by the server is used; otherwise, if an activity is specified in the request body, then that activity is used; otherwise, if the versioned resource is a member of a workspace and the DAV:current-activity of the workspace is set, then that activity is used; otherwise, the DAV:activity of the checked out revision 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.9.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 <?xml version="1.0" encoding="utf-8" ?> <D:checkout xmlns:D="DAV:"> <D:activity> <D:href>http://repo.webdav.org/act/fix-bug-23</D:href> </D:activity> Clemm, et al. [Page 39]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 </D:checkout> >>RESPONSE HTTP/1.1 201 Created Location: http://www.webdav.org/ws/public/foo.html 12.10 CHECKIN Normally, a CHECKIN request will create a new revision. If a server supports mutable revisions and if DAV:overwrite is specified, then instead of creating a new revision, CHECKIN will overwrite the value of the revision identified by the DAV:checked- out property of the working resource. Additional Marshalling: <!ELEMENT checkin (keep-checked-out?, activity?, branch-ok?, hidden?, overwrite?) > <!ELEMENT keep-checked-out EMPTY> <!ELEMENT activity (href, new)> <!ELEMENT branch-ok EMPTY> <!ELEMENT hidden EMPTY> <!ELEMENT overwrite EMPTY> Additional Preconditions: Each revision in DAV:predecessor-set of the working resource MUST have the same DAV:history value as the working resource. Any revision of that versioned resource that has the same DAV:activity value MUST be an ancestor of the working resource. The DAV:merge-set of the working resource MUST be empty. A CHECKIN request MUST fail if it would cause a revision whose DAV:checkin-branch is DAV:forbidden to appear in the DAV:predecessor-set of more than one revision. If DAV:checkin- branch is DAV:discouraged, such a CHECKIN request MUST fail unless DAV:branch-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 revision is "T". Additional Postconditions: If the DAV:predecessor-set property of the working resource is non- empty, the DAV:predecessor-set of the new revision is set to that value instead of the value of the DAV:checked-out property. The DAV:history of the new revision is the DAV:history of the working resource. The DAV:revision-set of the history resource is updated to include the new revision. If the working resource was a member of a workspace, it is replaced by a versioned resource whose DAV:default-target specifies the new revision created by the CHECKIN. Clemm, et al. [Page 40]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 If the working resource was a collection, the bindings of the working collection are moved to the versioned collection that replaces it. If the working resource was a collection, and if DAV:versioned- bindings is set for the history resource associated with that working collection, and if DAV:keep-checked-out is not specified, then the new collection revision contains bindings to the history resources of the versioned resource 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 history resource. The DAV:activity of the new revision is set as follows: if DAV:new is specified as the DAV:activity in the request body, then a new activity created by the server is used; otherwise, if an activity is specified in the request body, then that activity is used; otherwise, if the working resource has a DAV:activity property, that activity is used; otherwise, if the working resource is a member of a workspace and the DAV:current-activity of the workspace is set, then that activity is used; otherwise, the DAV:activity of the checked out revision is used. If an activity is specified in the DAV:activity property of the new revision, a revision URL for the new revision is added to the DAV:revision-set property of that activity. If DAV:hidden is specified, the DAV:default-target of the versioned resource is not changed by the CHECKIN request. If DAV:overwrite is specified, a new revision is not created, but instead the content and properties of the working resource replace those of the DAV:checked-out revision. 12.11 UNCHECKOUT Additional Postconditions: The URL of the working resource is removed from the DAV:working- resource-set property of its history resource. If the working resource is a member of a workspace, it is replaced by a versioned resource whose DAV:history is that of the working resource, and whose DAV:default-target is the DAV:checked-out revision of the working resource. .If the request-URL identifies a working collection, then the private bindings of the working collection are moved to the versioned collection that replaces it. 12.12 SET-TARGET A SET-TARGET request can be applied to a workspace to cause every revision in a specified baseline to be selected by the corresponding versioned resource in that workspace. Clemm, et al. [Page 41]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Additional Marshalling: <!ELEMENT set-target (label | revision | baseline)) <!ELEMENT baseline (href)> Additional Preconditions: If a DAV:baseline element is specified in the request body, the request-URL MUST identify a workspace. Additional Postconditions: If the request-URL identifies a workspace and the request body specifies a baseline, then for each versioned resource in that workspace that is associated with the history resource of a revision selected by that baseline, the DAV:default target of that versioned resource is set to be the revision selected by the baseline. If the SET-TARGET request modifies the DAV:default-target of a versioned collection whose history resource has a DAV:versioned- bindings value of "T", then all bindings in that versioned collection to versioned resources are replaced by the bindings specified by the new default target. In particular, bindings are deleted for versioned resources whose history resources are not a member of the new target revision, bindings are renamed for versioned resources whose history resources have been renamed in the new target revision, and bindings are created to versioned resources whose history resources have been added to the new target revision. If a new binding identifies a versioned resource that was not previously a member of that workspace, then a new versioned resource is created whose DAV:default-target is the initial revision of that history resource. 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.6). The MKWORKSPACE request body can be used to initialize the workspace with the versioned resources from an existing. A MKWORKSPACE response MUST NOT be cached. If a MKWORKSPACE request fails, the server state preceding the request MUST be restored. Marshalling: If a request body is included, it MUST be a DAV:mkworkspace XML element. <!ELEMENT mkworkspace (parent-workspace?)> <!ELEMENT parent-workspace (href)> Preconditions: Clemm, et al. [Page 42]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 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. 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 versioned resource that is a member of the parent workspace, a new versioned resource with the same DAV:history property will be created in the new workspace. The new versioned resource will have the same name relative to the new workspace as the existing versioned resource has relative to the parent workspace. Any collections that are needed in the new workspace to provide the appropriate name for a versioned resource 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.2MERGE A MERGE request performs the logical merge of one or more revisions (the "request revisions") into a specified workspace (the "destination workspace"). If the request URL identifies a revision, that revision is the request revision. If the request URL identifies a versioned resource, and a Target- Selector request header is specified, the revision selected by that Target-Selector is the request revision; otherwise the default target of that versioned resource is the request revision. If a Depth header is specified, all selected revisions are merged. If the request URL identifies a working resource, an error is reported and no merge is performed from that working resource. Clemm, et al. [Page 43]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 If the request URL identifies a baseline, all revisions selected by that baseline are merged into the destination workspace. If the request URL identifies an activity, then for each history resource containing a revision selected by the activity, the latest revision selected by that activity is merged into the destination workspace. Note that the revisions selected by an activity are the union of the DAV:revision-set of that activity with the revisions selected by the activities identified by its DAV:subactivity-set. For each request revision, the server determines the "merge target" for that request revision. The merge target is the member of the destination workspace that is a versioned resource or working resource whose DAV:history is the same as that of the request revision. If a request revision has no corresponding versioned resource or working resource in the destination workspace, that request revision is ignored by the MERGE. The result of a merge depends on the relationship between the request revision and it's merge target. - If the merge target is a working resource, the request revision is added to the DAV:merge-set of the working resource. - If the merge target is a versioned resource whose default target is a descendent of the request revision, the merge target is unaffected by the MERGE. - If the merge target is a versioned resource whose default target is an ancestor of the request revision, the DAV:default-target of the merge target is modified to select the request revision. - If the merge target is a versioned resource whose default target is neither a descendent nor an ancestor of the request revision, the merge target is checked out and the DAV:merge-set of the new working resource is set to contain the request revision. A MERGE response MUST NOT be cached. Marshalling: The request MUST include a Destination request header. The response body MUST contain a DAV:update-set element. <!ELEMENT update-set (href*)> Preconditions: The Destination header MUST identify a workspace. If the MERGE request modifies a write-locked versioned resource or working resource, the request MUST include the appropriate lock token. 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. Clemm, et al. [Page 44]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Postconditions: The specified revisions have been merged into the destination workspace. The versioned resources and working resources that have been modified by the MERGE are identified in the DAV:update-set. 13.2.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" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:update-set xmlns:D="DAV:"> <D:href> http://www.webdav.org/ws/public/src/parse.c </D:href> <D:href> http://www.webdav.org/ws/public/src/inc/parse.h </D:href> <D:href> http://www.webdav.org/ws/public/doc/parse.html </D:href> </D:update-set> 13.3UNVERSION An UNVERSION request can be applied to a versioned resource to take it out of version control. The associated history resource is left unchanged. An UNVERSION response MUST NOT be cached. If an UNVERSION request fails, the server state preceding the request MUST be restored. Preconditions: The request-URL MUST identify a versioned resource. If the parent collection is a versioned collection, it MUST have DAV:auto-version set. Return Status Codes: 200 (OK): The resource is no longer under version control. 405 (Method Not Allowed): The request-URL does not identify a versioned resource. Clemm, et al. [Page 45]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Postconditions: The resource MUST no longer have a DAV:default-target, DAV:history, DAV:revision, DAV:predecessor-set, DAV:checkin-date, DAV:auto- version, or DAV:activity property. The revisions and history resource that were associated with the versioned resource MUST NOT be modified by the UNVERSION request. If the parent collection is a versioned collection with DAV:auto- version set, a new revision of that versioned collection is created that no longer has a binding to the history resource that was associated with the versioned resource. 13.3.1 Example - UNVERSION >>REQUEST UNVERSION /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 200 OK 14 ADVANCED VERSIONING REPORTS Advanced versioning introduces the following reports (the REPORT method is defined in section 6.6.2). 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. <!ELEMENT property-report (ANY*)> 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. Clemm, et al. [Page 46]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 14.1.1 Example - DAV:property-report This example describes how to query a versioned resource to determine the DAV:creator-display-name and DAV:activity of every revision of that versioned resource. >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:property-report xmlns:D="DAV:"> <D:history> <D:revision-set> <D:creator-displayname/> <D:activity/> </D:revision-set> </D:history> </D:property-report> >>RESPONSE HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://www.webdav.org/foo.html</D:href> <D:propstat> <D:prop> <D:history> <D:response> <D:href>http://repo.webdav.org/his/23</D:href> <D:propstat> <D:prop> <D:revision-set> <D:response> <D:href>http://repo.webdav.org/his/23/rev/1<D:href> <D:propstat> <D:prop> <D:creator-displayname>Fred</D:creator- displayname> <D:activity> http://repo.webdav.org/act/fix-parser- bug </D:activity> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> Clemm, et al. [Page 47]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 <D:response> <D:href>http://repo.webdav.org/his/23/rev/2<D:href> <D:propstat> <D:prop> <D:creator-displayname>Sally</D:creator- displayname> <D:activity> <D:href> http://repo.webdav.org/act/add-refresh- cmd </D:href> </D:activity> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> </D:revision-set> </D:prop> </D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> </D:history> </D:prop> </D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> </D:multistatus> 14.2DAV:workspace-url-report The DAV:workspace-url-report identifies the longest prefix of the request-URL that identifies a workspace (if any). <!ELEMENT workspace-url-report EMPTY> If no prefix of the request-URL identifies a workspace, a 404 response status is returned. 14.2.1 Example - DAV:workspace-url-report >>REQUEST REPORT /ws/public/myCollection/foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <DAV:workspace-url-report/> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:href xmlns:D="DAV:"> http://www.webdav.org/ws/public </D:href> Clemm, et al. [Page 48]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 14.3DAV:versioned-resource-url-report The request URL of this report MUST be a revision URL, and the result is a URL of a versioned resource whose default target has the same DAV:history value as that revision. The request MAY specify the URL of a workspace, in which case the versioned resource MUST be a member of that workspace. If an appropriate versioned resource is not visible in the specified workspace, a "404 (Not Found)" response status is returned. <!ELEMENT versioned-resource-url-report (href?)> 14.3.1 Example - DAV:versioned-resource-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 <?xml version="1.0" encoding="utf-8" ?> <D:versioned-resource-url-report xmlns:D="DAV:"> <D:href> http://www.webdav.org/ws/public </D:href> </D:versioned-resource-url-report> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:href xmlns:D="DAV:"> http://www.webdav.org/ws/public/mycollection/test.html </D:href> 14.4DAV:merge-preview-report A merge preview describes the changes that would result if the revisions specified by the request-URL were merged into the destination workspace. The destination workspace is specified in a Destination request header. <!ELEMENT merge-preview-report EMPTY> A DAV:merge-preview-report response contains a DAV:update-preview- set element, which contains the list of versioned resources and working resources that would be modified by the merge. <!ELEMENT update-preview-set (conflict|update)*)> <!ELEMENT conflict (href, common-ancestor, contributor, contributor)> <!ELEMENT common-ancestor (href)> <!ELEMENT contributor(href)> <!ELEMENT update (href, href)> Clemm, et al. [Page 49]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 The DAV:conflict element contains the URL of a versioned resource 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 revision URL for a revision that is a common ancestor of all the DAV:contributor elements for a particular conflict. The first DAV:contributor element contains a revision URL for the revision selected by the workspace. The remaining DAV:contributor elements identify the revision selected by the request-URL. The DAV:update element contains the URL of a versioned resource whose default target would change as a result of the merge, and contains the revision URL for the new default target. Response Status Codes: 200 (OK): The merge was performed. 2xx (Partial Merge): Only part of the requested merge could be performed. 14.4.1 Example - DAV:merge-preview-report >>REQUEST 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 <?xml version="1.0" encoding="utf-8" ?> <D:merge-preview-report xmlns:D="DAV:"/> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:update-preview-set xmlns:D="DAV:"> <D:conflict> <D:href>http://www.webdav.org/ws/public/foo.html</D:href> <D:common-ancestor> <D:href>http://repo.webdav.org/his/23/rev/18</D:href> </D:common-ancestor> <D:contributor> <D:href>http://repo.webdav.org/his/23/rev/42</D:href> </D:contributor> <D:contributor> <D:href>http://repo.webdav.org/his/23/rev/56</D:href> </D:contributor> Clemm, et al. [Page 50]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 </D:conflict> <D:update> <D:href>http://www.webdav.org/ws/public/bar.html</D:href> <D:href>http://www.repo/his/42/rev/3</D:href> </D:update> </D:update-preview-set> 14.5DAV: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. <!ELEMENT compare-report (href+)> 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 revisions that are selected by one baseline but not the other. <!ELEMENT comparison (added, deleted, changed)*> <!ELEMENT added (ANY)> <!ELEMENT deleted (ANY)> <!ELEMENT changed (ANY)> 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 versioned resource if the baselines select different revisions of that versioned resource. 14.5.1 Example - DAV:compare-report >>REQUEST REPORT /myCollection HTTP/1.1 Host: www.foo.com Clemm, et al. [Page 51]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:compare-report xmlns:D="DAV:"> <D:href>http://www.foo.com/myOtherCollection</D:href> </D:compare-report> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:comparison xmlns:D="DAV:"> <D:added> <D:href>http://www.foo.com/myOtherCollection</D:href> </D:added> <D:added> <D:href>http://www.foo.com/myOtherCollection/foo.html</D:href> </D:added> <D:deleted> <D:href>http://www.foo.com/myCollection/bar.html</D:href> </D:deleted> </D:comparison> 14.6DAV: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. <!ELEMENT repository-report (workspace|activity)> <!ELEMENT workspace EMPTY> <!ELEMENT activity EMPTY> 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. <!ELEMENT repository-set (href*)> 14.6.1 Example - DAV:repository-report >>REQUEST REPORT /myCollection HTTP/1.1 Clemm, et al. [Page 52]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:repository-report xmlns:D="DAV:"> <D:activity/> </D:repository-report> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:repository-set xmlns:D="DAV:"> <D:href>http://repo.webdav.org/act</D:href> </D:repository-set> 14.7DAV:current-workspace-report <!ELEMENT current-workspace-report EMPTY> This report can be applied to an activity, and lists the URL of each workspace whose DAV:current-activity selects the specified activity. <!ELEMENT workspace-set (href*)> 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 <?xml version="1.0" encoding="utf-8" ?> <D:current-workspace-report xmlns:D="DAV:"/> >>RESPONSE HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:workspace-set xmlns:D="DAV:"> <D:href>http://www.webdav.org/ws/public</D:href> </D:workspace-set> Clemm, et al. [Page 53]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 15 INTERNATIONALIZATION CONSIDERATIONS To be supplied. 16 SECURITY CONSIDERATIONS For security reasons, a PROPFIND request MAY report only a subset of the labels that select this revision. 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 54]
INTERNET-DRAFT WebDAV Versioning June 15, 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), David Durand (INSO), Tim Ellison (OTI), 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, <http://www.ietf.org/rfc/rfc2026.txt>. [RFC2068] R.Fielding, J.Gettys, J.C.Mogul, H.Frystyk, and T.Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, U.C. Irvine, DEC, MIT/LCS, 1997, <http://www.ietf.org/rfc/rfc2068.txt >. [RFC2119] S.Bradner, "Key words for use in RFCs to Indicate Requirement Levels", Harvard, 1997, <http://www.ietf.org/rfc/rfc2119.txt >. [RFC2396] T.Berners-Lee, R.Fielding, L.Masinter, Uniform Resource Identifiers (URI): Generic Syntax, MIT/LCS, U.C. Irvine, Xerox, 1998, <http://www.ietf.org/rfc/rfc2396.txt>. [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 <http://www.ietf.org/rfc/rfc2518.txt>. [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, <http://www.ietf.org/internet-drafts/draft-ietf-webdav-binding- protocol-01.txt> [Goals] J.Amsden, C.Kaler, J.Stracke, "Goals for Web Versioning", IBM, Microsoft, Netscape, 1999, <http://www.ietf.org/internet- drafts/draft-ietf-webdav-version-goals-01.txt> 24 AUTHORS' ADDRESSES Geoffrey Clemm Rational Software 20 Maguire Road, Lexington, MA 02421 Email: geoffrey.clemm@rational.com Clemm, et al. [Page 55]
INTERNET-DRAFT WebDAV Versioning June 15, 2000 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 . Replace "server state restored" with something more specific/constrained Clemm, et al. [Page 56]
