INTERNET-DRAFT Geoffrey Clemm, Rational Software draft-ietf-deltav-versioning-04 Chris Kaler, Microsoft Expires November 10, 2000 May 10, 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: - Basic versioning with automatic versioning for versioning-unaware clients, - Activity and configuration management, - URL namespace versioning. Clemm, Kaler [Page 1] INTERNET-DRAFT WebDAV Versioning May10, 2000 Table of Contents 1 INTRODUCTION...........................................5 1.1 Relationship to DAV...................................5 1.2 Terms.................................................5 1.3 Notational Conventions................................7 2 WEBDAV VERSIONING SEMANTICS............................7 2.1 Creating and Modifying Versioned Resources............7 2.2 Naming Working Resources: Workspaces..................9 2.3 Naming Revisions: Revision Ids and Revision Labels....9 2.4 Accessing Versioned Resources: Workspace and Revision-Selector Headers...................................................9 3 VERSIONING PROPERTIES BY RESOURCE TYPE.................9 3.1 Common Property Values...............................10 3.1.1 boolean Syntax...................................10 3.1.2 segment Syntax...................................10 3.1.3 date-time Syntax.................................10 3.1.4 href XML Element.................................10 3.1.5 stable href......................................10 3.2 Resource Properties..................................10 3.2.1 DAV:author.......................................10 3.2.2 DAV:comment......................................10 3.3 Versioned Resource Properties........................11 3.3.1 DAV:revision-set (protected).....................11 3.3.2 DAV:initial-revision (protected).................11 3.3.3 DAV:default-revision.............................11 3.3.4 DAV:auto-version.................................11 3.4 Revision Properties..................................11 3.4.1 DAV:revision-id (protected)......................11 3.4.2 DAV:revision (protected).........................12 3.4.3 DAV:predecessor-set (protected)..................12 3.4.4 DAV:successor-set (protected)....................12 3.4.5 DAV:label-set (protected)........................12 3.4.6 DAV:checkin-date (protected).....................13 3.4.7 DAV:workspace-set (protected)....................13 3.4.8 DAV:single-checkout..............................13 3.4.9 DAV:versioned-resource (protected)...............13 3.5 Working Resource Properties..........................13 3.5.1 DAV:workspace (protected)........................13 3.5.2 DAV:predecessor-set (protected)..................13 3.5.3 DAV:checkin-policy...............................14 4 VERSIONING AND EXISTING METHODS.......................14 4.1 Automatic Versioning for Versioning Unaware Clients..14 4.2 New Status Codes for Existing Methods................15 5 NEW WEBDAV METHODS....................................15 5.1 MKRESOURCE...........................................15 5.1.1 Example - MKRESOURCE.............................16 5.2 REPORT...............................................16 5.2.1 DAV:report-request...............................17 Clemm, Kaler [Page 2] INTERNET-DRAFT WebDAV Versioning May10, 2000 5.2.2 DAV:report-response..............................17 5.3 Available REPORT.....................................17 5.3.1 DAV:available-report-request.....................17 5.3.2 DAV:available-report-response....................17 5.3.3 Example - Available REPORT.......................18 5.4 Property REPORT......................................18 5.4.1 DAV:property-report-request......................18 5.4.2 DAV:property-report-response.....................19 5.4.3 Example - Property REPORT........................19 6 VERSIONING METHODS....................................19 6.1 VERSION..............................................19 6.1.1 Example - VERSION................................20 6.2 CHECKOUT.............................................20 6.2.1 Example - CHECKOUT...............................21 6.3 UNCHECKOUT...........................................22 6.3.1 Example - UNCHECKOUT.............................22 6.4 CHECKIN..............................................22 6.4.1 Example - CHECKIN................................23 6.5 LABEL................................................24 6.5.1 Example - LABEL..................................24 7 VERSIONING HEADERS....................................25 7.1 Workspace............................................25 7.2 Revision-Selector....................................25 8 ADVANCED VERSIONING...................................26 8.1 Advanced Versioning Terms............................26 9 ADVANCED VERSIONING SEMANTICS.........................29 9.1 Revision Selection and Workspaces....................29 9.2 Parallel Development, Activities, and Merging........29 9.3 Configurations.......................................30 9.4 Versioned Collections................................30 9.5 Repositories.........................................31 10 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE......31 10.1 Collection Properties..............................31 10.1.1 DAV:default-workspace............................31 10.2 Versioned Resource Properties......................31 10.2.1 DAV:baselines (protected)........................32 10.2.2 DAV:baselines-root (protected)...................35 10.2.3 DAV:repository (protected).......................32 10.3 Revision Properties................................32 10.3.1 DAV:activity.....................................32 10.4 Working Resource Properties........................32 10.4.1 DAV:activity.....................................32 10.5 Workspace Properties...............................32 10.5.1 DAV:working-resource-set (protected).............32 10.5.2 DAV:revision-selection-rule......................33 10.5.3 DAV:no-checkout..................................34 10.5.4 DAV:current-label................................34 10.5.5 DAV:current-activity.............................34 10.6 Activity Properties................................35 Clemm, Kaler [Page 3] INTERNET-DRAFT WebDAV Versioning May10, 2000 10.6.1 DAV:revision-set (protected).....................35 10.6.2 DAV:needed-activity-set..........................35 10.6.3 DAV:workspace-set (protected)....................35 10.7 Configuration Properties...........................35 10.8 Baseline Properties................................35 10.9 Repository Properties..............................36 10.9.1 DAV:versioned-resource-collection (protected)....36 10.9.2 DAV:repository-root (protected)..................36 10.9.3 DAV:activity-collection (protected)..............36 10.9.4 DAV:configuration-collection (protected).........36 11 ADVANCED VERSIONING AND EXISTING METHODS.............36 11.1 LOCK...............................................37 11.2 CHECKOUT...........................................37 11.3 CHECKIN............................................37 12 ADVANCED VERSIONING REPORTS..........................38 12.1 Conflict REPORT....................................38 12.1.1 DAV:conflict-report-request......................38 12.1.2 DAV:conflict-report-response.....................38 12.1.3 Example - Conflict REPORT........................38 12.2 Compare REPORT.....................................39 12.2.1 DAV:compare-report-request.......................39 12.2.2 DAV:compare-report-response......................40 12.2.3 Example - Compare REPORT.........................40 13 ADVANCED VERSIONING METHODS..........................41 13.1 MERGE..............................................41 13.1.1 Example - MERGE..................................42 13.2 BASELINE...........................................42 13.2.1 Example - BASELINE...............................44 14 ADVANCED VERSIONING HEADERS..........................44 14.1 Workspace..........................................44 15 INTERNATIONALIZATION CONSIDERATIONS..................44 16 SECURITY CONSIDERATIONS..............................44 17 SCALABILITY..........................................44 18 AUTHENTICATION.......................................44 19 IANA CONSIDERATIONS..................................44 20 INTELLECTUAL PROPERTY................................45 21 ACKNOWLEDGEMENTS.....................................45 22 INDEX................................................45 23 REFERENCES...........................................45 24 AUTHORS' ADDRESSES...................................46 Clemm, Kaler [Page 4] INTERNET-DRAFT WebDAV Versioning May10, 2000 25 OPEN ISSUES..........................................46 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: basic versioning and advanced versioning. Basic 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 basic versioning functionality MUST be provided by a versioned resource that supports versioning. Advanced versioning provides more sophisticated capabilities such as logical change tracking, configuration 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 may be discovered with an OPTIONS request. This document will first define the terminology, semantics, properties, methods, and headers for basic versioning, and then define the additional terminology, semantics, properties, and methods for advanced versioning. 1.1 Relationship to DAV To maximize interoperability and the use of existing protocol functionality, versioning support is designed as extensions to the WebDAV [RFC2518] and Binding protocols [Binding]. In particular, WebDAV Versioning relies on the resource and property model defined by [RFC2518] and the binding model defined by [Binding]. 1.2 Terms This draft uses the terms defined in [RFC2068] and [RFC2518]. In addition, the following terms are defined: Versionable Resource A "versionable resource" is a resource that can be placed under version control with a VERSION request. Versioned Resource A "versioned resource" is a resource that is under version control. A versioned resource tracks the history of its significant states. To update a resource under version control, it must be checked out and then subsequently checked in. Working Resource Clemm, Kaler [Page 5] INTERNET-DRAFT WebDAV Versioning May10, 2000 A "working resource" is a writeable resource created by applying a CHECKOUT request to a revision of a versioned resource. Workspace A "workspace" is a string chosen by the server to identify a particular working resource of a versioned resource. Revision A "revision" of a versioned resource is a write-protected resource created by applying a CHECKIN request to a working resource. Revision Id A "revision id" is a string chosen by the server to identify a particular revision of a 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 A "predecessor" of a revision is a previous revision that was checked out or merged to create the revision. A successor of a revision is a later revision that has the revision as one of its predecessors. Each revision except for the initial revision has at least one predecessor. The following diagram illustrates several of the previous definitions. Clemm, Kaler [Page 5.1] INTERNET-DRAFT WebDAV Versioning May10, 2000 Versioned -------> Foo.htm Resource +----+ \ Initial Revision ---> | V1 | | +----+ | | | | | +----+ | Label ------> "beta1" | V2 | | +----+ | / \ | / \ | +----+ +----+ | Revision Id ------> V3 | | V4 | | History +----+ +----+ | of ^ | | | Foo.htm Predecessor | | | | | +----+ +----+ | | V5 | | V6 | | +----+ +----+ | | \ / | Successor | \ / | v +----+ | | V7 | | +----+ / Clemm, Kaler [Page 6] INTERNET-DRAFT WebDAV Versioning May10, 2000 Target Whenever a server encounters a versioned resource while it is processing an HTTP request, it acts on the "target" of the versioned resource, rather than on the versioned resource itself. This allows a client to largely ignore the fact that a resource has been placed under version control. Workspace and Version-Selector headers are used to control the target selection for a versioned resource. The "default target" of a versioned resource is the target selected when neither a Workspace nor a Revision-Selector header is specified. 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 up updated with a PROPPATCH request. 2 WEBDAV VERSIONING SEMANTICS 2.1 Creating and Modifying Versioned Resources An unversioned resource that can be put under version control is called a versionable resource. A versionable resource that is put under version control is called a versioned resource. A versioned resource must be checked out before it can be modified. Checking out a versioned resource produces a new resource, called a working resource. A working resource is a modifiable copy of the revision, and is identical to an unversioned resource in all respects other than that it is associated with a particular revision of a particular versioned resource. It may be edited by setting its properties or contents any number of times. When the author is satisfied that the working resource is in a state that should be retained in the versioned resource history, the author checks in the working resource to create a new revision of the Clemm, Kaler [Page 7] INTERNET-DRAFT WebDAV Versioning May10, 2000 versioned resource. The revision that was checked out is the predecessor of the new revision. The following diagram illustrates the checkout/checkin process. ===CHECKOUT==> ===CHECKIN==> Foo.htm | Foo.htm | Foo.htm | | +----+ | +----+ | +----+ | V1 | | | V1 | | | V1 | +----+ | +----+ | +----+ | | | | | v | v | v +----+ | +----+ | +----+ | V2 | | | V2 | | | V2 | +----+ | +----+ | +----+ | | | | | v | v | +----+ | +----+ | | WR | | | V3 | | +----+ | +----+ The use of checkout/checkin and working resources to update a versioned resource addresses the lost update problem by ensuring that each author is updating his or her own working resource rather than a shared resource, and by ensuring that the predecessor of the updated resource is reliably tracked. Authors can use checkout/checkin to register intent to modify a versioned resource similar to the way lock /unlock are used in WebDAV class 2, but the underlying semantics are very different. With lock/unlock, work is serialized and avoiding lost updates depends on clients using the lock/unlock protocol. With checkout/checkin, work can be performed in parallel, and the server prevents lost updates by retaining all saved states (revisions) of the resource. Another distinction is that an update to a locked resource is immediately visible to all clients, while an update to a working resource in a workspace is immediately visible only to clients using that workspace. A server MAY support mutable revisions. Normally, a revision cannot be changed and provides a stable environment for history management, change recovery, merging, and configuration management. A mutable revision is more suitable for situations where versioning is treated more informally, and it is not necessary or desirable to maintain strict version histories, or to guarantee the possibility of backtracking to a previous saved state. If mutable revisions are supported, the author may request that a checkin should overwrite the revision that was checked out, instead of creating a new revision. In this case, the previous state captured by that revision is lost. Servers may choose not to support mutable revisions. Clemm, Kaler [Page 8] INTERNET-DRAFT WebDAV Versioning May10, 2000 2.2 Naming Working Resources: Workspaces Workspaces are used to distinguish a working resource of a versioned resource from other working resources of that versioned resource. A working resource of a versioned resource is given a server assigned workspace when it is created. This workspace acts as an identifier that distinguishes this working resource from all others of the same versioned resource. A workspace does not distinguish working resources from different versioned resources, since the same workspace can be assigned to a working resource of any versioned resource. 2.3 Naming Revisions: Revision Ids and Revision Labels Revision ids and revision labels are used to distinguish a revision of a versioned resource from other revisions of that versioned resource. A revision of a versioned resource is given a server assigned revision id when it is created. This revision id acts as a persistent, immutable identifier distinguishing this revision from all others of the same versioned resource. The revision id cannot be changed, assigned to another revision, or reused. A user may assign revision labels to a revision in order to provide a more meaningful name for the revision. A given revision label can be assigned to at most one revision of a given versioned resource, but may be reassigned to any other revision of the versioned resource at any time. Revision identifiers and revision labels are unique only across a single versioned resource. That is, a revision id or revision label does not distinguish revisions from different versioned resources, since the same revision id or revision label can be applied to a revision of any other versioned resource. 2.4 Accessing Versioned Resources: Workspace and Revision-Selector Headers When a method is applied to a versioned resource, it is applied to the target of that versioned resource. The target can be a working resource of the versioned resource, a revision of the versioned resource, or the versioned resource itself. The Workspace and Revision-Selector headers of the request determine the target. If neither a Workspace or a Revision-Selector header is specified, the target is the DAV:default-revision of the 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. Clemm, Kaler [Page 9] INTERNET-DRAFT WebDAV Versioning May10, 2000 3.1 Common Property Values 3.1.1 boolean Syntax Some properties take a Boolean value. boolean = "F" | "T" 3.1.2 segment Syntax Some properties take a value suitable for use as a segment of a URI. Segment characters are encoded in UTF-8 format, and then when appropriate escaped with the URL segment escaping mechanism defined in section 3.3 of [RFC2396]. 3.1.3 date-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.4 href XML Element The href XML element is defined in section 12.3 of [RFC2518]. 3.1.5 stable href A stable href contains a URL that identifies a resource that cannot be renamed with a MOVE request. 3.2 Resource Properties WebDAV versioning introduces the following properties for a resource: 3.2.1 DAV:author This property is used to track the author of a resource. Different revisions of a versioned resource can have different DAV:author values, indicating who authored that revision. 3.2.2 DAV:comment This property is used to track a brief comment about a resource. Each revision of a versioned resource has its own set of properties, so each revision can be given a DAV:comment appropriate to that revision. Clemm, Kaler [Page 10] INTERNET-DRAFT WebDAV Versioning May10, 2000 3.3 Versioned Resource Properties The DAV:resourcetype of a versioned resource MUST be DAV:versioned- resource-resourcetype. WebDAV versioning introduces the following properties for a versioned resource: 3.3.1 DAV:revision-set (protected) This property identifies the revisions of this versioned resource. Each DAV:revision-set href contains a stable URL. 3.3.2 DAV:initial-revision (protected) This property identifies the initial revision of this versioned resource. The DAV:initial-revision href contains a stable URL. 3.3.3 DAV:default-revision This property identifies the default revision of this versioned resource that will be the target of the versioned resource if no Workspace or Revision-Selector header is specified. Whenever a new revision is created by the automatic CHECKIN resulting from automatic versioning (see the DAV:auto-version property), the DAV:default-revision property is updated to refer to that revision . The DAV:default-revision href contains a stable URL. 3.3.4 DAV:auto-version When the DAV:auto-version property of a versioned resource is set, a request that attempts to modify the state of a revision of that versioned resource without specifying a Workspace or Revision- Selector header (such as PUT/PROPPATCH for a basic resource or a DELETE /MOVE for a collection) is automatically preceded by a CHECKOUT and automatically followed by a CHECKIN. This allows a versioning-unaware client to modify a version-controlled resource. 3.4 Revision Properties WebDAV versioning introduces the following properties for a revision of a versioned resource: 3.4.1 DAV:revision-id (protected) The DAV:revision-id is an identifier assigned to a revision by the server. A revision cannot be given a DAV:revision-id that has been given to any other revision of that versioned resource, even a revision that has been deleted. Clemm, Kaler [Page 11] INTERNET-DRAFT WebDAV Versioning May10, 2000 Value: segment Since implementations are likely to use revision ids in resource naming schemes, a revision id is constrained to be a legal URL segment. Standard URL encoding techniques should provide a server with sufficient flexibility in defining revision id formats. Since a revision id can be specified in a Revision-Selector header, the length of a revision id should be compatible with common header length constraints. 3.4.2 DAV:revision (protected) This property contains a stable URL for this revision. This is a server allocated URL that can be used without a Revision-Selector header to reference this revision. The DAV:revision href contains a stable URL. 3.4.3 DAV:predecessor-set (protected) The DAV:predecessor-set of a revision identifies the revision that was checked out to produce this revision. The DAV:predecessor-set property can identify multiple revisions if the advanced versioning MERGE method is supported. Each DAV:predecessor-set href contains a stable URL. 3.4.4 DAV:successor-set (protected) This property identifies the revisions whose DAV:predecessor-set identify this revision. Each DAV:successor-set href contains a stable URL. 3.4.5 DAV:label-set (protected) This property is used to identify labels that are associated with a specific revision. The value of DAV:label-set is updated with the LABEL method. Value: segment Since revision labels are only exposed to a user as a simple mnemonic tag for selecting a specific revision, embedding advanced XML facilities for character set tagging, character set encoding, and language tagging would not be appropriate. For label applications that are not exposed to a user, the standard URL Clemm, Kaler [Page 12] INTERNET-DRAFT WebDAV Versioning May10, 2000 encoding techniques will provide a client with sufficient flexibility in defining label formats. Since a revision label can be specified in a Revision-Selector header, clients should limit the length of a revision label to be compatible with common header length constraints. 3.4.6 DAV:checkin-date (protected) This property contains the date when the revision was checked in. Value: date-time 3.4.7 DAV:workspace-set (protected) This property identifies the workspaces for the working-resources currently checked out from this revision. Each DAV:workspace-set href contains a stable URL. This property is updated with the CHECKOUT method. 3.4.8 DAV:single-checkout When the DAV:single-checkout property of a revision is true, only one working resource can be checked out from that revision at any time. Value: boolean 3.4.9 DAV:versioned-resource (protected) This property identifies the versioned resource that contains this revision. The DAV:versioned-resource href contains a stable URL. 3.5 Working Resource Properties WebDAV versioning introduces the following properties for a working resource: 3.5.1 DAV:workspace (protected) This property identifies the workspace for this working resource. The DAV:workspace href contains a stable URL. 3.5.2 DAV:predecessor-set (protected) This property identifies the revision that was checked out to create this working resource. Each DAV:predecessor-set href Clemm, Kaler [Page 13] INTERNET-DRAFT WebDAV Versioning May10, 2000 contains a stable URL. The advanced versioning MERGE method can be used to add additional values to this property. 3.5.3 DAV:checkin-policy The DAV:checkin-policy property of a working resource describes any special processing that should be performed when this working resource is checked in. If a PROPPATCH request specifies a DAV:checkin-policy that is not supported by the server, it MUST fail. The following are defined values for DAV:checkin-policy: DAV:new-revision - Create a new revision (the default value). DAV:overwrite - The working resource should be copied into its DAV:predecessor instead of creating a new revision. This CHECKIN will succeed only if the server supports mutable revisions. DAV:keep-checked-out - Create a new revision but do not delete the working resource. The DAV:predecessor-set of the working resource is changed to identify the new revision. 4 VERSIONING AND EXISTING METHODS For most existing HTTP and WebDAV methods, the only change introduced by versioning is instead of applying a method to a versioned resource, the method is applied to the target of that versioned resource. Note that if a method modifies only a binding to a resource and not the resource itself (e.g. DELETE, MOVE, BIND), the method is being applied to the collection containing that binding, so these methods are not affected by versioning unless that collection is under version control. 4.1 Automatic Versioning for Versioning Unaware Clients For methods that update a resource (e.g. PUT, PROPPATCH), when that method is applied to a revision of a versioned resource, the method MUST fail unless the versioned resource has a DAV:auto-version property and no Workspace or Revision-Selector header has been specified. In this case, the revision is checked out, the update is applied to the resulting working resource, and the working resource is checked in. The check-out, update, check-in sequence MUST be performed atomically. This functionality allows a versioning unaware client to update a versioned resource. Clemm, Kaler [Page 14] INTERNET-DRAFT WebDAV Versioning May10, 2000 4.2 New Status Codes for Existing Methods 4xx (No Such Revision): The selected versioned resource does not have the specified revision. 4xx (No Such Working Resource): The selected versioned resource does not have the specified working resource. 5 NEW WEBDAV METHODS WebDAV versioning introduces two new methods, MKRESOURCE and REPORT, which are not specific to versioning but are needed to support the versioning extensions. 5.1 MKRESOURCE The MKRESOURCE method requests the creation of a resource and initialization of its properties. It allows resources other than standard data containers and collections to be created and their properties initialized in one atomic operation. Preconditions: A resource MUST NOT exist at the Request-URL. Request Marshalling: The location of the new resource to be created is specified by the Request-URL. The request body of the MKRESOURCE method MUST consist of the DAV:propertyupdate XML element defined in Section 12.13 of [WebDAV]. Postconditions: If the response status code is 201, a new resource exists at the request-URL. The body of the new resource is empty. The properties of the new resource are as specified by the DAV:propertyupdate request body, using PROPPATCH semantics. If the DAV:propertyupdate does not specify a DAV:resourcetype, the resource will be a standard data container. If the response status code is not 201, then a new resource is not created at the request-URL, and any existing resource at the request-URL is unaffected. Response Marshalling: Responses from a MKRESOURCE request SHOULD NOT be cached, as MKRESOURCE has non-idempotent semantics. The following status codes can be expected in responses to MKRESOURCE request: 201 (Created): The new resource was successfully created. Clemm, Kaler [Page 15] INTERNET-DRAFT WebDAV Versioning May10, 2000 207 (Multi-Status): This response is generated if an error was encountered while initializing the properties of the resource, in which case the response is as defined in Section 8.2.1 of [WebDAV]. 403 (Forbidden): The server does not allow the creation of the requested resource type at the requested location, or the parent collection of the request-URL exists but cannot accept members. 409 (Conflict): A resource cannot be created at the request-URL because the parent collection for the resource does not exist, or because there is already a resource at that request-URL. 423 (Locked): The request-URL is locked and the lock token was not specified in the request. 507 (Insufficient Storage): The server does not have sufficient space to record the state of the resource. 5.1.1 Example - MKRESOURCE MKRESOURCE /repo/worspaces/public HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx >>Response HTTP/1.1 201 Created Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx 5.2 REPORT The REPORT request is an extensible mechanism for obtaining information about resources. This differs from OPTIONS in that the information provided is dynamic. The REPORT method MUST not change the state of any resource managed by the server. This document defines two general purpose reports (DAV:available- report, DAV:property-report) and two advanced versioning reports (DAV:compare-report, DAV:conflict-report). Request Marshalling: The resource that is the target of the report is specified by the request-URL. Clemm, Kaler [Page 16] INTERNET-DRAFT WebDAV Versioning May10, 2000 A Depth header MAY be specified. The request body of the REPORT method MUST consist of a DAV:report- request XML element. Response Marshalling: The response body of the REPORT method MUST consist of a DAV:report-response XML element. The following status codes can be expected in responses to REPORT request: 200 (OK): Generated on successful completion of the requested report. The body of the response is marshaled as a DAV:report- response. 5.2.1 DAV:report-request Describes a report request. 5.2.2 DAV:report-response A DAV:report-response contains an entire report. A response can be for one of the standard reports (reports, conflict, or compare) or for a server-defined report. The form of server-defined requests is not specified. 5.3 Available REPORT The list of reports supported by the resource identified by the request-URL. 5.3.1 DAV:available-report-request 5.3.2DAV:available-report-response A DAV:available-report-response is a sequence of elements identifying the supported reports. 5.3.3Example - Available REPORT >>Request REPORT /myCollection HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Workspace http://www.webdav.org/repo/workspaces/public >>Response HTTP/1.1 200 OK Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Workspace http://www.webdav.org/repo/workspaces/public 5.4 Property REPORT Many properties consist of a set of one or more href elements. The property REPORT provides a mechanism for retrieving in one request the properties from all of the resources identified by those href elements. 5.4.1 DAV:property-report-request (TBD) Clemm, Kaler [Page 18] INTERNET-DRAFT WebDAV Versioning May10, 2000 5.4.2DAV:property-report-response TBD. 5.4.3Example - Property REPORT >>Request REPORT /myCollection HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Workspace http://www.webdav.org/repo/workspaces/public ... >>Response HTTP/1.1 200 OK Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Workspace http://www.webdav.org/repo/workspaces/public ... 6 VERSIONING METHODS 6.1 VERSION The VERSION method can be applied to a versionable resource to produce a new versioned resource whose initial revision is a copy of the versionable resource. Preconditions: The request-URL MUST identify a versionable resource. Request Marshalling: The request-URL specifies a versionable resource. Postconditions: Clemm, Kaler [Page 19] INTERNET-DRAFT WebDAV Versioning May10, 2000 A new versioned resource is created. The initial revision of the new versioned resource is a copy of the versionable resource. The value of the DAV:resourceid of the initial revision is the same as that of the versionable resource. The versionable resource is replaced in its parent collection by the new versioned resource. Response Marshalling: The response MUST contain a Location header containing a stable URL for the new versioned resource. The following status codes can be expected in responses to a VERSION request: 201 (Created): The versioned resource was successfully created. 404 (Not Found): The request-URL did not identify a resource. 405 (Method Not Allowed): The selected resource is not a versionable resource. 6.1.1Example - VERSION >> REQUEST VERSION /file HTTP/1.1 Host: www.webdav.org >> RESPONSE HTTP/1.1 201 Created Host: www.webdav.org Location: http://www.webdav.org/repository/example/vr/183 6.2 CHECKOUT The CHECKOUT method can be applied to a URL whose target is a revision to produce a working resource that is a modifiable copy of that revision. The CHECKOUT response will contain a Workspace header that can be used in subsequent requests on that URL to identify that working resource. A CHECKIN request applied to that working resource can be used to create a new revision of that working resource. Preconditions: The request-URL MUST identify either a revision or a versioned resource whose target is a revision. This is the "selected revision". The versioned resource for the revision is the "selected versioned resource". If the DAV:single-checkout property of the selected revision is set, this revision MUST not be already checked out. Request Marshalling: Clemm, Kaler [Page 20] INTERNET-DRAFT WebDAV Versioning May10, 2000 The request-URL specifies the revision to check out. If the request-URL identifies a versioned resource, the revision to be checked out MAY be specified in a Revision-Selector header. Postconditions: A new working resource that is a copy of the revision is created. The value of the DAV:resourceid of the working resource is the same as that of the revision. The DAV:predecessor-set of the new working resource is set to the selected revision. The DAV:workspace of the new working resource is set to a value selected by the server. The value of DAV:workspace is the "selected workspace". The selected workspace is added to the DAV:workspace-set property of the selected revision. Response Marshalling: Results from a CHECKOUT request MUST NOT be cached as CHECKOUT has non-idempotent semantics. The response MUST contain a Location header containing a stable URL for the new working resource. The following status codes can be expected in responses to a CHECKOUT request: 201 (Created): The working resource was successfully created. 404 (Not Found): The request-URL did not identify a resource. 405 (Method Not Allowed): The selected resource is not a revision or the specified Workspace is invalid. 409 (Conflict): Any other violated pre-condition of the CHECKOUT request. 6.2.1Example - CHECKOUT >> REQUEST CHECKOUT /file HTTP/1.1 Host: www.webdav.org >> RESPONSE HTTP/1.1 201 Created Host: www.webdav.org Workspace: http://www.webdav.org/workspaces/ws-23 Location: http://www.webdav.org/workspaces/ws-23/wr/X143 Clemm, Kaler [Page 21] INTERNET-DRAFT WebDAV Versioning May10, 2000 6.3 UNCHECKOUT The UNCHECKOUT method can be applied to a working resource of a versioned resource to cancel the CHECKOUT and delete the working resource. Preconditions: The target of the request-URL MUST be a working resource. Request Marshalling: The request-URL specifies the working resource. The Workspace header specifies the workspace that contains the selected working resource. This workspace is the "selected workspace". Postconditions: The selected working resource is removed from the selected workspace. Response Marshalling: The following status codes can be expected in responses to an UNCHECKOUT request: 200 (OK): The working resource was successfully deleted. 404 (Not Found): The request-URL did not identify a resource. 405 (Method Not Allowed): The selected resource is not a working resource or the specified Workspace is invalid. 6.3.1Example - UNCHECKOUT >> REQUEST UNCHECKOUT /file HTTP/1.1 Host: www.webdav.org Workspace: http://www.webdav.org/workspaces/mywksp >> RESPONSE HTTP/1.1 200 OK Host: www.webdav.org Workspace: http://www.webdav.org/workspaces/mywksp 6.4 CHECKIN The CHECKIN method can be applied to a working resource of a versioned resource to produce a new revision that is a copy of that working resource. This working resource is the "selected working resource". The DAV:predecessor-set of the selected working resource identifies the "predecessor revisions". The versioned resource that contains the predecessor revisions is the "selected versioned resource". The DAV:workspace property of the working resource is the "selected workspace". If the server supports Clemm, Kaler [Page 22] INTERNET-DRAFT WebDAV Versioning May10, 2000 mutable revisions and there is a single predecessor revision, then CHECKIN can be used to overwrite the value of the predecessor revision. Preconditions: The request-URL MUST identify a working resource. Request Marshalling: The request-URL specifies the working resource. The Workspace header specifies the workspace that contains the selected working resource. If a request body is specified, it MUST contain a DAV:checkin- policy XML element. Postconditions: A new revision is created for the selected versioned resource. The new revision is a copy of the working resource without the DAV:checkin-policy property. The value of the DAV:resourceid of the new revision is the same as that of the working resource. The selected workspace is deleted from the DAV:workspace-set property of the predecessor revisions. The new revision is added to the DAV:successor-set property of the predecessor revisions. If DAV:keep-checked-out is specified, the working-resource is not deleted, but the DAV:predecessor-set property of the working resource is modified to contain just the new revision. Otherwise, the selected working resource is deleted. Response Marshalling: The response MUST contain a Location header containing a stable URL for the new revision. The following status codes can be expected in responses to a CHECKIN request: 201 (Created): The revision was successfully created. 404 (Not Found): The request-URL did not identify a resource. 405 (Method Not Allowed): The selected resource is not a working resource, the specified Workspace is invalid, or the specified properties in the DAV:propertyupdate element are invalid. 409 (Conflict): Any other violated pre-condition of the CHECKIN request. 6.4.1Example - CHECKIN >> REQUEST CHECKIN /file HTTP/1.1 Host: www.webdav.org Clemm, Kaler [Page 23] INTERNET-DRAFT WebDAV Versioning May10, 2000 Workspace: http://www.webdav.org/workspaces/mywksp Content-type: text/xml; charset="utf-8" >> RESPONSE HTTP/1.1 201 Created Host: www.webdav.org Workspace: http://www.webdav.org/workspaces/mywksp Content-type: text/xml; charset="utf-8" Location: http://www.webdav.org/repository/vr/23/rev/12 6.5 LABEL The LABEL method is used to add or remove a label on a revision of a versioned resource. Preconditions: The request-URL MUST identify a revision of a versioned resource. Request Marshalling: The request-URL specifies the revision. The body of the request contains either a DAV:add or a DAV:delete element. Postconditions: The specified label has been added to or deleted from the specified revision. Response Marshalling: The following status codes can be expected in responses to a LABEL request: 200 (OK): The label update was performed. 400 (Bad Request): The specified label was not a legal segment. 404 (Not Found): The request-URL did not identify a resource. 405 (Method Not Allowed): The selected resource is not a revision. 6.5.1Example - LABEL >> REQUEST LABEL /file HTTP/1.1 Host: www.webdav.org Workspace "http://www.webdav.org/workspaces/mywksp" Content-type: text/xml; charset="utf-8" stable Clemm, Kaler [Page 24] INTERNET-DRAFT WebDAV Versioning May10, 2000 >> RESPONSE HTTP/1.1 200 OK Host: www.webdav.org Workspace "http://www.webdav.org/workspaces/mywksp" Content-type: text/xml; charset="utf-8" 7 VERSIONING HEADERS 7.1 Workspace The following defines the BNF for the Workspace header: Workspace := "Workspace" ":" URL | "Workspace" ":" The syntax of a URL is defined in [RFC2396]. Examples of a workspace header are: Workspace: http://www.webdav.org/workspaces/public Workspace: Whenever a server encounters a versioned resource while it is processing an HTTP request, it is required to act on the target of the versioned resource. The Workspace header specifies which workspace will be used to determine the target. If that workspace identifies a working resource for that versioned resource, that working resource is selected; otherwise, the request MUST fail. If the Workspace-URL is omitted in the Workspace header, the versioned resource itself is the target of the request. This allows a client to access the properties of the versioned resource itself. If no Workspace header is specified, the DAV:default-revision of that versioned resource is selected. A server MUST return a Vary header containing "Workspace" in any response that includes a Workspace header. 7.2 Revision-Selector The following defines the BNF for the Revision-Selector header: Revision-Selector := "Revision-Selector" ":" "id" segment | " Revision-Selector" ":" "label" segment Examples of a Revision-Selector header are: Revision-Selector: id Rev178AE8 Revision-Selector: label released Clemm, Kaler [Page 25] INTERNET-DRAFT WebDAV Versioning May10, 2000 When the target of a request-URL would otherwise be a working resource or a revision of a versioned resource, a Revision-Selector header causes the revision identified by the specified id or label to be selected instead. A server MUST return a Vary header containing "Revision-Selector" in any response that includes a Revision-Selector header. 8 ADVANCED VERSIONING 8.1 Advanced Versioning Terms Workspace A workspace is a resource that not only identifies working resources, but also contains a revision selection rule that specifies what revision of an arbitrary versioned resource should be accessed when the resource is referenced in the context of that workspace. A revision selection rule provides revision selection based on criteria such as revision label, latest in an activity, and membership in a configuration. The following diagram illustrates a workspace resource. Foo.htm Bar.htm Bing.htm +----+ +----+ | V1 | | V1 | +----+ +----+ | | | | +-----------------|------------|------------------+ | v v | | +----+ +----+ +----+ | | | V1 | | V2 | | WR | Workspace X | | +----+ +----+ +----+ | | | | +-----------------|-------------------------------+ | v +----+ | V3 | +----+ Default Workspace A default workspace can be associated with a collection to specify the default revision selection for members of that collection . The revision selection specified by a default workspace overrides the DAV:default-revision property of a versioned resource. Activity An activity is a resource that selects a set of revisions that correspond to some unit of work or conceptual change. An activity Clemm, Kaler [Page 26] INTERNET-DRAFT WebDAV Versioning May10, 2000 can contain revisions of multiple versioned resources, and multiple revisions of the same versioned resource. If an activity contains multiple revisions of the same versioned resource, every revision must be on a single "line of descent" in that versioned resource, where a line of descent is a sequence of revisions connected by successor relationships. The following diagram illustrates activities. Revision V3 is the latest revision of Foo.htm selected by activity 2, and revision V7 is the latest revision of Bar.htm selected by activity 2. Foo.htm | Bar.htm | +----+ | +----+ | V1 | | | V5 | +----+ | +----+ | Activity | | Activity v 1 | v 2 +----+ | +----+ | V2 | | | V6 | +----+ | +----+ | Activity | | Activity v 2 | v 2 +----+ | +----+ | V3 | | | V7 | +----+ | +----+ | | Activity | v 3 | +----+ | | V8 | | +----+ Conflict Report A conflict report lists all versioned resources for which the revision selection rule of a workspace selects multiple revisions on different lines of descent. A conflict is resolved by checking out one of the selected revisions, modifying the resulting working resource so that it represents the logical merge of all selected revisions, and then indicating these merges by adding these revisions as additional predecessors of the working resource. Checking in this working resource creates a new revision that resolves the conflict. Configuration A configuration is a type of collection that contains a set of revisions, with a most one revision from any versioned resource. Unlike a workspace, which can select both working resources and revisions, a configuration can only select revisions. Also, while the revision selected by a workspace for a versioned resource can change as a result of a change to the versioned resource (such as adding a label), the revision selected by a configuration can change only by explicitly modifying the configuration. Unlike an activity, a configuration can contain at most one revision of a Clemm, Kaler [Page 27] INTERNET-DRAFT WebDAV Versioning May10, 2000 given versioned resource. Unlike both a workspace and an activity, a configuration can be versioned. The following diagram illustrates a configuration. Foo.htm Bar.htm Bing.htm +----+ | V1 | +----+ | | +-----------------|-------------------------------+ | | | | +----+ +----+ +----+ Configuration | | | V1 | | V2 | | V1 | V1.1 | | +----+ +----+ +----+ | | | | | +-----------------|------------|------------------+ | | v v +----+ +----+ | V3 | | V2 | +----+ +----+ Versioned Collection A versioned collection is a type of versioned resource that results from placing a collection under version control. The members of a versioned collection revision must be versioned resources. The working resource that results from checking out a versioned collection is called a working collection. Baseline A baseline is a revision of a versioned configuration that is associated with a particular versioned collection. Each baseline defines a "deep revision" of a particular versioned collection. A deep revision of a versioned collection captures the state of a versioned collection in a particular workspace, including a revision of the versioned collection selected by that workspace, as well as a revision of every member of that versioned collection selected by that workspace. Repository A repository is a type of resource that contains related versioned resources, activities, and configurations. A repository provides a stable namespace for versioning metadata resources, and provides versioning unaware clients access to the versioning metadata. Clemm, Kaler [Page 28] INTERNET-DRAFT WebDAV Versioning May10, 2000 9 ADVANCED VERSIONING SEMANTICS 9.1 Revision Selection and Workspaces When a request URL identifies a versioned resource, it is necessary to provide additional information to specify which working resource or which revision of the versioned resource should be accessed. Specifying the resource URL and a revision label can access a specific revision of the versioned resource. However, this requires the user to add and remember labels for each revision; it does not provide a way of accessing a consistent set of revisions captured by an activity or contained in a configuration; it does not enable non-versioning aware clients to access revisions; and it does not provide a client with access to a working resource of a versioned resource. To address the restrictions inherent in revision-name based revision selection, the revision selected when a specific revision name is not specified is resolved through a workspace. A workspace is a resource whose primary purpose is to identify working resources. If the workspace contains no working resource for a given versioned resource, it can also be used to select an appropriate revision of the versioned resource. This allows versioned resources and unversioned resources to be accessed consistently by both versioning-aware and versioning-unaware clients. In order to specify revision selection, a workspace contains a revision selection rule. A revision selection rule can specify revision labels, activities, configurations, or use operators that combine several of these revision selectors. A revision label selects a revision with that label. An activity selects the latest revision that was created in that activity. Configurations select the revision contained in the configuration. The "or" operator contains a sequence of rule elements, and applies them in order until the first match is found. If there is no matching revision, then a resource-not-found status is returned. If a request is made and no workspace is specified, a server determined default workspace is used. This is the workspace used by all versioning-unaware clients. A server MAY allow modifications to the revision selection rule of the default workspace. 9.2 Parallel Development, Activities, and Merging In a locking model, when a resource is locked for modifications by one author, all other authors are supposed to respect that lock and not work on a copy of that resource until the lock has been released. To avoid the work serialization inherent in the locking model, a versioning model allows multiple authors in different workspaces to check out the same revision at the same time, work on their respective working resources in parallel, and check in their respective working resources as soon as their changes are complete. Clemm, Kaler [Page 29] INTERNET-DRAFT WebDAV Versioning May10, 2000 This results in two parallel revisions (neither revision is an ancestor of the other) that will need to be merged. Although a simple versioning model works well for isolated changes to independent resources, the required merge process becomes unmanageable when sequences of inter-related changes are performed on sets of related resources. To address this merge problem, resources can be checked out in the context of an activity. An activity captures the set of revisions that form a set of related changes an author is making to one or more versioned resources. Each activity represents a thread of development, where any thread can be isolated from other threads to provide a stable environment for parallel work. When parallel work on isolated activities results in branches in the underlying versioned resource histories, the activities can be unified through a merge operation. The activities to be merged are specified with a merge operator in the revision selection rule of a workspace. A conflict report is then obtained from the workspace, which enumerates which revisions of which versioned resources need to be merged. The client then uses the conflict report to iterate through the versioned resources that require merging, preferably providing the user with some domain specific merge tool. Finally, the result of each merge is checked in as a new revision with multiple predecessors (the revisions that were merged). The next time a conflict report is requested for that set of activities, the workspace will indicate that no conflicts exist (i.e. all conflicts have been resolved by merges). 9.3 Configurations A workspace selects a volatile set of revisions. Changes to selected activities or changes to labels may result in the selection of different revisions. A configuration is a resource that selects a specific set of revisions. A workspace whose version selection rule contains a configuration will always select the same revisions as long as the configuration is not modified and no checkouts are performed in that workspace. Configurations are convenient for defining a persistent set of revisions that relate to each other in some specific way at some point in time. This can be useful for a variety of purposes such as publishing consistent versions of resources to deploy an application, or for recovering a specific state for legal or maintenance reasons. 9.4 Versioned Collections A collection contains a set of named bindings to other resources that are the members of that collection. For a versioned collection, the bindings are to versioned resources, not to particular revisions. To modify the state of a versioned collection (i.e. add or remove a binding), the versioned collection must be checked out, just like any other versioned resource. Requests that Clemm, Kaler [Page 30] INTERNET-DRAFT WebDAV Versioning May10, 2000 modify the state of a collection member, such as checking it out or checking in a new revision, have no effect on the state of the collection. Conversely, requests that modify the state of a versioned collection, such as deleting or adding a binding to a resource, have no effect on the state of that resource. In particular, the resource will remain bound in any other revisions of the collection of which it was a member. It is often important to capture the entire tree of revisions selected by a workspace rooted at a given versioned collection. This "deep revision" of a versioned collection is called a baseline. If a URL identifies a sequence of nested versioned collections, revision selection is performed for each versioned collection in the sequence, to select the versioned collection revision that will be used to map the next segment of the URL to the appropriate versioned resource. 9.5 Repositories A repository contains versioned resources, activities, and configurations. Since a server will often allow certain metadata relationships to be created only between resources in the same repository, it is important to allow a client to specify in which repository a resource should be created. 10 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE This section defines the new resource types and properties introduced by WebDAV versioning. 10.1 Collection Properties WebDAV advanced versioning introduces the following properties for a collection: 10.1.1 DAV:default-workspace This property of a collection identifies the workspace that should be used to perform default revision selection for members of a collection. The DAV:default-workspace href contains a stable URL. 10.2 Versioned Resource Properties WebDAV advanced versioning introduces the following properties for a versioned resource: Clemm, Kaler [Page 31] INTERNET-DRAFT WebDAV Versioning May10, 2000 10.2.1 DAV:baselines (protected) This property appears on a versioned collection that has baselines. It identifies the versioned configuration containing those baselines. The DAV:baselines href contains a stable URL. 10.2.2 DAV:repository (protected) This property identifies the repository that contains this versioned resource. The DAV:repository href contains a stable URL. 10.3 Revision Properties WebDAV advanced versioning introduces the following properties for a revision: 10.3.1 DAV:activity This property identifies the activity that represents the logical change to which this revision contributes. The DAV:activity href contains a stable URL. 10.4 Working Resource Properties WebDAV advanced versioning introduces the following properties for a working resource: 10.4.1 DAV:activity This property identifies the activity that represents the logical change to which this working resource contributes. The DAV:activity href contains a stable URL. 10.5 Workspace Properties The DAV:resourcetype of a workspace MUST be DAV:workspace- resourcetype. WebDAV advanced versioning introduces the following properties for a workspace: 10.5.1 DAV:working-resource-set (protected) This property identifies the working resources that are checked out into this workspace. Each DAV:working-resource-set href contains a stable URL. Clemm, Kaler [Page 32] INTERNET-DRAFT WebDAV Versioning May10, 2000 10.5.2 DAV:revision-selection-rule If there is no working resource in a workspace for a given versioned resource, the DAV:revision-selection-rule of the workspace specifies the revision of that versioned resource that is selected by that workspace. Since the working resources checked out into a workspace take priority over revisions selected by the revision selection rule, the target of a versioned resource in a workspace is the working resource in that workspace for that versioned resource, otherwise the revision selected by the workspace revision selection rule. To ensure that working resources continue to be visible in a workspace after they are checked in, the DAV:current-label or DAV:current-activity of a workspace is usually the first element of the DAV:revision-selection-rule. If the DAV:revision-selection-rule is not set or is empty, the workspace will select no revision for any versioned resource. The DAV:revision-selection-rule property contains an XML element. Semantically, a revision selection rule (or RSR) element can be applied to an arbitrary versioned resource, and will either select a particular revision of that versioned resource, select no revision of that versioned resource, or detect a conflict (e.g. when there were multiple candidates for selection). A document describing the conflicts can be obtained through a conflict REPORT request. An href element contains a stable URL of an activity, a configuration, or a revision. If the href identifies an activity, and the DAV:revision-set property of the activity contains one or more revisions of the versioned resource, then the latest revision for that activity is selected. The semantics of activities ensures that there always is a unique latest revision for an activity. If the activity contains no revisions of the versioned resource, the activity selects no revisions of that versioned resource. If the DAV:needed-activity- set property of an activity is non-empty, then the activity acts like a DAV:rsr-merge element that contains that activity and each of the DAV:needed-activity-set activities. An activity element can generate conflicts only if the DAV:needed-activity-set property is non-empty. If the href identifies a configuration, and the configuration contains a revision of the versioned resource, that revision is selected by the configuration; otherwise, no revision is selected. To avoid revision selection circularities, a versioned Clemm, Kaler [Page 33] INTERNET-DRAFT WebDAV Versioning May10, 2000 configuration MUST not be specified in a revision selection rule, but a configuration revision may. A configuration never generates a conflict. If the href identifies a revision, then that revision is selected if it is a revision of the versioned resource; otherwise, no revision is selected. If the revision selection rule element is a label, and a revision of the versioned resource has that label, that revision is selected; otherwise, no revision is selected. A label element never generates a conflict. A DAV:rsr-latest element selects the revision of that versioned resource with the latest DAV:creationdate. A DAV:rsr-latest element never generates a conflict. A DAV:rsr-or element contains a sequence of RSR elements. The behavior of a DAV:rsr-or element is identical to the behavior of the first element in this sequence that selects a revision of the versioned resource. If this element generates a conflict, the DAV:rsr-or element generates this conflict as well. If no element selects a revision, then the DAV:rsr-or element selects no revision of that versioned resource. A DAV:rsr-merge element contains a sequence of RSR elements. If one of the elements in this sequence selects a revision that is the descendent of all of the other revisions selected by elements in this sequence, then that revision is selected by the DAV:rsr-merge element. If no selected revision is a descendent of all the other selected revisions, then the result of the DAV:rsr-merge is a "conflict". A conflict REPORT request can be used to identify the conflicts. 10.5.3 DAV:no-checkout The DAV:no-checkout property of a workspace indicates that no new working resources can be created in that workspace. Value: boolean 10.5.4 DAV:current-label The DAV:current-label property of a workspace can contain a revision label. When a working resource in a workspace is checked in, it will be given this label. Value: segment 10.5.5 DAV:current-activity The DAV:current-activity property of a workspace is the activity that is currently being performed in that workspace. A new working resource in a workspace will have its DAV:current-activity Clemm, Kaler [Page 34] INTERNET-DRAFT WebDAV Versioning May10, 2000 property set to this activity. The DAV:current-activity href contains a stable URL. 10.6 Activity Properties The DAV:resourcetype of an activity MUST be DAV:activity- resourcetype. WebDAV advanced versioning introduces the following properties for an activity: 10.6.1 DAV:revision-set (protected) This property identifies the revisions whose DAV:activity property identifies this activity. Each DAV:revision-set href contains a stable URL. 10.6.2 DAV:needed-activity-set This property identifies the other activities that form a part of the logical change being captured by this activity. The DAV:needed-activity-set of an activity contribute to the revision selection behavior of that activity when it is used in a revision selection rule. The purpose of this property is to identify other activities that are a prerequisite to this activity. Each DAV:needed-activity-set href contains a stable URL. 10.6.3 DAV:workspace-set (protected) This property identifies the workspaces whose DAV:current-activity property identifies this activity. Each DAV:workspace-set href contains a stable URL. 10.7 Configuration Properties The DAV:resourcetype of a configuration MUST be DAV:configuration- resourcetype. 10.7.1 DAV:baseline-root (protected) This property appears on a configuration that is a baseline of a versioned collection. It contains a stable URL to the versioned collection. Clemm, Kaler [Page 35] INTERNET-DRAFT WebDAV Versioning May10, 2000 10.8 Repository Properties The DAV:resourcetype of a repository MUST be DAV:repository- resourcetype. WebDAV advanced versioning introduces the following properties for a repository: 10.8.1 DAV:versioned-resource-collection (protected) This property identifies the stable URL of a collection that contains the set of versioned resources maintained by the repository. The name of a versioned resource in this collection MUST be its DAV:resourceid. This restricts the DAV:resourceid of a versioned resource in a repository to be a legal URL segment. 10.8.2 DAV:repository-root (protected) This property identifies the member of DAV:versioned-resource- collection that can be exposed with a BIND operation in another part of the URL namespace. The DAV:repository-root href contains a stable URL. 10.8.3 DAV:activity-collection (protected) This property identifies the stable URL of a collection that contains the set of activities maintained by that repository. New activities can be added to this collection with a MKRESOURCE request. A server MAY restrict the creation of new activities to only occur in a DAV:activity-collection of a repository. 10.8.4 DAV:configuration-collection (protected) This property identifies the stable URL of a collection that contains the set of configurations maintained by that repository. New configurations can be added to this collection with a MKRESOURCE request. A server MAY restrict the creation of new configurations to only occur in a DAV:configuration-collection collection of a repository. 11 ADVANCED VERSIONING AND EXISTING METHODS Each binding in a working collection MUST be to a versioned resource. Therefore, when a request (e.g. PUT, MKCOL, MKRESOURCE) attempts to create a new resource in a working collection: - a new versioned resource is created, - an empty initial revision is created and checked out, Clemm, Kaler [Page 36] INTERNET-DRAFT WebDAV Versioning May10, 2000 - the request is used to initialize the state of the new working resource, - and a binding to the new versioned resource is added to the working collection. When a request attempts to add a binding to a revision of a versioned collection, the request MUST fail unless the versioned collection has a DAV:auto-version property and no Workspace header has been specified. In this case, the versioned collection is checked out, the request is applied to the resulting working collection, and the working collection is checked in. 11.1LOCK If a LOCK is successfully applied to a URL, revision selection in the current workspace is frozen for the duration of the lock for any versioned resource or versioned collection identified by that URL or by any slash-terminated prefix of that URL. When revision selection is frozen for a particular versioned resource in a workspace, only a CHECKIN of a working resource in that workspace for that versioned resource causes revision selection to be recomputed for that versioned resource. 11.2CHECKOUT When workspace resources are provided, a CHECKOUT request may specify a workspace in the Workspace request header. The server MUST use this workspace to identify the working resource created by the CHECKOUT. If there already is a working resource for that versioned resource with that workspace, the CHECKOUT request MUST fail. The new working resource is added to the DAV:working-resource-set property of the selected workspace. If the DAV:current-activity property of the specified workspace is set, the DAV:activity property of the working resource is set to that activity. 11.3CHECKIN If the DAV:current-label of the workspace is set, that label is applied to the new revision created by the CHECKIN request. If the DAV:activity property of the working resource being checked in identifies an activity, the new revision created by the CHECKIN is added to the DAV:revision-set property of that activity. If CHECKIN is being applied to a baseline of a versioned collection, then the current workspace must select a particular revision of each member of that versioned collection. In particular, there can be no conflicts and there can be no working resources. Clemm, Kaler [Page 37] INTERNET-DRAFT WebDAV Versioning May10, 2000 12 ADVANCED VERSIONING REPORTS 12.1Conflict REPORT A conflict report describes the conflicts in a specified workspace for a specified resource or for all the members of a specified versioned collection. Conflicts occur when the workspace revision selection rule selects more than one revision of a particular versioned resource, resulting in ambiguous revision selection. The resource to test is specified by the request-URL. Conflicts are checked in the workspace specified in the Workspace header. If the Workspace header is not given, the default workspace is used. Conflicts for all resources transitively reachable from the request-URL are reported according to the value of the Depth header. If the Depth header is not specified, the value infinity is assumed. Conflicts in resources reachable only via a versioned collection which is itself ambiguous are not reported. 12.1.1 DAV:conflict-report-request 12.1.2 DAV:conflict-report-response A DAV:conflict-report-response contains a DAV:conflict element for each versioned resource for which the workspace produced a conflict. Value: segment Value: segment The DAV:conflict element contains the URL of a versioned resource for which the revision selection rule generated a conflict, a DAV:common-ancestor for the conflict, and two or more DAV:contributor elements for the conflict. The DAV:common-ancestor element identifies the revision id of a revision that is a common ancestor of all the DAV:contributor elements for a particular conflict. The DAV:contributor element identifies the revision id of a revision that is selected by an element of the revision selection rule but that is not an ancestor of any of the other revisions selected by the revision selection rule. 12.1.3 Example - Conflict REPORT >>Request Clemm, Kaler [Page 38] INTERNET-DRAFT WebDAV Versioning May10, 2000 REPORT /myCollection HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Workspace http://www.webdav.org/repo/workspaces/public >>Response HTTP/1.1 200 OK Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Workspace http://www.webdav.org/repo/workspaces/public http://www.webdav.org/repo/vr/vr732 revisionid:3 revisionid:5 revisionid:4 12.2Compare REPORT A compare REPORT identifies the differences between the resource identified by the request-URL (base) and the resources specified in the body of the request (targets). 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 target but not in the base are described by DAV:added elements, resources appearing in the base but not a target are described by DAV:deleted elements, and resources appearing in both base and target but having different states are described by DAV:changed elements. Resource content comparison is not specified, though servers MAY provide it. 12.2.1 DAV:compare-report-request A DAV:compare- request contains the URL's of the resources to be compared with the resource identified by the request URL. Clemm, Kaler [Page 39] INTERNET-DRAFT WebDAV Versioning May10, 2000 12.2.2 DAV:compare-report-response A DAV:compare-report-response identifies the differences between two resources. These differences are indicated by appropriate DAV:added, DAV:deleted, and DAV:changed elements. For example, if a DAV:compare-request is applied to two configurations, the DAV:compare-report-response contains the revisions that are selected by one configuration but not the other. A DAV:added element identifies something that appears in a particular target resource but not in the base. A DAV:deleted element identifies something that appears in the base resource but not in a particular target. A DAV:changed element identifies information that is in both the base and the target but that has changed in some way. For example, when two configurations are being compared, a DAV:changed element can identify a versioned resource if the configurations select different revisions of that versioned resource. 12.2.3 Example - Compare REPORT >>Request REPORT /myCollection HTTP/1.1 Host: www.foo.com Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Depth: 1 http://www.foo.com/myOtherCollection >>Response HTTP/1.1 200 OK Host: www.foo.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx http://www.foo.com/myOtherCollection Clemm, Kaler [Page 40] INTERNET-DRAFT WebDAV Versioning May10, 2000 http://www.foo.com/myOtherCollection/foo.html http://www.foo.com/myCollection/bar.html 13 ADVANCED VERSIONING METHODS 13.1MERGE The MERGE method can be applied to a working resource to add or delete predecessors for that working resource. Preconditions: The request-URL MUST identify a working resource. A revision being added to the predecessors of a working resource MUST share a common ancestor with each of the other predecessors of the working resource. A revision being added to the predecessors of working resource MUST not be an ancestor of one of the other predecessors of the working resource. A revision being deleted from the predecessors of a working resource MUST be one of the predecessors of the working resource. Request Marshalling: The request-URL specifies the working resource. The body of the request contains an XML document with DAV:add and DAV:delete members. Postconditions: The predecessor revisions being added are members of the DAV:predecessor-set property of the working resource. The predecessor revisions being deleted are not members of the DAV:predecessor-set property of the working resource. Response Marshalling: The following status codes can be expected in responses to a MERGE request: 200 (OK): The predecessor update was performed.. 404 (Not Found): The request-URL did not identify a resource. 405 (Method Not Allowed): The selected resource is not a working resource or the specified Workspace is invalid. Clemm, Kaler [Page 41] INTERNET-DRAFT WebDAV Versioning May10, 2000 409 (Conflict): Any other violated pre-condition of the MERGE request. 13.1.1 Example - MERGE >> REQUEST MERGE /file HTTP/1.1 Host: www.webdav.org Workspace "http://www.webdav.org/workspaces/mywksp" Content-type: text/xml; charset="utf-8" http://www.webdav.org/repo/vr/VR182/rev/5 >> RESPONSE HTTP/1.1 200 OK Host: www.webdav.org Workspace "http://www.webdav.org/workspaces/mywksp" Content-type: text/xml; charset="utf-8" 13.2CONFIGURE The CONFIGURE method is used to add or remove a revision from a configuration. Preconditions: The request-URL MUST identify a revision of a versioned resource. Request Marshalling: The request-URL specifies the revision. The body of the request contains either a DAV:add or a DAV:delete element, where the value of the element is an href of a configuration. Postconditions: The specified revision has been added to or deleted from the specified configuration. Response Marshalling: The following status codes can be expected in responses to a CONFIGURE request: 200 (OK): The configuration update was performed. 400 (Bad Request): The body of the request did not contain a DAV:add or DAV:delete element whose value was an href of a configuration. 404 (Not Found): The request-URL did not identify a resource. 405 (Method Not Allowed): The selected resource is not a revision. Clemm, Kaler [Page 42] INTERNET-DRAFT WebDAV Versioning May10, 2000 13.2.1 Example - CONFIGURE >> REQUEST CONFIGURE /file HTTP/1.1 Host: www.webdav.org Workspace "http://www.webdav.org/workspaces/mywksp" Content-type: text/xml; charset="utf-8" http://www.webdav.org/repository/cg/357 >> RESPONSE HTTP/1.1 200 OK Host: www.webdav.org Workspace "http://www.webdav.org/workspaces/mywksp" Content-type: text/xml; charset="utf-8" 13.3BASELINE The BASELINE method can be applied to a versioned collection to allow the creation of baselines for that versioned collection. Preconditions: The request-URL MUST identify a versioned collection. The versioned collection MUST NOT have a DAV:baselines property. Request Marshalling: The request-URL specifies the versioned collection. Postconditions: The DAV:baselines property of the versioned collection identifies a new versioned configuration that will contain the baselines for the versioned collection. Response Marshalling: The response MUST contain a Location header containing a stable URL for the new versioned configuration. The following status codes can be expected in responses to a BASELINE request: 201 (Created): The versioned configuration was successfully created and associated with the versioned collection. 404 (Not Found): The request-URL did not identify a resource. 405 (Method Not Allowed): The selected resource is not a versioned collection. 409 (Conflict): The versioned collection already has a DAV:baselines property. Clemm, Kaler [Page 43] INTERNET-DRAFT WebDAV Versioning May10, 2000 13.3.1 Example - BASELINE >> REQUEST BASELINE /folder HTTP/1.1 Host: www.webdav.org >> RESPONSE HTTP/1.1 201 Created Host: www.webdav.org Location: http://www.webdav.org/repository/vr/237 14 ADVANCED VERSIONING HEADERS Advanced versioning does not introduce any new headers, but the semantics of the Workspace header is extended to take advantage of the DAV:revision-selection-rule property of workspace resources. 14.1Workspace If the Workspace header specifies the URL of an advanced versioning workspace resource, and no working resource for that versioned resource exists in that workspace, then the revision specified by the DAV:revision-selection-rule property of the workspace is selected. 15 INTERNATIONALIZATION CONSIDERATIONS To be supplied. 16 SECURITY CONSIDERATIONS To be supplied. 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] also applicable to WebDAV Versioning. Clemm, Kaler [Page 44] INTERNET-DRAFT WebDAV Versioning May10, 2000 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 IETF's procedures 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 which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. 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), Chris Kaler (Microsoft), Jeff McAffer (OTI), Bradley Sergeant (Merant), 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, . [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, . Clemm, Kaler [Page 45] INTERNET-DRAFT WebDAV Versioning May10, 2000 [RFC2119] S.Bradner, "Key words for use in RFCs to Indicate Requirement Levels", Harvard, 1997, . [RFC2396] T.Berners-Lee, R.Fielding, L.Masinter, ôUniform Resource Identifiers (URI): Generic Syntaxö, MIT/LCS, U.C. Irvine, Xerox, 1998, . [RFC2518] Y. Goland, E.Whitehead, A.Faizi, S.R.Carter, D.Jensen, "HTTP Extensions for Distributed Authoring - WEBDAV", Microsoft, U.C.Irvine, Netscape, Novell, 1999 . [Binding] J.Slein, E.Whitehead, J.Davis, G.Clemm, C.Fay, J.Crawford, T.Chihaya, "WebDAV Bindings", Xerox, U.C.Irvine, CourseNet, Rational, FileNet, DataChannel, 1999, [Goals] J.Amsden, C.Kaler, J.Stracke, "Goals for Web Versioning", IBM, Microsoft, Netscape, 1999, 24 AUTHORS' ADDRESSES Geoffrey Clemm Rational Software 20 Maguire Road Lexington, MA Email: geoffrey.clemm@rational.com Christopher Kaler Microsoft One Microsoft Way Redmond WA, 9085-6933 Email: ckaler@microsoft.com 25 OPEN ISSUES The following list identifies key open issues against this document: @ TODO: Flesh out the effect of VERSION and CHECKIN on all properties. @ TODO: Add error conditions for auto-versioning. @ TODO: Allow activity and workspace as CHECKIN request-URL. @ TODO: Allow CHECKOUT to apply to a versionable resource (like LOCK). Clemm, Kaler [Page 46] INTERNET-DRAFT WebDAV Versioning May10, 2000 @ TODO: Describe how BIND can mount the root versioned collection of a repository at an arbitrary URL, even at another authority. @ TODO: Mention that the If-Modified-Since header cannot be used to reliably cache versioned resource information since the modification date can decrease. @ Does Versioning have to be a header, or can it be the body of the OPTIONS response? @ Couldn't MKRESOURCE be handled just by allowing PROPPATCH to be applied to a null resource? @ Do members of a versioned collection revision have to be versioned resources? @ Should we define which properties are optional, and which can have an empty string as a value? @ Should there be a report to enumerate the repositories and workspaces ? @ Is there already an DAV property like DAV:author? @ Should dead properties like DAV:author and DAV:comment be in another document METHOD Template Preconditions: {What are the expected preconditions of the method, and what happens if these preconditions are violated. For example, a common precondition is the resource identified by the Request-URI must exist.} Request Marshalling: {How are the arguments for the method marshalled. For WebDAV, this includes stating which headers must be present, and which XML elements are present in the request body.} Postconditions: {It states the postconditions of the method, giving easily validated postconditions. Some examples of postconditions are effects on the state of the resource, including body and properties, and effects on the resource's parent collection. Postconditions will often vary depending on the type of the resource executing the method.} Response Marshalling: {It states how the results of the method are marshalled, including the response for success, and the responses which are generated when the postconditions cannot be achieved.} Effect on Existing Resource Types: Clemm, Kaler [Page 47] INTERNET-DRAFT WebDAV Versioning May10, 2000 {How does this method work on all the different types of resources defined so far (collections, redirect references, ordinary resources, etc.)} Clemm, Kaler [Page 48]