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..........................................118
1 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 RFC2518 and RFC2616 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 RFC2518 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 RFC2119.
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 RFC2616, in RFC2518, 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 RFC2518, 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
RFC2518, 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).
3 Version-Control Feature
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.
3.1 Additional Resource Properties
The version-control feature introduces the following REQUIRED
properties for any WebDAV resource.
3.1.1 DAV:comment
This property is used to track a brief comment about a resource that
is suitable for presentation to a user. The DAV:comment of a version
can be used to indicate why that version was created.
<!ELEMENT comment (#PCDATA)>
PCDATA value: string
3.1.2 DAV:creator-displayname
This property contains a description of the creator of the resource
that is suitable for presentation to a user. The DAV:creator-
displayname of a version can be used to indicate who created that
version.
<!ELEMENT creator-displayname (#PCDATA)>
PCDATA value: string
3.1.3 DAV:supported-method-set (protected)
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
3.1.4 DAV:supported-live-property-set (protected)
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 name>
<!ELEMENT prop ANY>
ANY value: a property element type
3.1.5 DAV:supported-report-set (protected)
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
3.2 Version-Controlled Resource Properties
The version-control feature introduces the following REQUIRED
properties for a version-controlled resource.
3.2.1 DAV:checked-in (protected)
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)>
3.2.2 DAV:auto-version
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.