RFC 3253
Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)
Network Working Group G. Clemm Request for Comments: 3253 Rational Software Category: Standards Track J. Amsden T. Ellison IBM C. Kaler Microsoft J. Whitehead U.C. Santa Cruz March 2002 Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning) Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2002). All Rights Reserved.Abstract
This document specifies a set of methods, headers, and resource types that define the WebDAV (Web Distributed Authoring and Versioning) versioning extensions to the HTTP/1.1 protocol. WebDAV versioning will minimize the complexity of clients that are capable of interoperating with a variety of versioning repository managers, to facilitate widespread deployment of applications capable of utilizing the WebDAV Versioning services. WebDAV versioning includes automatic versioning for versioning-unaware clients, version history management, workspace management, baseline management, activity management, and URL namespace versioning.Table of Contents
1 Introduction.................................................... 6 1.1 Relationship to WebDAV........................................ 7 1.2 Notational Conventions........................................ 8 1.3 Terms......................................................... 8 1.4 Property Values............................................... 11 1.4.1 Initial Property Value..................................... 11
1.4.2 Protected Property Value................................... 12
1.4.3 Computed Property Value.................................... 12
1.4.4 Boolean Property Value..................................... 12
1.4.5 DAV:href Property Value.................................... 12
1.5 DAV Namespace XML Elements.................................... 12
1.6 Method Preconditions and Postconditions....................... 12
1.6.1 Example - CHECKOUT request................................. 13
1.7 Clarification of COPY Semantics with Overwrite:T.............. 13
1.8 Versioning Methods and Write Locks............................ 14
2 Basic Versioning Features....................................... 14
2.1 Basic Versioning Packages..................................... 14
2.2 Basic Versioning Semantics.................................... 16
2.2.1 Creating a Version-Controlled Resource..................... 16
2.2.2 Modifying a Version-Controlled Resource.................... 17
2.2.3 Reporting.................................................. 19
3 Version-Control Feature......................................... 20
3.1 Additional Resource Properties................................ 20
3.1.1 DAV:comment................................................ 20
3.1.2 DAV:creator-displayname.................................... 20
3.1.3 DAV:supported-method-set (protected)....................... 20
3.1.4 DAV:supported-live-property-set (protected)................ 21
3.1.5 DAV:supported-report-set (protected)....................... 21
3.2 Version-Controlled Resource Properties........................ 21
3.2.1 DAV:checked-in (protected)................................. 21
3.2.2 DAV:auto-version........................................... 22
3.3 Checked-Out Resource Properties............................... 22
3.3.1 DAV:checked-out (protected)................................ 23
3.3.2 DAV:predecessor-set........................................ 23
3.4 Version Properties............................................ 23
3.4.1 DAV:predecessor-set (protected)............................ 23
3.4.2 DAV:successor-set (computed)............................... 23
3.4.3 DAV:checkout-set (computed)................................ 23
3.4.4 DAV:version-name (protected)............................... 24
3.5 VERSION-CONTROL Method........................................ 24
3.5.1 Example - VERSION-CONTROL.................................. 25
3.6 REPORT Method................................................. 25
3.7 DAV:version-tree Report....................................... 26
3.7.1 Example - DAV:version-tree Report.......................... 27
3.8 DAV:expand-property Report.................................... 29
3.8.1 Example - DAV:expand-property.............................. 30
3.9 Additional OPTIONS Semantics.................................. 31
3.10 Additional PUT Semantics..................................... 31
3.11 Additional PROPFIND Semantics................................ 32
3.12 Additional PROPPATCH Semantics............................... 33
3.13 Additional DELETE Semantics.................................. 33
3.14 Additional COPY Semantics.................................... 34
3.15 Additional MOVE Semantics.................................... 34
3.16 Additional UNLOCK Semantics.................................. 35
4 Checkout-In-Place Feature....................................... 35 4.1 Additional Version Properties................................. 35 4.1.1 DAV:checkout-fork.......................................... 36 4.1.2 DAV:checkin-fork........................................... 36 4.2 Checked-Out Resource Properties............................... 36 4.2.1 DAV:checkout-fork.......................................... 36 4.2.2 DAV:checkin-fork........................................... 37 4.3 CHECKOUT Method............................................... 37 4.3.1 Example - CHECKOUT......................................... 38 4.4 CHECKIN Method................................................ 38 4.4.1 Example - CHECKIN.......................................... 40 4.5 UNCHECKOUT Method............................................. 40 4.5.1 Example - UNCHECKOUT....................................... 41 4.6 Additional OPTIONS Semantics.................................. 42 5 Version-History Feature......................................... 42 5.1 Version History Properties.................................... 42 5.1.1 DAV:version-set (protected)................................ 42 5.1.2 DAV:root-version (computed)................................ 42 5.2 Additional Version-Controlled Resource Properties............. 42 5.2.1 DAV:version-history (computed)............................. 43 5.3 Additional Version Properties................................. 43 5.3.1 DAV:version-history (computed)............................. 43 5.4 DAV:locate-by-history Report.................................. 43 5.4.1 Example - DAV:locate-by-history Report..................... 44 5.5 Additional OPTIONS Semantics.................................. 45 5.6 Additional DELETE Semantics................................... 46 5.7 Additional COPY Semantics..................................... 46 5.8 Additional MOVE Semantics..................................... 46 5.9 Additional VERSION-CONTROL Semantics.......................... 46 5.10 Additional CHECKIN Semantics................................. 47 6 Workspace Feature............................................... 47 6.1 Workspace Properties.......................................... 48 6.1.1 DAV:workspace-checkout-set (computed)...................... 48 6.2 Additional Resource Properties................................ 48 6.2.1 DAV:workspace (protected).................................. 48 6.3 MKWORKSPACE Method............................................ 48 6.3.1 Example - MKWORKSPACE...................................... 49 6.4 Additional OPTIONS Semantics.................................. 49 6.4.1 Example - OPTIONS.......................................... 51 6.5 Additional DELETE Semantics................................... 51 6.6 Additional MOVE Semantics..................................... 52 6.7 Additional VERSION-CONTROL Semantics.......................... 52 6.7.1 Example - VERSION-CONTROL.................................. 53 7 Update Feature.................................................. 53 7.1 UPDATE Method................................................. 53 7.1.1 Example - UPDATE........................................... 55 7.2 Additional OPTIONS Semantics.................................. 55 8 Label Feature................................................... 56
8.1 Additional Version Properties................................. 56 8.1.1 DAV:label-name-set (protected)............................. 56 8.2 LABEL Method.................................................. 56 8.2.1 Example - Setting a label.................................. 58 8.3 Label Header.................................................. 58 8.4 Additional OPTIONS Semantics.................................. 59 8.5 Additional GET Semantics...................................... 59 8.6 Additional PROPFIND Semantics................................. 59 8.7 Additional COPY Semantics..................................... 60 8.8 Additional CHECKOUT Semantics................................. 60 8.9 Additional UPDATE Semantics................................... 61 9 Working-Resource Feature........................................ 62 9.1 Additional Version Properties................................. 62 9.1.1 DAV:checkout-fork.......................................... 62 9.1.2 DAV:checkin-fork........................................... 63 9.2 Working Resource Properties................................... 63 9.2.1 DAV:auto-update (protected)................................ 63 9.2.2 DAV:checkout-fork.......................................... 63 9.2.3 DAV:checkin-fork........................................... 63 9.3 CHECKOUT Method (applied to a version)........................ 63 9.3.1 Example - CHECKOUT of a version............................ 65 9.4 CHECKIN Method (applied to a working resource)................ 65 9.4.1 Example - CHECKIN of a working resource.................... 66 9.5 Additional OPTIONS Semantics.................................. 67 9.6 Additional COPY Semantics..................................... 67 9.7 Additional MOVE Semantics..................................... 67 10 Advanced Versioning Features.................................. 67 10.1 Advanced Versioning Packages................................. 68 10.2 Advanced Versioning Terms.................................... 68 11 MERGE Feature................................................. 70 11.1 Additional Checked-Out Resource Properties................... 70 11.1.1 DAV:merge-set............................................. 70 11.1.2 DAV:auto-merge-set........................................ 71 11.2 MERGE Method................................................. 71 11.2.1 Example - MERGE........................................... 74 11.3 DAV:merge-preview Report..................................... 75 11.3.1 Example - DAV:merge-preview Report........................ 76 11.4 Additional OPTIONS Semantics................................. 77 11.5 Additional DELETE Semantics.................................. 77 11.6 Additional CHECKIN Semantics................................. 77 12 Baseline Feature.............................................. 77 12.1 Version-Controlled Configuration Properties.................. 78 12.1.1 DAV:baseline-controlled-collection (protected)............ 78 12.2 Checked-Out Configuration Properties......................... 78 12.2.1 DAV:subbaseline-set....................................... 78 12.3 Baseline Properties.......................................... 78 12.3.1 DAV:baseline-collection (protected)....................... 79 12.3.2 DAV:subbaseline-set (protected)........................... 79
12.4 Additional Resource Properties............................... 79 12.4.1 DAV:version-controlled-configuration (computed)........... 79 12.5 Additional Workspace Properties.............................. 80 12.5.1 DAV:baseline-controlled-collection-set (computed)......... 80 12.6 BASELINE-CONTROL Method...................................... 80 12.6.1 Example - BASELINE-CONTROL................................ 82 12.7 DAV:compare-baseline Report.................................. 84 12.7.1 Example - DAV:compare-baseline Report..................... 85 12.8 Additional OPTIONS Semantics................................. 86 12.9 Additional MKCOL Semantics................................... 86 12.10 Additional COPY Semantics................................... 86 12.11 Additional CHECKOUT Semantics............................... 86 12.12 Additional CHECKIN Semantics................................ 86 12.13 Additional UPDATE Semantics................................. 87 12.14 Additional MERGE Semantics.................................. 89 13 Activity Feature.............................................. 90 13.1 Activity Properties.......................................... 91 13.1.1 DAV:activity-version-set (computed)....................... 91 13.1.2 DAV:activity-checkout-set (computed)...................... 92 13.1.3 DAV:subactivity-set....................................... 92 13.1.4 DAV:current-workspace-set (computed)...................... 92 13.2 Additional Version Properties................................ 92 13.2.1 DAV:activity-set.......................................... 93 13.3 Additional Checked-Out Resource Properties................... 93 13.3.1 DAV:unreserved............................................ 93 13.3.2 DAV:activity-set.......................................... 93 13.4 Additional Workspace Properties.............................. 93 13.4.1 DAV:current-activity-set.................................. 94 13.5 MKACTIVITY Method............................................ 94 13.5.1 Example - MKACTIVITY...................................... 95 13.6 DAV:latest-activity-version Report........................... 95 13.7 Additional OPTIONS Semantics................................. 96 13.8 Additional DELETE Semantics.................................. 96 13.9 Additional MOVE Semantics.................................... 97 13.10 Additional CHECKOUT Semantics............................... 97 13.10.1 Example - CHECKOUT with an activity...................... 98 13.11 Additional CHECKIN Semantics................................ 99 13.12 Additional MERGE Semantics.................................. 99 14 Version-Controlled-Collection Feature.........................100 14.1 Version-Controlled Collection Properties.....................102 14.1.1 DAV:eclipsed-set (computed)...............................102 14.2 Collection Version Properties................................103 14.2.1 DAV:version-controlled-binding-set (protected)............103 14.3 Additional OPTIONS Semantics.................................103 14.4 Additional DELETE Semantics..................................103 14.5 Additional MKCOL Semantics...................................104 14.6 Additional COPY Semantics....................................104 14.7 Additional MOVE Semantics....................................104
14.8 Additional VERSION-CONTROL Semantics.........................104 14.9 Additional CHECKOUT Semantics................................105 14.10 Additional CHECKIN Semantics................................105 14.11 Additional UPDATE and MERGE Semantics.......................106 15 Internationalization Considerations...........................106 16 Security Considerations.......................................107 16.1 Auditing and Traceability....................................107 16.2 Increased Need for Access Control............................108 16.3 Security Through Obscurity...................................108 16.4 Denial of Service............................................108 17 IANA Considerations...........................................109 18 Intellectual Property.........................................109 19 Acknowledgements..............................................109 20 References....................................................110 Appendix A - Resource Classification..............................111 A.1 DeltaV-Compliant Unmapped URL.................................111 A.2 DeltaV-Compliant Resource.....................................111 A.3 DeltaV-Compliant Collection...................................112 A.4 Versionable Resource..........................................112 A.5 Version-Controlled Resource...................................112 A.6 Version.......................................................113 A.7 Checked-In Version-Controlled Resource........................113 A.8 Checked-Out Resource..........................................113 A.9 Checked-Out Version-Controlled Resource.......................114 A.10 Working Resource.............................................114 A.11 Version History..............................................114 A.12 Workspace....................................................115 A.13 Activity.....................................................115 A.14 Version-Controlled Collection................................115 A.15 Collection Version...........................................115 A.16 Version-Controlled Configuration.............................116 A.17 Baseline.....................................................116 A.18 Checked-Out Version-Controlled Configuration.................116 Authors' Addresses................................................117 Full Copyright Statement..........................................1181 Introduction
This document specifies a set of methods, headers, and properties that define the WebDAV (Web Distributed Authoring and Versioning) versioning extensions to the HTTP/1.1 protocol. Versioning is concerned with tracking and accessing the history of important states of a web resource, such as a standalone web page. The benefits of versioning in the context of the worldwide web include:
- A resource has an explicit history and a persistent identity
across the various states it has had during the course of that
history. It allows browsing through past and alternative versions
of a resource. Frequently the modification and authorship history
of a resource is critical information in itself.
- Resource states (versions) are given stable names that can support
externally stored links for annotation and link server support.
Both annotation and link servers frequently need to store stable
references to portions of resources that are not under their
direct control. By providing stable states of resources, version
control systems allow not only stable pointers into those
resources, but also well defined methods to determine the
relationships of those states of a resource.
WebDAV Versioning defines both basic and advanced versioning
functionality.
Basic versioning allows users to:
- Put a resource under version control
- Determine whether a resource is under version control
- Determine whether a resource update will automatically be captured
as a new version
- Create and access distinct versions of a resource
Advanced versioning provides additional functionality for parallel
development and configuration management of sets of web resources.
This document will first define the properties and method semantics
for the basic versioning features, and then define the additional
properties and method semantics for the advanced versioning features.
An implementer that is only interested in basic versioning should
skip the advanced versioning sections (Section 10 to Section 14).
1.1 Relationship to WebDAV
To maximize interoperability and the use of existing protocol
functionality, versioning support is designed as extensions to the
WebDAV protocol [RFC2518], which itself is an extension to the HTTP
protocol [RFC2616]. All method marshalling and postconditions
defined by RFC 2518 and RFC 2616 continue to hold, to ensure that
versioning unaware clients can interoperate successfully with
versioning servers. Although the versioning extensions are designed
to be orthogonal to most aspects of the WebDAV and HTTP protocols, a
clarification to RFC 2518 is required for effective interoperable
versioning. This clarification is described in Section 1.7.
1.2 Notational Conventions
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 RFC 2119. The term "protected" is placed in parentheses following the definition of a protected property (see Section 1.4.2). The term "computed" is placed in parentheses following the definition of a computed property (see Section 1.4.3). When an XML element type in the "DAV:" namespace is referenced in this document outside of the context of an XML fragment, the string "DAV:" will be prefixed to the element type. When a method is defined in this document, a list of preconditions and postconditions will be defined for that method. If the semantics of an existing method is being extended, a list of additional preconditions and postconditions will be defined. A precondition or postcondition is prefixed by a parenthesized XML element type that identifies that precondition or postcondition (see Section 1.6).1.3 Terms
This document uses the terms defined in RFC 2616, in RFC 2518, and in this section. Section 2.2 defines the semantic versioning model underlying this terminology. Version Control, Checked-In, Checked-Out "Version control" is a set of constraints on how a resource can be updated. A resource under version control is either in a "checked-in" or "checked-out" state, and the version control constraints apply only while the resource is in the checked-in state. Versionable Resource A "versionable resource" is a resource that can be put under version control. Version-Controlled Resource When a versionable resource is put under version control, it becomes a "version-controlled resource". A version-controlled resource can be "checked out" to allow modification of its content or dead properties by standard HTTP and WebDAV methods.
Checked-Out Resource
A "checked-out resource" is a resource under version control that
is in the checked-out state.
Version Resource
A "version resource", or simply "version", is a resource that
contains a copy of a particular state (content and dead
properties) of a version-controlled resource. A version is
created by "checking in" a checked-out resource. The server
allocates a distinct new URL for each new version, and this URL
will never be used to identify any resource other than that
version. The content and dead properties of a version never
change.
Version History Resource
A "version history resource", or simply "version history", is a
resource that contains all the versions of a particular version-
controlled resource.
Version Name
A "version name" is a string chosen by the server to distinguish
one version of a version history from the other versions of that
version history. Versions from different version histories may
have the same version name.
Predecessor, Successor, Ancestor, Descendant
When a version-controlled resource is checked out and then
subsequently checked in, the version that was checked out becomes
a "predecessor" of the version created by the checkin. A client
can specify multiple predecessors for a new version if the new
version is logically a merge of those predecessors. When a
version is connected to another version by traversing one or more
predecessor relations, it is called an "ancestor" of that version.
The inverse of the predecessor and ancestor relations are the
"successor" and "descendant" relations. Therefore, if X is a
predecessor of Y, then Y is a successor of X, and if X is an
ancestor of Y, then Y is a descendant of X.
Root Version Resource
The "root version resource", or simply "root version", is the
version in a version history that is an ancestor of every other
version in that version history.
Workspace Resource
A "workspace resource", or simply "workspace", is a collection
that contains at most one version-controlled resource for a given
version history (see Section 6).
Working Resource
A "working resource" is a checked-out resource created by the
server at a server-defined URL when a version (instead of a
version-controlled resource) is checked out. Unlike a checked-out
version-controlled resource, a working resource is deleted when it
is checked in.
Fork, Merge
When a second successor is added to a version, this creates a
"fork" in the version history. When a version is created with
multiple predecessors, this creates a "merge" in the version
history. A server may restrict the version history to be linear
(with no forks or merges), but an interoperable versioning client
should be prepared to deal with both forks and merges in the
version history.
The following diagram illustrates several of the previous
definitions. Each box represents a version and each line between two
boxes represents a predecessor/successor relationship. For example,
it shows V3 is a predecessor of V5, V7 is a successor of V5, V1 is an
ancestor of V4, and V7 is a descendant of V4. It also shows that
there is a fork at version V2 and a merge at version V7.
History of foo.html
+---+
Root Version -------> | | V1
+---+ ^
| |
| |
+---+ |
Version Name ----> V2 | | | Ancestor
+---+ |
/ \ |
/ \ |
+---+ +---+
| | V3 | | V4
^ +---+ +---+
| | | |
Predecessor | | | |
+---+ +---+ |
| | V5 | | V6 | Descendant
+---+ +---+ |
Successor | \ / |
| \ / |
v +---+ v
| | V7
+---+
Label
A "label" is a name that can be used to select a version from a
version history. A label can be assigned by either a client or
the server. The same label can be used in different version
histories.
1.4 Property Values
1.4.1 Initial Property Value
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
implementation dependent.
1.4.2 Protected Property Value
When a property of a specific kind of resource is "protected", the property value cannot be updated on that kind of resource except by a method explicitly defined as updating that specific property. In particular, a protected property cannot be updated with a PROPPATCH request. Note that a given property can be protected on one kind of resource, but not protected on another kind of resource.1.4.3 Computed Property Value
When a property is "computed", its value is defined in terms of a computation based on the content and other properties of that resource, or even of some other resource. When the semantics of a method is defined in this document, the effect of that method on non-computed properties will be specified; the effect of that method on computed properties will not be specified, but can be inferred from the computation defined for those properties. A computed property is always a protected property.1.4.4 Boolean Property Value
Some properties take a Boolean value of either "false" or "true".1.4.5 DAV:href Property Value
The DAV:href XML element is defined in RFC 2518, Section 12.3.1.5 DAV Namespace XML Elements in Request and Response Bodies
Although WebDAV request and response bodies can be extended by arbitrary XML elements, which can be ignored by the message recipient, an XML element in the DAV namespace MUST NOT be used in the request or response body of a versioning method unless that XML element is explicitly defined in an IETF RFC.1.6 Method Preconditions and Postconditions
A "precondition" of a method describes the state of the server that must be true for that method to be performed. A "postcondition" of a method describes the state of the server that must be true after that method has been completed. If a method precondition or postcondition for a request is not satisfied, the response status of the request MUST be either 403 (Forbidden) if the request should not be repeated because it will always fail, or 409 (Conflict) if it is expected that the user might be able to resolve the conflict and resubmit the request.
In order to allow better client handling of 403 and 409 responses, a distinct XML element type is associated with each method precondition and postcondition of a request. When a particular precondition is not satisfied or a particular postcondition cannot be achieved, the appropriate XML element MUST be returned as the child of a top-level DAV:error element in the response body, unless otherwise negotiated by the request. In a 207 Multi-Status response, the DAV:error element would appear in the appropriate DAV:responsedescription element.1.6.1 Example - CHECKOUT request with DAV:must-be-checked-in response
>>REQUEST CHECKOUT /foo.html HTTP/1.1 Host: www.webdav.org >>RESPONSE HTTP/1.1 409 Conflict Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:error xmlns:D="DAV:"> <D:must-be-checked-in/> </D:error> In this example, the request to CHECKOUT /foo.html fails because /foo.html is not checked in.1.7 Clarification of COPY Semantics with Overwrite:T
RFC 2518, Section 8.8.4 states: "If a resource exists at the destination and the Overwrite header is "T" then prior to performing the copy the server MUST perform a DELETE with "Depth: infinity" on the destination resource." The purpose of this sentence is to ensure that following a COPY, all destination resources have the same content and dead properties as the corresponding resources identified by the request-URL (where a resource with a given name relative to the Destination URL "corresponds" to a resource with the same name relative to the request-URL). If at the time of the request, there already is a resource at the destination that has the same resource type as the corresponding resource at the request-URL, that resource MUST NOT be deleted, but MUST be updated to have the content and dead properties
of its corresponding member. If a client wishes all resources at the destination to be deleted prior to the COPY, it MUST explicitly issue a DELETE request. The difference between updating a resource and replacing a resource with a new resource is especially important when resource history is being maintained (the former adds to an existing history, while the latter creates a new history). In addition, locking and access control constraints might allow you to update a resource, but not allow you to delete it and create a new one in its place. Note that this clarification does not apply to a MOVE request. A MOVE request with Overwrite:T MUST perform the DELETE with "Depth:infinity" on the destination resource prior to performing the MOVE.1.8 Versioning Methods and Write Locks
If a write-locked resource has a non-computed property defined by this document, the property value MUST NOT be changed by a request unless the appropriate lock token is included in the request. Since every method introduced in this document other than REPORT modifies at least one property defined by this document, every versioning method other than REPORT is affected by a write lock. In particular, the method MUST fail with a 423 (Locked) status if the resource is write-locked and the appropriate token is not specified in an If request header.2 Basic Versioning Features
Each basic versioning feature defines extensions to existing HTTP and WebDAV methods, as well as new resource types, live properties, and methods.2.1 Basic Versioning Packages
A server MAY support any combination of versioning features. However, in order to minimize the complexity of a WebDAV basic versioning client, a WebDAV basic versioning server SHOULD support one of the following three "packages" (feature sets): - Core-Versioning Package: version-control - Basic-Server-Workspace Package: version-control, workspace, version-history, checkout - Basic-Client-Workspace Package: version-control, working- resource, update, label
The core-versioning package supports linear versioning by both versioning-aware and versioning-unaware clients. A versioning-aware client can use reports and properties to access previous versions of a version-controlled resource. The basic workspace packages support parallel development of version-controlled resources. Each client has its own configuration of the shared version-controlled resources, and can make changes to its configuration without disturbing that of another client. In the basic-server-workspace package, all persistent state is maintained on the server. Each client has its own workspace resource allocated on the server, where each workspace identifies a configuration of the shared version-controlled resources. Each client makes changes to its workspace, and can transfer changes when appropriate from one workspace to another. The server workspace package is appropriate for clients with no local persistent state, or for clients that wish to expose their working configurations to other clients. In the basic-client-workspace package, each client maintains in local persistent storage the state for its configuration of the shared version-controlled resources. When a client is ready to make its changes visible to other clients, it allocates a set of "working resources" on the server, updates the content and dead properties of these working resources, and then uses the set of working resources to update the version-controlled resources. The working resources are used, instead of directly updating the version-controlled resources, so that sets of consistent updates can be prepared in parallel by multiple clients. Also, a working resource allows a client to prepare a single update that requires multiple server requests (e.g. updating both the content and dead properties of a resource requires both a PUT and a PROPPATCH). The client workspace package simplifies the server implementation by requiring each client to maintain its own namespace, but this requires that the clients have local persistent state, and does not allow clients to expose their working configurations to other clients. A server that supports both basic workspace packages will interoperate with all basic versioning clients.
2.2 Basic Versioning Semantics
2.2.1 Creating a Version-Controlled Resource
In order to track the history of the content and dead properties of a versionable resource, a user can put the resource under version control with a VERSION-CONTROL request. A VERSION-CONTROL request performs three distinct operations: 1) It creates a new "version history resource". In basic versioning, a version history resource is not assigned a URL, and hence is not visible in the http scheme URL space. However, when the version- history feature (see Section 5) is supported, this changes, and each version history resource is assigned a new distinct and unique server-defined URL. 2) It creates a new "version resource" and adds it to the new version history resource. The body and dead properties of the new version resource are a copy of those of the versionable resource. The server assigns the new version resource a new distinct and unique URL. 3) It converts the versionable resource into a "version-controlled resource". The version-controlled resource continues to be identified by the same URL that identified it as a versionable resource. As part of this conversion, it adds a DAV:checked-in property, whose value contains the URL of the new version resource. Note that a versionable resource and a version-controlled resource are not new types of resources (i.e. they introduce no new DAV:resourcetype), but rather they are any type of resource that supports the methods and live properties defined for them in this document, in addition to all the methods and live properties implied by their DAV:resourcetype. For example, a collection (whose DAV:resourcetype is DAV:collection) is a versionable resource if it supports the VERSION-CONTROL method, and is a version-controlled resource if it supports the version-controlled resource methods and live properties. In the following example, foo.html is a versionable resource that is put under version control. After the VERSION-CONTROL request succeeds, there are two additional resources: a new version history resource and a new version resource in that version history. The versionable resource is converted into a version-controlled resource, whose DAV:checked-in property identifies the new version resource.
The content and dead properties of a resource are represented by the
symbol appearing inside the box for that resource (e.g., "S1" in the
following example).
===VERSION-CONTROL==>
| +----+ version
| version- | | history
versionable | controlled +----+ resource
resource | resource |
/foo.html | /foo.html |
| v
+----+ | +----+ checked-in +----+ version
| S1 | | | S1 |----------->| S1 | resource
+----+ | +----+ +----+ /his/73/ver/1
Thus, whereas before the VERSION-CONTROL request there was only one,
non-version-controlled resource, after VERSION-CONTROL there are
three separate, distinct resources, each containing its own state and
properties: the version-controlled resource, the version resource,
and the version history resource. Since the version-controlled
resource and the version resource are separate, distinct resources,
when a method is applied to a version-controlled resource, it is only
applied to that version-controlled resource, and is not applied to
the version resource that is currently identified by the
DAV:checked-in property of that version-controlled resource.
Although the content and dead properties of a checked-in version-
controlled resource are required to be the same as those of its
current DAV:checked-in version, its live properties may differ. An
implementation may optimize storage by retrieving the content and
dead properties of a checked-in version-controlled resource from its
current DAV:checked-in version rather than storing them in the
version-controlled resource, but this is just an implementation
optimization.
Normally, a resource is placed under version control with an explicit
VERSION-CONTROL request. A server MAY automatically place every new
versionable resource under version control. In this case, the
resulting state on the server MUST be the same as if the client had
explicitly applied a VERSION-CONTROL request to the versionable
resource.
2.2.2 Modifying a Version-Controlled Resource
In order to use methods like PUT and PROPPATCH to directly modify the
content or dead properties of a version-controlled resource, the
version-controlled resource must first be checked out. When the
checked-out resource is checked in, a new version is created in the
version history of that version-controlled resource. The version that was checked out is remembered as the predecessor of the new version. The DAV:auto-version property (see Sections 3.2.2) of a checked-in version-controlled resource determines how it responds to a method that attempts to modify its content or dead properties. Possible responses include: - Fail the request. The resource requires an explicit CHECKOUT request for it to be modified (see Sections 4 and 9.2.1). - Automatically checkout the resource, perform the modification, and automatically checkin the resource. This ensures that every state of the resource is tracked by the server, but can result in an excessive number of versions being created. - Automatically checkout the resource, perform the modification, and then if the resource is not write-locked, automatically checkin the resource. If the resource is write-locked, it remains checked-out until the write-lock is removed (either explicitly through a subsequent UNLOCK request or implicitly through a time- out of the write-lock). This helps a locking client avoid the proliferation of versions, while still allowing a non-locking client to update the resource. - Automatically checkout the resource, perform the modification, and then leave the resource checked out. If the resource is write- locked, it will be automatically checked in when the write-lock is removed, but an explicit CHECKIN operation (see Section 4.4) is required for a non-write-locked resource. This minimizes the number of new versions that will be created by a versioning unaware client, but only a versioning aware client can create new versions of a non-write-locked resource. - Fail the request unless the resource is write-locked. If it is write-locked, automatically checkout the resource and perform the modification. The resource is automatically checked in when the write-lock is removed. This minimizes the number of new versions that will be created by a versioning unaware client, but never automatically checks out a resource that will not subsequently be automatically checked in.
The following diagram illustrates the effect of the checkout/checkin
process on a version-controlled resource and its version history.
The symbol inside a box (S1, S2, S3) represents the current content
and dead properties of the resource represented by that box. The
symbol next to a box (V1, V2, V3) represents the URL for that
resource.
===checkout==> ===PUT==> ===checkin==>
/foo.html (version-controlled resource)
+----+ | +----+ | +----+ | +----+
| S2 | | | S2 | | | S3 | | | S3 |
+----+ | +----+ | +----+ | +----+
Checked-In=V2|Checked-Out=V2|Checked-Out=V2|Checked-In=V3
/his/73 (version history for /foo.html)
+----+ | +----+ | +----+ | +----+
| S1 | V1 | | S1 | V1 | | S1 | V1 | | S1 | V1
+----+ | +----+ | +----+ | +----+
| | | | | | |
| | | | | | |
+----+ | +----+ | +----+ | +----+
| S2 | V2 | | S2 | V2 | | S2 | V2 | | S2 | V2
+----+ | +----+ | +----+ | +----+
| | | |
| | | |
| | | +----+
| | | | S3 | V3
| | | +----+
Note that a version captures only a defined subset of the state of a
resource. In particular, a version of a basic resource captures its
content and dead properties, but not its live properties.
2.2.3 Reporting
Some versioning information about a resource requires that parameters
be specified along with that request for information. Included in
basic versioning is the required support for an extensible reporting
mechanism, which includes a REPORT method as well as a live property
for determining what reports are supported by a particular resource.
The REPORT method is required by versioning, but it can be used in
non-versioning WebDAV extensions.
To allow a client to query the properties of all versions in the version history of a specified version-controlled resource, basic versioning provides the DAV:version-tree report (see Section 3.7). A more powerful version history reporting mechanism is provided by applying the DAV:expand-property report (see Section 3.8) to a version history resource (see Section 5).
(page 20 continued on part 2)
