As per Relevance of the word resource, we have this rfc below:
Network Working Group G.
Request for Comments: 3253 Rational
Category: Standards Track J.
T.
C.
J.
U.C. Santa
March 2002
Versioning Extensions to
(Web Distributed Authoring and Versioning
Status of this
This document specifies an Internet standards track protocol for
Internet community, and requests discussion and suggestions
improvements. Please refer to the current edition of the "
Official Protocol Standards" (STD 1) for the standardization
and status of this protocol. Distribution of this memo is unlimited
Copyright
Copyright (C) The Internet Society (2002). All Rights Reserved
This document specifies a set of methods, headers, and resource
that define the WebDAV (Web Distributed Authoring and Versioning
versioning extensions to the HTTP/1.1 protocol. WebDAV
will minimize the complexity of clients that are capable
interoperating with a variety of versioning repository managers,
facilitate widespread deployment of applications capable of
the WebDAV Versioning services. WebDAV versioning includes
versioning for versioning-unaware clients, version
management, workspace management, baseline management,
management, and URL namespace versioning
Table of
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
Clemm, et al. Standards Track [Page 1]
RFC 3253 Versioning Extensions to WebDAV March 2002
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
Clemm, et al. Standards Track [Page 2]
RFC 3253 Versioning Extensions to WebDAV March 2002
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
Clemm, et al. Standards Track [Page 3]
RFC 3253 Versioning Extensions to WebDAV March 2002
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
Clemm, et al. Standards Track [Page 4]
RFC 3253 Versioning Extensions to WebDAV March 2002
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
Clemm, et al. Standards Track [Page 5]
RFC 3253 Versioning Extensions to WebDAV March 2002
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
This document specifies a set of methods, headers, and
that define the WebDAV (Web Distributed Authoring and Versioning
versioning extensions to the HTTP/1.1 protocol. Versioning
concerned with tracking and accessing the history of important
of a web resource, such as a standalone web page. The benefits
versioning in the context of the worldwide web include
Clemm, et al. Standards Track [Page 6]
RFC 3253 Versioning Extensions to WebDAV March 2002
- A resource has an explicit history and a persistent
across the various states it has had during the course of
history. It allows browsing through past and alternative
of a resource. Frequently the modification and authorship
of a resource is critical information in itself
- Resource states (versions) are given stable names that can
externally stored links for annotation and link server support
Both annotation and link servers frequently need to store
references to portions of resources that are not under
direct control. By providing stable states of resources,
control systems allow not only stable pointers into
resources, but also well defined methods to determine
relationships of those states of a resource
WebDAV Versioning defines both basic and advanced
functionality
Basic versioning allows users to
- Put a resource under version
- Determine whether a resource is under version
- Determine whether a resource update will automatically be
as a new
- Create and access distinct versions of a
Advanced versioning provides additional functionality for
development and configuration management of sets of web resources
This document will first define the properties and method
for the basic versioning features, and then define the
properties and method semantics for the advanced versioning features
An implementer that is only interested in basic versioning
skip the advanced versioning sections (Section 10 to Section 14).
1.1 Relationship to
To maximize interoperability and the use of existing
functionality, versioning support is designed as extensions to
WebDAV protocol [RFC2518], which itself is an extension to the
protocol [RFC2616]. All method marshalling and
defined by RFC 2518 and RFC 2616 continue to hold, to ensure
versioning unaware clients can interoperate successfully
versioning servers. Although the versioning extensions are
to be orthogonal to most aspects of the WebDAV and HTTP protocols,
clarification to RFC 2518 is required for effective
versioning. This clarification is described in Section 1.7.
Clemm, et al. Standards Track [Page 7]
RFC 3253 Versioning Extensions to WebDAV March 2002
1.2 Notational
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
document are to be interpreted as described in RFC 2119.
The term "protected" is placed in parentheses following
definition of a protected property (see Section 1.4.2).
The term "computed" is placed in parentheses following the
of a computed property (see Section 1.4.3).
When an XML element type in the "DAV:" namespace is referenced
this document outside of the context of an XML fragment, the
"DAV:" will be prefixed to the element type
When a method is defined in this document, a list of
and postconditions will be defined for that method. If the
of an existing method is being extended, a list of
preconditions and postconditions will be defined. A precondition
postcondition is prefixed by a parenthesized XML element type
identifies that precondition or postcondition (see Section 1.6).
1.3
This document uses the terms defined in RFC 2616, in RFC 2518, and
this section. Section 2.2 defines the semantic versioning
underlying this terminology
Version Control, Checked-In, Checked-
"Version control" is a set of constraints on how a resource can
updated. A resource under version control is either in
"checked-in" or "checked-out" state, and the version
constraints apply only while the resource is in the checked-
state
Versionable
A "versionable resource" is a resource that can be put
version control
Version-Controlled
When a versionable resource is put under version control,
becomes a "version-controlled resource". A version-
resource can be "checked out" to allow modification of its
or dead properties by standard HTTP and WebDAV methods
Clemm, et al. Standards Track [Page 8]
RFC 3253 Versioning Extensions to WebDAV March 2002
Checked-Out
A "checked-out resource" is a resource under version control
is in the checked-out state
Version
A "version resource", or simply "version", is a resource
contains a copy of a particular state (content and
properties) of a version-controlled resource. A version
created by "checking in" a checked-out resource. The
allocates a distinct new URL for each new version, and this
will never be used to identify any resource other than
version. The content and dead properties of a version
change
Version History
A "version history resource", or simply "version history", is
resource that contains all the versions of a particular version
controlled resource
Version
A "version name" is a string chosen by the server to
one version of a version history from the other versions of
version history. Versions from different version histories
have the same version name
Predecessor, Successor, Ancestor,
When a version-controlled resource is checked out and
subsequently checked in, the version that was checked out
a "predecessor" of the version created by the checkin. A
can specify multiple predecessors for a new version if the
version is logically a merge of those predecessors. When
version is connected to another version by traversing one or
predecessor relations, it is called an "ancestor" of that version
The inverse of the predecessor and ancestor relations are
"successor" and "descendant" relations. Therefore, if X is
predecessor of Y, then Y is a successor of X, and if X is
ancestor of Y, then Y is a descendant of X
Root Version
The "root version resource", or simply "root version", is
version in a version history that is an ancestor of every
version in that version history
Clemm, et al. Standards Track [Page 9]
RFC 3253 Versioning Extensions to WebDAV March 2002
Workspace
A "workspace resource", or simply "workspace", is a
that contains at most one version-controlled resource for a
version history (see Section 6).
Working
A "working resource" is a checked-out resource created by
server at a server-defined URL when a version (instead of
version-controlled resource) is checked out. Unlike a checked-
version-controlled resource, a working resource is deleted when
is checked in
Fork,
When a second successor is added to a version, this creates
"fork" in the version history. When a version is created
multiple predecessors, this creates a "merge" in the
history. A server may restrict the version history to be
(with no forks or merges), but an interoperable versioning
should be prepared to deal with both forks and merges in
version history
Clemm, et al. Standards Track [Page 10]
RFC 3253 Versioning Extensions to WebDAV March 2002
The following diagram illustrates several of the
definitions. Each box represents a version and each line between
boxes represents a predecessor/successor relationship. For example
it shows V3 is a predecessor of V5, V7 is a successor of V5, V1 is
ancestor of V4, and V7 is a descendant of V4. It also shows
there is a fork at version V2 and a merge at version V7.
History of foo.
+---+
Root Version -------> | | V
+---+ ^
| |
| |
+---+ |
Version Name ----> V2 | | |
+---+ |
/ \ |
/ \ |
+---+ +---+
| | V3 | | V
^ +---+ +---+
| | | |
Predecessor | | | |
+---+ +---+ |
| | V5 | | V6 |
+---+ +---+ |
Successor | \ / |
| \ / |
v +---+
| | V
+---+
A "label" is a name that can be used to select a version from
version history. A label can be assigned by either a client
the server. The same label can be used in different
histories
1.4 Property
1.4.1 Initial Property
Unless an initial value of a property of a given type is defined
this document, the initial value of a property of that type
implementation dependent
Clemm, et al. Standards Track [Page 11]
RFC 3253 Versioning Extensions to WebDAV March 2002
1.4.2 Protected Property
When a property of a specific kind of resource is "protected",
property value cannot be updated on that kind of resource except by
method explicitly defined as updating that specific property.
particular, a protected property cannot be updated with a
request. Note that a given property can be protected on one kind
resource, but not protected on another kind of resource
1.4.3 Computed Property
When a property is "computed", its value is defined in terms of
computation based on the content and other properties of
resource, or even of some other resource. When the semantics of
method is defined in this document, the effect of that method
non-computed properties will be specified; the effect of that
on computed properties will not be specified, but can be
from the computation defined for those properties. A
property is always a protected property
1.4.4 Boolean Property
Some properties take a Boolean value of either "false" or "true".
1.4.5 DAV:href Property
The DAV:href XML element is defined in RFC 2518, Section 12.3.
1.5 DAV Namespace XML Elements in Request and Response
Although WebDAV request and response bodies can be extended
arbitrary XML elements, which can be ignored by the
recipient, an XML element in the DAV namespace MUST NOT be used
the request or response body of a versioning method unless that
element is explicitly defined in an IETF RFC
1.6 Method Preconditions and
A "precondition" of a method describes the state of the server
must be true for that method to be performed. A "postcondition" of
method describes the state of the server that must be true after
method has been completed. If a method precondition or
for a request is not satisfied, the response status of the
MUST be either 403 (Forbidden) if the request should not be
because it will always fail, or 409 (Conflict) if it is expected
the user might be able to resolve the conflict and resubmit
request
Clemm, et al. Standards Track [Page 12]
RFC 3253 Versioning Extensions to WebDAV March 2002
In order to allow better client handling of 403 and 409 responses,
distinct XML element type is associated with each method
and postcondition of a request. When a particular precondition
not satisfied or a particular postcondition cannot be achieved,
appropriate XML element MUST be returned as the child of a top-
DAV:error element in the response body, unless otherwise
by the request. In a 207 Multi-Status response, the DAV:
element would appear in the appropriate DAV:
element
1.6.1 Example - CHECKOUT request with DAV:must-be-checked-in
>>
CHECKOUT /foo.html HTTP/1.1
Host: www.webdav.
>>
HTTP/1.1 409
Content-Type: text/xml; charset="utf-8"
Content-Length:
encoding="utf-8" ?>
In this example, the request to CHECKOUT /foo.html fails
/foo.html is not checked in
1.7 Clarification of COPY Semantics with Overwrite:
RFC 2518, Section 8.8.4 states
"If a resource exists at the destination and the Overwrite header
"T" then prior to performing the copy the server MUST perform
DELETE with "Depth: infinity" on the destination resource."
The purpose of this sentence is to ensure that following a COPY,
destination resources have the same content and dead properties
the corresponding resources identified by the request-URL (where
resource with a given name relative to the Destination
"corresponds" to a resource with the same name relative to
request-URL). If at the time of the request, there already is
resource at the destination that has the same resource type as
corresponding resource at the request-URL, that resource MUST NOT
deleted, but MUST be updated to have the content and dead
Clemm, et al. Standards Track [Page 13]
RFC 3253 Versioning Extensions to WebDAV March 2002
of its corresponding member. If a client wishes all resources at
destination to be deleted prior to the COPY, it MUST explicitly
a DELETE request
The difference between updating a resource and replacing a
with a new resource is especially important when resource history
being maintained (the former adds to an existing history, while
latter creates a new history). In addition, locking and
control constraints might allow you to update a resource, but
allow you to delete it and create a new one in its place
Note that this clarification does not apply to a MOVE request.
MOVE request with Overwrite:T MUST perform the DELETE
"Depth:infinity" on the destination resource prior to performing
MOVE
1.8 Versioning Methods and Write
If a write-locked resource has a non-computed property defined
this document, the property value MUST NOT be changed by a
unless the appropriate lock token is included in the request.
every method introduced in this document other than REPORT
at least one property defined by this document, every
method other than REPORT is affected by a write lock. In particular
the method MUST fail with a 423 (Locked) status if the resource
write-locked and the appropriate token is not specified in an
request header
2 Basic Versioning
Each basic versioning feature defines extensions to existing HTTP
WebDAV methods, as well as new resource types, live properties,
methods
2.1 Basic Versioning
A server MAY support any combination of versioning features
However, in order to minimize the complexity of a WebDAV
versioning client, a WebDAV basic versioning server SHOULD
one of the following three "packages" (feature sets):
- Core-Versioning Package: version-
- Basic-Server-Workspace Package: version-control, workspace
version-history,
- Basic-Client-Workspace Package: version-control, working
resource, update,
Clemm, et al. Standards Track [Page 14]
RFC 3253 Versioning Extensions to WebDAV March 2002
The core-versioning package supports linear versioning by
versioning-aware and versioning-unaware clients. A versioning-
client can use reports and properties to access previous versions
a version-controlled resource
The basic workspace packages support parallel development
version-controlled resources. Each client has its own
of the shared version-controlled resources, and can make changes
its configuration without disturbing that of another client
In the basic-server-workspace package, all persistent state
maintained on the server. Each client has its own workspace
allocated on the server, where each workspace identifies
configuration of the shared version-controlled resources.
client makes changes to its workspace, and can transfer changes
appropriate from one workspace to another. The server
package is appropriate for clients with no local persistent state,
for clients that wish to expose their working configurations to
clients
In the basic-client-workspace package, each client maintains in
persistent storage the state for its configuration of the
version-controlled resources. When a client is ready to make
changes visible to other clients, it allocates a set of "
resources" on the server, updates the content and dead properties
these working resources, and then uses the set of working
to update the version-controlled resources. The working
are used, instead of directly updating the version-
resources, so that sets of consistent updates can be prepared
parallel by multiple clients. Also, a working resource allows
client to prepare a single update that requires multiple
requests (e.g. updating both the content and dead properties of
resource requires both a PUT and a PROPPATCH). The client
package simplifies the server implementation by requiring each
to maintain its own namespace, but this requires that the
have local persistent state, and does not allow clients to
their working configurations to other clients
A server that supports both basic workspace packages
interoperate with all basic versioning clients
Clemm, et al. Standards Track [Page 15]
RFC 3253 Versioning Extensions to WebDAV March 2002
2.2 Basic Versioning
2.2.1 Creating a Version-Controlled
In order to track the history of the content and dead properties of
versionable resource, a user can put the resource under
control with a VERSION-CONTROL request. A VERSION-CONTROL
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
visible in the http scheme URL space. However, when the version
history feature (see Section 5) is supported, this changes,
each version history resource is assigned a new distinct
unique server-defined URL
2) It creates a new "version resource" and adds it to the new
history resource. The body and dead properties of the new
resource are a copy of those of the versionable resource
The server assigns the new version resource a new distinct
unique URL
3) It converts the versionable resource into a "version-
resource". The version-controlled resource continues to
identified by the same URL that identified it as a
resource. As part of this conversion, it adds a DAV:checked-
property, whose value contains the URL of the new
resource
Note that a versionable resource and a version-controlled
are not new types of resources (i.e. they introduce no
DAV:resourcetype), but rather they are any type of resource
supports the methods and live properties defined for them in
document, in addition to all the methods and live properties
by their DAV:resourcetype. For example, a collection (
DAV:resourcetype is DAV:collection) is a versionable resource if
supports the VERSION-CONTROL method, and is a version-
resource if it supports the version-controlled resource methods
live properties
In the following example, foo.html is a versionable resource that
put under version control. After the VERSION-CONTROL
succeeds, there are two additional resources: a new version
resource and a new version resource in that version history.
versionable resource is converted into a version-controlled resource
whose DAV:checked-in property identifies the new version resource
Clemm, et al. Standards Track [Page 16]
RFC 3253 Versioning Extensions to WebDAV March 2002
The content and dead properties of a resource are represented by
symbol appearing inside the box for that resource (e.g., "S1" in
following example).
===VERSION-CONTROL==>
| +----+
| version- | |
versionable | controlled +----+
resource | resource |
/foo.html | /foo.html |
|
+----+ | +----+ checked-in +----+
| S1 | | | S1 |----------->| S1 |
+----+ | +----+ +----+ /his/73/ver/1
Thus, whereas before the VERSION-CONTROL request there was only one
non-version-controlled resource, after VERSION-CONTROL there
three separate, distinct resources, each containing its own state
properties: the version-controlled resource, the version resource
and the version history resource. Since the version-
resource and the version resource are separate, distinct resources
when a method is applied to a version-controlled resource, it is
applied to that version-controlled resource, and is not applied
the version resource that is currently identified by
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
current DAV:checked-in version, its live properties may differ.
implementation may optimize storage by retrieving the content
dead properties of a checked-in version-controlled resource from
current DAV:checked-in version rather than storing them in
version-controlled resource, but this is just an
optimization
Normally, a resource is placed under version control with an
VERSION-CONTROL request. A server MAY automatically place every
versionable resource under version control. In this case,
resulting state on the server MUST be the same as if the client
explicitly applied a VERSION-CONTROL request to the
resource
2.2.2 Modifying a Version-Controlled
In order to use methods like PUT and PROPPATCH to directly modify
content or dead properties of a version-controlled resource,
version-controlled resource must first be checked out. When
checked-out resource is checked in, a new version is created in
Clemm, et al. Standards Track [Page 17]
RFC 3253 Versioning Extensions to WebDAV March 2002
version history of that version-controlled resource. The
that was checked out is remembered as the predecessor of the
version
The DAV:auto-version property (see Sections 3.2.2) of a checked-
version-controlled resource determines how it responds to a
that attempts to modify its content or dead properties.
responses include
- Fail the request. The resource requires an explicit
request for it to be modified (see Sections 4 and 9.2.1).
- Automatically checkout the resource, perform the modification,
automatically checkin the resource. This ensures that every
of the resource is tracked by the server, but can result in
excessive number of versions being created
- Automatically checkout the resource, perform the modification,
then if the resource is not write-locked, automatically
the resource. If the resource is write-locked, it
checked-out until the write-lock is removed (either
through a subsequent UNLOCK request or implicitly through a time
out of the write-lock). This helps a locking client avoid
proliferation of versions, while still allowing a non-
client to update the resource
- Automatically checkout the resource, perform the modification,
then leave the resource checked out. If the resource is write
locked, it will be automatically checked in when the write-lock
removed, but an explicit CHECKIN operation (see Section 4.4)
required for a non-write-locked resource. This minimizes
number of new versions that will be created by a
unaware client, but only a versioning aware client can create
versions of a non-write-locked resource
- Fail the request unless the resource is write-locked. If it
write-locked, automatically checkout the resource and perform
modification. The resource is automatically checked in when
write-lock is removed. This minimizes the number of new
that will be created by a versioning unaware client, but
automatically checks out a resource that will not subsequently
automatically checked in
Clemm, et al. Standards Track [Page 18]
RFC 3253 Versioning Extensions to WebDAV March 2002
The following diagram illustrates the effect of the checkout/
process on a version-controlled resource and its version history
The symbol inside a box (S1, S2, S3) represents the current
and dead properties of the resource represented by that box.
symbol next to a box (V1, V2, V3) represents the URL for
resource
===checkout==> ===PUT==> ===checkin==>
/foo.html (version-controlled resource
+----+ | +----+ | +----+ | +----+
| S2 | | | S2 | | | S3 | | | S3 |
+----+ | +----+ | +----+ | +----+
Checked-In=V2|Checked-Out=V2|Checked-Out=V2|Checked-In=V
/his/73 (version history for /foo.html
+----+ | +----+ | +----+ | +----+
| S1 | V1 | | S1 | V1 | | S1 | V1 | | S1 | V
+----+ | +----+ | +----+ | +----+
| | | | | | |
| | | | | | |
+----+ | +----+ | +----+ | +----+
| S2 | V2 | | S2 | V2 | | S2 | V2 | | S2 | V
+----+ | +----+ | +----+ | +----+
| | | |
| | | |
| | | +----+
| | | | S3 | V
| | | +----+
Note that a version captures only a defined subset of the state of
resource. In particular, a version of a basic resource captures
content and dead properties, but not its live properties
2.2.3
Some versioning information about a resource requires that
be specified along with that request for information. Included
basic versioning is the required support for an extensible
mechanism, which includes a REPORT method as well as a live
for determining what reports are supported by a particular resource
The REPORT method is required by versioning, but it can be used
non-versioning WebDAV extensions
Clemm, et al. Standards Track [Page 19]
RFC 3253 Versioning Extensions to WebDAV March 2002
To allow a client to query the properties of all versions in
version history of a specified version-controlled resource,
versioning provides the DAV:version-tree report (see Section 3.7).
more powerful version history reporting mechanism is provided
applying the DAV:expand-property report (see Section 3.8) to
version history resource (see Section 5).
3 Version-Control
The version-control feature provides support for putting a
under version control, creating an associated version-
resource and version history resource as described in Section 2.2.1.
A server indicates that it supports the version-control feature
including the string "version-control" as a field in the DAV
in the response to an OPTIONS request. The version-control
MUST be supported if any other versioning feature is supported
3.1 Additional Resource
The version-control feature introduces the following
properties for any WebDAV resource
3.1.1 DAV:
This property is used to track a brief comment about a resource
is suitable for presentation to a user. The DAV:comment of a
can be used to indicate why that version was created
PCDATA value:
3.1.2 DAV:creator-
This property contains a description of the creator of the
that is suitable for presentation to a user. The DAV:creator
displayname of a version can be used to indicate who created
version
PCDATA value:
3.1.3 DAV:supported-method-set (protected
This property identifies the methods that are supported by
resource. A method is supported by a resource if there is some
of that resource for which an application of that method
Clemm, et al. Standards Track [Page 20]
RFC 3253 Versioning Extensions to WebDAV March 2002
successfully satisfy all postconditions of that method, including
additional postconditions added by the features supported by
resource
supported-method-set (supported-method*)>
supported-method ANY
supported-method name NMTOKEN #REQUIRED
name value: a method
3.1.4 DAV:supported-live-property-set (protected
This property identifies the live properties that are supported
the resource. A live property is supported by a resource if
property has the semantics defined for that property. The value
this property MUST identify all live properties defined by
document that are supported by the resource, and SHOULD identify
live properties that are supported by the resource
supported-live-property-set (supported-live-property*)>
supported-live-property name
ANY value: a property element
3.1.5 DAV:supported-report-set (protected
This property identifies the reports that are supported by
resource
supported-report-set (supported-report*)>
supported-report report
ANY value: a report element
3.2 Version-Controlled Resource
The version-control feature introduces the following
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
properties as the version-controlled resource. This property
removed when the resource is checked out, and then added
(identifying a new version) when the resource is checked back in
Clemm, et al. Standards Track [Page 21]
RFC 3253 Versioning Extensions to WebDAV March 2002
3.2.2 DAV:auto-
If the DAV:auto-version value is DAV:checkout-checkin, when
modification request (such as PUT/PROPPATCH) is applied to
checked-in version-controlled resource, the request is
preceded by a checkout and followed by a checkin operation
If the DAV:auto-version value is DAV:checkout-unlocked-checkin,
a modification request is applied to a checked-in version-
resource, the request is automatically preceded by a
operation. If the resource is not write-locked, the request
automatically followed by a checkin operation
If the DAV:auto-version value is DAV:checkout, when a
request is applied to a checked-in version-controlled resource,
request is automatically preceded by a checkout operation
If the DAV:auto-version value is DAV:locked-checkout, when
modification request is applied to a write-locked checked-
version-controlled resource, the request is automatically preceded
a checkout operation
If an update to a write-locked checked-in resource is
preceded by a checkout of that resource, the checkout is
with the write lock. When this write lock is removed (e.g. from
UNLOCK or a lock timeout), if the resource has not yet been
in, the removal of the write lock is automatically preceded by
checkin operation
A server MAY refuse to allow the value of the DAV:auto-
property to be modified, or MAY only support values from a subset
the valid values
| checkout | locked-checkout)? >
3.3 Checked-Out Resource
The version-control feature introduces the following
properties for a checked-out resource
Clemm, et al. Standards Track [Page 22]
RFC 3253 Versioning Extensions to WebDAV March 2002
3.3.1 DAV:checked-out (protected
This property identifies the version that was identified by
DAV:checked-in property at the time the resource was checked out
This property is removed when the resource is checked in
3.3.2 DAV:predecessor-
This property determines the DAV:predecessor-set property of
version that results from checking in this resource
A server MAY reject attempts to modify the DAV:predecessor-set of
version-controlled resource
3.4 Version
The version-control feature introduces the following
properties for a version
3.4.1 DAV:predecessor-set (protected
This property identifies each predecessor of this version.
for the root version, which has no predecessors, each version has
least one predecessor
3.4.2 DAV:successor-set (computed
This property identifies each version whose DAV:predecessor-
identifies this version
3.4.3 DAV:checkout-set (computed
This property identifies each checked-out resource
DAV:checked-out property identifies this version
Clemm, et al. Standards Track [Page 23]
RFC 3253 Versioning Extensions to WebDAV March 2002
3.4.4 DAV:version-name (protected
This property contains a server-defined string that is different
each version in a given version history. This string is intended
display for a user, unlike the URL of a version, which is
only used by a client and not displayed for a user
PCDATA value:
3.5 VERSION-CONTROL
A VERSION-CONTROL request can be used to create a version-
resource at the request-URL. It can be applied to a
resource or to a version-controlled resource
If the request-URL identifies a versionable resource, a new
history resource is created, a new version is created whose
and dead properties are copied from the versionable resource, and
resource is given a DAV:checked-in property that is initialized
identify this new version
If the request-URL identifies a version-controlled resource,
resource just remains under version-control. This allows a client
be unaware of whether or not a server automatically puts a
under version control when it is created
If a VERSION-CONTROL request fails, the server state preceding
request MUST be restored
Marshalling
If a request body is included, it MUST be a DAV:version-
XML element
If a response body for a successful request is included, it
be a DAV:version-control-response XML element. Note that
document does not define any elements for the VERSION-
response body, but the DAV:version-control-response element
defined to ensure interoperability between future extensions
do define elements for the VERSION-CONTROL response body
response ANY
Clemm, et al. Standards Track [Page 24]
RFC 3253 Versioning Extensions to WebDAV March 2002
Postconditions
(DAV:put-under-version-control): If the request-URL identified
versionable resource at the time of the request, the request
have created a new version history and MUST have created a
version resource in that version history. The resource MUST
a DAV:checked-in property that identifies the new version.
content, dead properties, and DAV:resourcetype of the new
MUST be the same as those of the resource. Note that
implementation can choose to locate the version history
version resources anywhere that it wishes. In particular,
could locate them on the same host and server as the version
controlled resource, on a different virtual host maintained by
same server, on the same host maintained by a different server,
on a different host maintained by a different server
(DAV:must-not-change-existing-checked-in-out): If the request-
identified a resource already under version control at the time
the request, the request MUST NOT change the DAV:checked-in
DAV:checked-out property of that version-controlled resource
3.5.1 Example - VERSION-
>>
VERSION-CONTROL /foo.html HTTP/1.1
Host: www.webdav.
Content-Length: 0
>>
HTTP/1.1 200
In this example, /foo.html is put under version control. A
version history is created for it, and a new version is created
has a copy of the content and dead properties of /foo.html.
DAV:checked-in property of /foo.html identifies this new version
3.6 REPORT
A REPORT request is an extensible mechanism for obtaining
about a resource. Unlike a resource property, which has a
value, the value of a report can depend on additional
specified in the REPORT request body and in the REPORT
headers
Clemm, et al. Standards Track [Page 25]
RFC 3253 Versioning Extensions to WebDAV March 2002
Marshalling
The body of a REPORT request specifies which report is
requested, as well as any additional information that will be
to customize the report
The request MAY include a Depth header. If no Depth header
included, Depth:0 is assumed
The response body for a successful request MUST contain
requested report
If a Depth request header is included, the response MUST be a 207
Multi-Status. The request MUST be applied separately to
collection itself and to all members of the collection
satisfy the Depth value. The DAV:prop element of a DAV:
for a given resource MUST contain the requested report for
resource
Preconditions
(DAV:supported-report): The specified report MUST be supported
the resource identified by the request-URL
Postconditions
(DAV:no-modification): The REPORT method MUST NOT have changed
content or dead properties of any resource
3.7 DAV:version-tree
The DAV:version-tree report describes the requested properties of
the versions in the version history of a version. If the report
requested for a version-controlled resource, it is redirected to
DAV:checked-in or DAV:checked-out version
The DAV:version-tree report MUST be supported by all
resources and all version-controlled resources
Marshalling
The request body MUST be a DAV:version-tree XML element
ANY value: a sequence of zero or more elements, with at most
DAV:prop element
prop: see RFC 2518, Section 12.11
Clemm, et al. Standards Track [Page 26]
RFC 3253 Versioning Extensions to WebDAV March 2002
The response body for a successful request MUST be
DAV:multistatus XML element
multistatus: see RFC 2518, Section 12.9
The response body for a successful DAV:version-tree REPORT
MUST contain a DAV:response element for each version in
version history of the version identified by the request-URL
3.7.1 Example - DAV:version-tree
The version history drawn below would produce the following
tree report
foo.html
+---+
| | V
+---+
/ \
/ \
+---+ +---+
| | V2 | | V2.1.1
+---+ +---+
>>
REPORT /foo.html HTTP/1.1
Host: www.webdav.
Content-Type: text/xml; charset="utf-8"
Content-Length:
encoding="utf-8" ?>
Clemm, et al. Standards Track [Page 27]
RFC 3253 Versioning Extensions to WebDAV March 2002
>>
HTTP/1.1 207 Multi-
Content-Type: text/xml; charset="utf-8"
Content-Length:
encoding="utf-8" ?>
response
http://repo.webdav.org/his/23/ver/V1
V1
Fred
http://repo.webdav.org/his/23/ver/V2
http://repo.webdav.org/his/23/ver/V2.1.1
HTTP/1.1 200 OK
response
response
http://repo.webdav.org/his/23/ver/V2
V2
Fred
HTTP/1.1 200 OK
response
response
http://repo.webdav.org/his/23/ver/V2.1.1
V2.1.1
Sally
HTTP/1.1 200 OK
response
Clemm, et al. Standards Track [Page 28]
RFC 3253 Versioning Extensions to WebDAV March 2002
3.8 DAV:expand-property
Many 