|
draft-ietf-webdav-versioning-xx.7 Expires April 16, 2004 |
G. Clemm IBM J. Amsden IBM T. Ellison IBM Chris Kaler Microsoft Jim Whitehead U.C. Santa Cruz
|
Versioning Extensions to WebDAV
Status of this Memo
This document is an Internet-Draft and is in full conformance with all provisions of RFC 2026, Section 10.
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 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.4.2 Protected Property Value
1.5 DAV Namespace XML Elements in
Request and Response Bodies
1.6 Method Preconditions and
Postconditions
1.6.1 Example - CHECKOUT request with
DAV:must-be-checked-in response
1.7 Clarification of COPY Semantics
with Overwrite:T
1.8 Versioning Methods and Write Locks
2.2 Basic Versioning Semantics
2.2.1 Creating a Version-Controlled
Resource
2.2.2 Modifying a Version-Controlled
Resource
3.1 Additional Resource Properties
3.1.3 DAV:supported-method-set (protected)
3.1.4 DAV:supported-live-property-set
(protected)
3.1.5 DAV:supported-report-set (protected)
3.2 Version-Controlled Resource
Properties
3.2.1 DAV:checked-in (protected)
3.3 Checked-Out Resource Properties
3.3.1 DAV:checked-out (protected)
3.4.1 DAV:predecessor-set (protected)
3.4.2 DAV:successor-set (computed)
3.4.3 DAV:checkout-set (computed)
3.4.4 DAV:version-name (protected)
3.5.1 Example - VERSION-CONTROL
3.7.1 Example - DAV:version-tree Report
3.8 DAV:expand-property Report
3.8.1 Example - DAV:expand-property
3.9 Additional OPTIONS Semantics
3.11 Additional
PROPFIND Semantics
3.12 Additional
PROPPATCH Semantics
3.13 Additional
DELETE Semantics
3.14 Additional
COPY Semantics
3.15 Additional
MOVE Semantics
3.16 Additional
UNLOCK Semantics
4.1 Additional Version Properties
4.2 Checked-Out Resource Properties
4.3 CHECKOUT Method (applied to a
version-controlled resource)
4.3.1 Example - CHECKOUT of a
version-controlled resource
4.4 CHECKIN Method (applied to a version-controlled
resource)
4.6 Additional OPTIONS Semantics
5.1 Version History Properties
5.1.1 DAV:version-set (protected)
5.1.2 DAV:root-version (computed)
5.2 Additional Version-Controlled
Resource Properties
5.2.1 DAV:version-history (computed)
5.3 Additional Version Properties
5.3.1 DAV:version-history (computed)
5.4 DAV:locate-by-history Report
5.4.1 Example - DAV:locate-by-history
Report
5.5 Additional OPTIONS Semantics
5.6 Additional DELETE Semantics
5.9 Additional VERSION-CONTROL
Semantics
5.10 Additional
CHECKIN Semantics
6.1.1 DAV:workspace-checkout-set (computed)
6.2 Additional Resource Properties
6.2.1 DAV:workspace (protected)
6.4 Additional OPTIONS Semantics
6.5 Additional DELETE Semantics
6.7 Additional VERSION-CONTROL
Semantics
6.7.1 Example - VERSION-CONTROL (using an
existing version history)
7.2 Additional OPTIONS Semantics
8.1 Additional Version Properties
8.1.1 DAV:label-name-set (protected)
8.2.1 Example - Setting a label
8.3 DAV:labeled-version Report
8.3.1 Example - DAV:labeled-version Report
8.4 Additional OPTIONS Semantics
8.5 Additional UPDATE Semantics
9.1 Additional Version Properties
9.2 Working Resource Properties
9.2.1 DAV:auto-update (protected)
9.3 CHECKOUT Method (applied to a
version)
9.3.1 Example - CHECKOUT of a version
9.4 CHECKIN Method (applied to a
working resource)
9.4.1 Example - CHECKIN of a working
resource
9.5 Additional OPTIONS Semantics
10 Advanced Versioning
Features
10.1 Advanced
Versioning Packages
10.2 Advanced
Versioning Terms
11.1 Additional
Checked-Out Resource Properties
11.3.1 Example - DAV:merge-preview Report
11.4 Additional
OPTIONS Semantics
11.5 Additional
DELETE Semantics
11.6 Additional
CHECKIN Semantics
12.1 Version-Controlled
Configuration Properties
12.1.1 DAV:baseline-controlled-collection
(protected)
12.2 Checked-Out
Configuration Properties
12.3.1 DAV:baseline-collection (protected)
12.3.2 DAV:subbaseline-set (protected)
12.4 Additional
Resource Properties
12.4.1 DAV:version-controlled-configuration
(computed)
12.5 Additional
Workspace Properties
12.5.1 DAV:baseline-controlled-collection-set
(computed)
12.6.1 Example - BASELINE-CONTROL
12.7 DAV:compare-baseline
Report
12.7.1 Example - DAV:compare-baseline
Report
12.8 Additional
OPTIONS Semantics
12.9 Additional
MKCOL Semantics
12.10 Additional
COPY Semantics
12.11 Additional
CHECKOUT Semantics
12.12 Additional
CHECKIN Semantics
12.13 Additional
UPDATE Semantics
12.14 Additional
MERGE Semantics
13.1.1 DAV:activity-version-set (computed)
13.1.2 DAV:activity-checkout-set
(computed)
13.1.4 DAV:current-workspace-set
(computed)
13.2 Additional
Version Properties
13.3 Additional
Checked-Out Resource Properties
13.4 Additional
Workspace Properties
13.4.1 DAV:current-activity-set
13.6 DAV:latest-activity-version
Report
13.7 Additional
OPTIONS Semantics
13.8 Additional
DELETE Semantics
13.9 Additional
MOVE Semantics
13.10 Additional
CHECKOUT Semantics
13.10.1 Example - CHECKOUT with an activity
13.11 Additional
CHECKIN Semantics
13.12 Additional
MERGE Semantics
14 Version-Controlled-Collection
Feature
14.1 Version-Controlled
Collection Properties
14.1.1 DAV:eclipsed-set (computed)
14.2 Collection
Version Properties
14.2.1 DAV:version-controlled-binding-set
(protected)
14.3 Additional
OPTIONS Semantics
14.4 Additional
DELETE Semantics
14.5 Additional
MKCOL Semantics
14.6 Additional
COPY Semantics
14.7 Additional
MOVE Semantics
14.8 Additional
VERSION-CONTROL Semantics
14.9 Additional
CHECKOUT Semantics
14.10 Additional
CHECKIN Semantics
14.11 Additional
UNCHECKOUT, UPDATE, and MERGE Semantics
14.12 Additional
DELETE Semantics
15 Internationalization
Considerations
16.1 Auditing
and Traceability
16.2 Increased
Need for Access Control
16.3 Security
Through Obscurity
21 Appendix A - Resource
Classification
21.1 DeltaV-Compliant
Unmapped URL (a URL that identifies no resource)
21.2 DeltaV-Compliant
Resource
21.3 DeltaV-Compliant
Collection
21.5 Version-Controlled
Resource
21.7 Checked-In
Version-Controlled Resource
21.9 Checked-Out
Version-Controlled Resource (checkout-in-place)
21.10 Working
Resource (working-resource)
21.11 Version
History (version-history)
21.14 Version-Controlled
Collection (version-controlled-collection)
21.15 Collection
Version (version-controlled-collection)
21.16 Version-Controlled
Configuration (baseline)
21.18 Checked-Out
Version-Controlled Configuration (baseline)
This document specifies a set of methods, headers, and properties that define the WebDAV 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).
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).
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.
Stable URL
A "stable URL" is a URL that is mapped to a resource when that resource is created, and that never is mapped to a different resource.
Version Resource
A "version resource", or simply "version", is a resource that is identified by a stable URL, and 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 content and dead properties of a version never change.
Version History Resource
A "version history resource", or simply "version history", is a resource that is identified by a stable URL, and 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.
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.
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.
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.
Some properties take a Boolean value of either "false" or "true".
The DAV:href XML element is defined in RFC 2518, Section 12.3. Whenever a DAV:href element in a property defined by this document contains a URL that identifies a version resource or a version history resource, that URL MUST be the stable URL for that resource.
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.
A "precondition" of a method describes the state on the server that must be true for that method to be performed. A "postcondition" of a method describes the state on the server that must be true after that method has 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.
>>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.
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.
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.
Each basic versioning feature defines extensions to existing HTTP and WebDAV methods, as well as new resource types, live properties, and methods.
Although a server MAY support any combination of versioning features, 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-in-place
- 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.
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 stable 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 stable 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 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 includes 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.
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.
===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.
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).
The version-control feature provides support for putting a resource under version control creating an associated version-controlled resource and version history resource as described in Section 2.2.1. A server indicates that it supports the version-control feature by including the string "version-control" as a field in the DAV header in the response to an OPTIONS request. The version-control feature MUST be supported if any other versioning feature is supported.
The version-control feature introduces the following REQUIRED properties for any WebDAV resource.
This property is used to track a brief comment about a resource that is suitable for presentation to a user. The DAV:comment of a version can be used to indicate why that version was created.
<!ELEMENT comment (#PCDATA)>
PCDATA value: string
This property contains a description of the creator of the resource that is suitable for presentation to a user. The DAV:creator-displayname of a version can be used to indicate who created that version.
<!ELEMENT creator-displayname (#PCDATA)>
PCDATA value: string
This property identifies the methods that are supported by the resource. A method is supported by a resource if there is some state of that resource for which an application of that method will successfully satisfy all postconditions of that method, including any additional postconditions added by the features supported by that resource.
<!ELEMENT supported-method-set (supported-method*)>
<!ELEMENT supported-method ANY>
<!ATTLIST supported-method name NMTOKEN #REQUIRED>
name value: a method name
This property identifies the live properties that are supported by the resource. A live property is supported by a resource if that property has the semantics defined for that property. The value of this property MUST identify all live properties defined by this document that are supported by the resource, and SHOULD identify all live properties that are supported by the resource.
<!ELEMENT supported-live-property-set (supported-live-property*)>
<!ELEMENT supported-live-property prop>
<!ELEMENT prop ANY>
ANY value: a property element type
This property identifies the reports that are supported by the resource.
<!ELEMENT supported-report-set (supported-report*)>
<!ELEMENT supported-report report>
<!ELEMENT report ANY>
ANY value: a report element type
The version-control feature introduces the following REQUIRED properties for a version-controlled resource.
This property appears on a checked-in version-controlled resource, and identifies a version that has the same content and dead properties as the version-controlled resource. This property is removed when the resource is checked out, and then added back (identifying a new version) when the resource is checked back in.
<!ELEMENT checked-in (href)>
If the DAV:auto-version value is DAV:checkout-checkin, when a modification request (such as PUT/PROPPATCH) is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout and followed by a checkin operation.
If the DAV:auto-version value is DAV:checkout-unlocked-checkin, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation. If the resource is not write-locked, the request is automatically followed by a checkin operation.
If the DAV:auto-version value is DAV:checkout, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation.
If the DAV:auto-version value is DAV:locked-checkout, when a modification request is applied to a write-locked checked-in version-controlled resource, the request is automatically preceded by a checkout operation.
If an update to a write-locked checked-in resource is automatically preceded by a checkout of that resource, the checkout is associated with the write-lock. When this write lock is removed (e.g. from an UNLOCK or a lock timeout), if the resource has not yet been checked in, the removal of the write lock is automatically preceded by a checkin operation.
A server MAY refuse to allow the value of the DAV:auto-version property to be modified, or MAY only support values from a subset of the valid values.
<!ELEMENT auto-version
(checkout-checkin | checkout-unlocked-checkin | checkout | locked-checkout)? >
<!ELEMENT checkout-checkin EMPTY>
<!ELEMENT checkout-unlocked-checkin EMPTY>
<!ELEMENT checkout EMPTY>
<!ELEMENT locked-checkout EMPTY>
The version-control feature introduces the following REQUIRED properties for a checked-out resource.
This property identifies the version that was identified by the DAV:checked-in property at the time the resource was checked out. This property is removed when the resource is checked in.
<!ELEMENT checked-out (href)>
This property determines the DAV:predecessor-set property of the version that results from checking in this resource.
A server MAY reject attempts to modify the DAV:predecessor-set of a version-controlled resource.
<!ELEMENT predecessor-set (href+)>
The version-control feature introduces the following REQUIRED properties for a version.
This property identifies each predecessor of this version. Except for the root version, which has no predecessors, each version has at least one predecessor.
<!ELEMENT predecessor-set (href*)>
This property identifies each version whose DAV:predecessor-set identifies this version.
<!ELEMENT successor-set (href*)>
This property identifies each checked-out resource whose DAV:checked-out property identifies this version.
<!ELEMENT checkout-set (href*)>
This property contains a server-defined string that is different for each version in a given version history. This string is intended for display to a user, unlike the URL of a version, which is normally only used by a client and not displayed to a user.
<!ELEMENT version-name (#PCDATA)>
PCDATA value: string
A VERSION-CONTROL request can be used to create a version-controlled resource at the request-URL. It can be applied to a versionable resource or to a version-controlled resource.
If the request-URL identifies a versionable resource, a new version history resource is created, a new version is created whose content and dead properties are copied from the versionable resource, and the resource is given a DAV:checked-in property that is initialized to identify this new version.
If the request-URL identifies a version-controlled resource, the resource just remains under version-control. This allows a client to be unaware of whether or not a server automatically puts a resource under version control when it is created.
If a VERSION-CONTROL request fails, the server state preceding the request MUST be restored.
Marshalling:
If a request body is included, it MUST be a DAV:version-control XML element.
<!ELEMENT version-control ANY>
If the request-URL
identifies a versionable resource, the response to a successful request MUST include a Location header containing the
URL for the new version created by the request.
If a response body for a successful request is included, it MUST be a DAV:version-control-response XML element. Note that this document does not define any elements for the VERSION-CONTROL response body, but the DAV:version-control-response element is defined to ensure interoperability between future extensions that do define elements for the VERSION-CONTROL response body.
<!ELEMENT version-control-response ANY>
Postconditions:
(DAV:put-under-version-control): If the request-URL identified a versionable resource at the time of the request, the request MUST have created a new version history and MUST have created a new version resource in that version history. The resource MUST have a DAV:checked-in property that identifies the new version. The content, dead properties, and DAV:resourcetype of the new version MUST be the same as those of the resource. Note that an implementation can choose to locate the version history and version resources anywhere that it wishes. In particular, it could locate them on the same host and server as the version-controlled resource, on a different virtual host maintained by the same server, on the same host maintained by a different server, or on a different host maintained by a different server.
>>REQUEST
VERSION-CONTROL /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
In this example, /foo.html is put under version control. A new version history is created for it, and a new version is created that has a copy of the content and dead properties of /foo.html. The DAV:checked-in property of /foo.html identifies this new version.
A REPORT request is an extensible mechanism for obtaining information about a resource. Unlike a resource property, which has a single value, the value of a report can depend on additional information specified in the REPORT request body and in the REPORT request headers.
Marshalling:
The body of a REPORT request specifies which report is being requested, as well as any additional information that will be used to customize the report.
The request MAY include a Depth header. If no Depth header is included, Depth:0 is assumed.
The response body for a successful request MUST contain the requested report.
If a Depth request header is included, the response MUST be a 207 Multi-Status. The request MUST be applied separately to the collection itself and to all members of the collection that satisfy the Depth value. The DAV:prop element of a DAV:response for a given resource MUST contain the requested report for that resource. Note that using a DAV:prop element to contain reports is an extension of the definition of DAV:prop in RFC 2518, Section 12.11.
Preconditions:
(DAV:supported-report): The specified report MUST be supported by the resource identified by the request-URL.
(DAV:acceptable-depth): A server MAY reject a non-zero Depth request that would match more resources than the server is willing to handle in a single request.
Postconditions:
(DAV:no-modification): The REPORT method MUST NOT have changed the content or dead properties of any resource.
The DAV:version-tree report describes the requested properties of all the versions in the version history of a version. If the report is requested for a version-controlled resource, it is redirected to its DAV:checked-in or DAV:checked-out version.
The DAV:version-tree report MUST be supported by all version resources and all version-controlled resources.
Marshalling:
The request body MUST be a DAV:version-tree XML element.
<!ELEMENT version-tree ANY>
ANY value: a sequence of zero or more elements, with at most one DAV:prop element.
prop: see RFC 2518, Section 12.11
The response body for a successful request MUST be a DAV:multistatus XML element.
multistatus: see RFC 2518, Section 12.9
The response body for a successful DAV:version-tree REPORT request MUST include a DAV:response element for each version in the version history of the version identified by the request-URL.
The version history drawn below would produce the following version tree report.
foo.html History
+---+
| | V1
+---+
/ \
/ \
+---+ +---+
| | V2 | | V2.1.1
+---+ +---+
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-tree xmlns:D="DAV:">
<D:prop>
<D:version-name/>
<D:creator-displayname/>
<D:successor-set/>
</D:prop>
</D:version-tree>
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
<D:propstat>
<D:prop>
<D:version-name>V1</D:version-name>
<D:creator-displayname>Fred</D:creator-displayname>
<D:successor-set>
<D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
<D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
</D:successor-set>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
<D:propstat>
<D:prop>
<D:version-name>V2</D:version-name>
<D:creator-displayname>Fred</D:creator-displayname>
<D:successor-set/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
<D:propstat>
<D:prop>
<D:version-name>V2.1.1</D:version-name>
<D:creator-displayname>Sally</D:creator-displayname>
<D:successor-set/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
Many property values are defined as a DAV:href, or a set of DAV:href elements. The DAV:expand-property report provides a mechanism for retrieving in one request the properties from the resources identified by those DAV:href elements. This report not only decreases the number of requests required, but also allows the server to minimize the number of separate read transactions required on the underlying versioning store.
The DAV:expand-property report SHOULD be supported by all resources that support the REPORT method.
Marshalling:
The request body MUST be a DAV:expand-property XML element.
<!ELEMENT expand-property (property*)>
<!ELEMENT property (property*)>
<!ATTLIST property name NMTOKEN #REQUIRED>
name value: a property element type
<!ATTLIST property namespace NMTOKEN "DAV:">
namespace value: an XML namespace
The response body for a successful request MUST be a DAV:multistatus XML element.
multistatus: see RFC 2518, Section 12.9
The properties reported in the DAV:prop elements of the DAV:multistatus element MUST be those identified by the DAV:property elements in the DAV:expand-property element. If there are DAV:property elements nested within a DAV:property element, then every DAV:href in the value of the corresponding property is replaced by a DAV:response element whose DAV:prop elements report the values of the properties identified by the nested DAV:property elements. The nested DAV:property elements can in turn include DAV:property elements, so that multiple levels of DAV:href expansion can be requested.
Note that a validating parser MUST be aware that the DAV:expand-property report effectively modifies the DTD of every property by replacing every occurrence of "href" in the DTD with "href | response".
This example describes how to query a version-controlled resource to determine the DAV:creator-display-name and DAV:activity-set of every version in the version history of that version-controlled resource. This example assumes that the server supports the version-history feature (see Section 5).
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:expand-property xmlns:D="DAV:">
<D:property name="version-history">
<D:property name="version-set">
<D:property name="creator-displayname"/>
<D:property name="activity-set"/>
</D:property>
</D:property>
</D:expand-property>
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/foo.html</D:href>
<D:propstat>
<D:prop>
<D:version-history>
<D:response>
<D:href>http://repo.webdav.org/his/23</D:href>
<D:propstat>
<D:prop>
<D:version-set>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/1</D:href>
<D:propstat>
<D:prop>
<D:creator-displayname>Fred</D:creator-displayname>
<D:activity-set> <D:href>
http://www.webdav.org/ws/dev/sally
</D:href> </D:activity-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/2</D:href>
<D:propstat>
<D:prop>
<D:creator-displayname>Sally</D:creator-displayname>
<D:activity-set> <D:href>
http://repo.webdav.org/act/add-refresh-cmd
</D:href> </D:activity-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:version-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:version-history> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:multistatus>
If the server supports the version-control feature, it MUST include "version-control" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods.
Additional Preconditions:
(DAV:cannot-modify-version-controlled-content): If the request-URL identifies a resource with a DAV:checked-in property, the request MUST fail unless DAV:auto-version semantics will automatically check out the resource.
(DAV:cannot-modify-version): If the request-URL identifies a version, the request MUST fail.
If the request creates a new resource that is automatically placed under version control, all preconditions for VERSION-CONTROL apply to the request.
Additional Postconditions:
(DAV: