INTERNET-DRAFT Geoffrey Clemm, Rational Software
draft-ietf-deltav-versioning-11 Jim Amsden, IBM
Chris Kaler, Microsoft
Jim Whitehead, U.C.Irvine
Expires July 5, 2001 January 5, 2001
Versioning Extensions to WebDAV
Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of RFC 2026, Section 10.
Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF), its areas, and its working groups. Note that other groups
may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
This document specifies a set of methods, headers, and resource-types
that define the WebDAV Versioning extensions to the HTTP/1.1 protocol.
WebDAV Versioning will minimize the complexity of clients that are
capable of interoperating with a variety of versioning repository
managers, to facilitate widespread deployment of applications capable of
utilizing the WebDAV Versioning services. WebDAV Versioning includes:
- version history management with automatic versioning for
versioning-unaware clients,
- workspace, baseline, and activity management,
- URL namespace versioning
- variant management.
Clemm, et al. [Page 1]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Table of Contents
1 INTRODUCTION...........................................6
1.1 Rationale.............................................7
1.2 Relationship to DAV...................................8
1.3 Terms.................................................8
1.4 Optional Versioning Terms............................10
1.5 Notational Conventions...............................12
1.6 Common Property Values...............................12
1.6.1 Boolean Value....................................12
1.6.2 String Value.....................................12
1.6.3 Date-Time Value..................................12
1.6.4 DAV:href XML Element Value.......................13
1.7 Initial Property Value...............................13
1.8 Property Value Locking...............................13
2 CORE VERSIONING.......................................13
2.1 Core Versioning Semantics............................13
2.1.1 Creating a Version-Controlled Resource...........13
2.1.2 Modifying a Version-Controlled Resource..........14
2.2 Version-Controlled Resource Properties...............15
2.2.1 DAV:checked-in (protected)......................15
2.2.2 DAV:checked-out (protected)......................16
2.2.3 DAV:predecessor-set..............................16
2.2.4 DAV:precursor-set................................16
2.2.5 DAV:auto-version.................................16
2.3 Version Properties...................................16
2.3.1 DAV:version (protected)..........................17
2.3.2 DAV:predecessor-set (protected)..................17
2.3.3 DAV:successor-set (protected)....................17
2.3.4 DAV:checkout-set (protected).....................17
2.3.5 DAV:checkin-date (protected).....................17
2.3.6 DAV:version-name (protected).....................17
2.3.7 DAV:precursor-set (protected)....................18
2.4 VERSION-CONTROL Method...............................18
2.4.1 Example - VERSION-CONTROL........................19
2.5 DAV:version-tree REPORT..............................19
2.5.1 Example - DAV:version-tree-report................20
2.6 Additional OPTIONS Semantics.........................21
2.7 Additional PUT Semantics.............................21
2.8 Additional PROPPATCH Semantics.......................22
2.9 Additional DELETE Semantics..........................23
2.10 Additional COPY Semantics..........................23
2.11 Additional MOVE Semantics..........................24
2.12 Additional UNLOCK Semantics........................24
3 CHECKOUT OPTION.......................................25
3.1 CHECKOUT Method......................................25
3.1.1 Example - CHECKOUT of a version-controlled resource26
3.2 CHECKIN Method.......................................26
3.2.1 Example - CHECKIN................................27
3.3 UNCHECKOUT Method....................................28
3.3.1 Example - UNCHECKOUT.............................28
Clemm, et al. [Page 2]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
3.4 Additional OPTIONS Semantics.........................29
4 UPDATE OPTION.........................................29
4.1 UPDATE Method........................................29
4.1.1 Example - UPDATE.................................30
4.2 Additional OPTIONS Semantics.........................30
5 VERSION-HISTORY OPTION................................30
5.1 Version History Properties...........................30
5.1.1 DAV:version-set (protected)......................31
5.1.2 DAV:root-version (protected).....................31
5.2 Additional Version-Controlled Resource Properties....31
5.2.1 DAV:version-history (protected)..................31
5.3 Additional Version Properties........................31
5.3.1 DAV:version-history (protected)..................31
5.4 Additional OPTIONS Semantics.........................31
5.5 Additional DELETE Semantics..........................32
5.6 Additional COPY Semantics............................32
5.7 Additional MOVE Semantics............................32
5.8 Additional VERSION-CONTROL Semantics.................33
5.9 Additional CHECKIN Semantics.........................33
6 CLIENT-WORKSPACE OPTION...............................33
6.1 Working Resource Properties..........................33
6.2 Additional OPTIONS Semantics.........................34
6.3 Additional DELETE Semantics..........................34
6.4 Additional COPY Semantics............................34
6.5 Additional MOVE Semantics............................34
6.6 Additional CHECKOUT Semantics........................34
6.6.1 Example - CHECKOUT of a version..................35
6.7 Additional CHECKIN Semantics.........................35
6.7.1 Example - CHECKIN of a working resource..........36
7 SERVER-WORKSPACE OPTION...............................36
7.1 Workspace Properties.................................37
7.1.1 DAV:workspace-checkout-set (protected)...........37
7.2 Additional Resource Properties.......................37
7.2.1 DAV:workspace (protected)........................38
7.3 DAV:version-controlled-resource-url REPORT...........38
7.3.1 Example - DAV:version-controlled-resource-url REPORT 38
7.4 MKWORKSPACE Method...................................39
7.4.1 Example - MKWORKSPACE............................40
7.5 Additional OPTIONS Semantics.........................40
7.6 Additional MOVE Semantics............................41
7.7 Additional VERSION-CONTROL Semantics.................41
7.7.1 Example - VERSION-CONTROL (using an existing version history) 42
8 MERGE OPTION..........................................42
8.1 Additional Version-Controlled Resource Properties....43
8.1.1 DAV:merge-set....................................43
8.1.2 DAV:auto-merge-set...............................43
8.2 MERGE Method.........................................43
8.2.1 Example - MERGE..................................46
8.3 DAV:merge-preview REPORT.............................47
Clemm, et al. [Page 3]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
8.3.1 Example - DAV:merge-preview-report...............48
8.4 Additional OPTIONS Semantics.........................49
8.5 Additional DELETE Semantics..........................49
8.6 Additional CHECKIN Semantics.........................49
9 LABEL OPTION..........................................49
9.1 Additional Version Properties........................50
9.1.1 DAV:label-name-set (protected)...................50
9.2 LABEL Method.........................................50
9.2.1 Example - Setting a label........................51
9.3 Label Header.........................................52
9.4 Additional OPTIONS Semantics.........................52
9.5 Additional GET Semantics.............................52
9.6 Additional PROPFIND Semantics........................53
9.7 Additional COPY Semantics............................53
9.8 Additional CHECKOUT Semantics........................54
9.9 Additional UPDATE Semantics..........................54
10 BASELINE OPTION......................................55
10.1 Baseline Selector Properties.......................56
10.1.1 DAV:baseline-controlled-collection (protected)...56
10.1.2 DAV:subbaseline-set..............................56
10.2 Baseline Properties................................57
10.2.1 DAV:version-set (protected)......................57
10.2.2 DAV:subbaseline-set (protected)..................57
10.3 Additional Collection Properties...................57
10.3.1 DAV:baseline-selector (protected)................57
10.4 BASELINE-CONTROL Method............................57
10.4.1 Example - BASELINE-CONTROL.......................59
10.5 DAV:baseline-version REPORT........................59
10.6 DAV:baseline-comparison REPORT.....................60
10.6.1 Example - DAV:baseline-comparison REPORT.........61
10.7 Additional OPTIONS Semantics.......................61
10.8 Additional MKCOL Semantics.........................62
10.9 Additional COPY Semantics..........................62
10.10 Additional CHECKIN Semantics.......................62
10.11 Additional UPDATE Semantics........................63
10.12 Additional MERGE Semantics.........................64
11 ACTIVITY OPTION......................................64
11.1 Activity Properties................................65
11.1.1 DAV:version-set (protected)......................65
11.1.2 DAV:activity-checkout-set (protected)............66
11.1.3 DAV:subactivity-set..............................66
11.1.4 DAV:current-workspace-set (protected)............66
11.2 Additional Version Properties......................66
11.2.1 DAV:activity-set.................................66
11.3 Additional Version-Controlled Resource Properties..66
11.3.1 DAV:unreserved...................................67
11.3.2 DAV:activity-set.................................67
11.4 Additional Workspace Properties....................67
11.4.1 DAV:current-activity-set.........................67
11.5 MKACTIVITY Method..................................67
11.5.1 Example - MKACTIVITY.............................68
Clemm, et al. [Page 4]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
11.6 DAV:latest-activity-version REPORT.................68
11.7 Additional OPTIONS Semantics.......................69
11.8 Additional DELETE Semantics........................70
11.9 Additional MOVE Semantics..........................70
11.10 Additional CHECKOUT Semantics......................70
11.10.1................Example - CHECKOUT with an activity 71
11.11 Additional CHECKIN Semantics.......................72
11.12 Additional MERGE Semantics.........................72
12 VERSION-CONTROLLED-COLLECTION OPTION.................73
12.1 Non-Version-Controlled Members of Version-Controlled Collections.75
12.2 Working Collections................................75
12.3 Additional OPTIONS Semantics.......................75
12.4 Additional PUT Semantics...........................76
12.5 Additional DELETE Semantics........................76
12.6 Additional MKCOL Semantics.........................76
12.7 Additional MOVE Semantics..........................76
12.8 Additional VERSION-CONTROL Semantics...............77
12.9 Additional CHECKIN Semantics.......................77
12.10 Additional UPDATE and MERGE Semantics..............77
13 FORK-CONTROL OPTION..................................78
13.1 Additional Version Properties......................78
13.1.1 DAV:checkout-fork................................78
13.1.2 DAV:checkin-fork.................................79
13.2 Additional Version-Controlled Resource Properties..79
13.2.1 DAV:checkout-fork................................79
13.2.2 DAV:checkin-fork.................................79
13.3 Additional OPTIONS Semantics.......................79
13.4 Additional CHECKOUT Semantics......................79
13.5 Additional CHECKIN Semantics.......................80
14 VARIANT OPTION.......................................80
14.1 Variant-Controlled Resource Properties.............81
14.1.1 DAV:variant-set (protected)......................81
14.1.2 DAV:default-variant (protected)..................81
14.2 Additional DELETE Semantics........................81
14.3 Additional MOVE Semantics..........................82
14.4 Additional VERSION-CONTROL Semantics...............82
14.5 Additional CHECKIN Semantics.......................82
14.6 Additional UPDATE Semantics........................83
15 INTERNATIONALIZATION CONSIDERATIONS..................83
16 SECURITY CONSIDERATIONS..............................84
17 AUTHENTICATION.......................................84
18 IANA CONSIDERATIONS..................................84
19 INTELLECTUAL PROPERTY................................85
20 ACKNOWLEDGEMENTS.....................................85
Clemm, et al. [Page 5]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
21 REFERENCES...........................................85
22 AUTHORS' ADDRESSES...................................86
23 APPENDIX A: CLARIFICATIONS AND EXTENSIONS TO RFC 251886
23.1 Additional Resource Properties.....................87
23.1.1 DAV:comment......................................87
23.1.2 DAV:creator-displayname..........................87
23.2 Response Bodies for 403 and 409 Status Responses...87
23.2.1 Example - CHECKOUT request with DAV:must-not-be-checked-out
response................................................87
23.3 Clarification of COPY Semantics with Overwrite:T...88
23.4 REPORT Method......................................88
23.4.1 Example - REPORT.................................89
23.4.2 Example - REPORT with Depth......................90
23.5 DAV:property REPORT................................90
23.5.1 Example - DAV:property-report....................91
23.6 Additional OPTIONS Semantics.......................93
23.6.1 Example - OPTIONS................................94
1 INTRODUCTION
This document defines WebDAV Versioning extensions, an application
of HTTP/1.1 for handling resource versioning in a WebDAV
environment. WebDAV Versioning defines both core and optional
versioning functionality. Core versioning allows authors to create
and access distinct versions of a resource, and provides automatic
versioning for versioning-unaware clients. All core versioning
functionality MUST be provided by a server that supports
versioning. An implementer that is only interesting in core
versioning should read Section 1 (Introduction), Section 2 (Core
Versioning), and Section 23 (Appendix A: Clarifications and
Extensions to RFC 2518).
Versioning options provide additional capabilities such as
workspace management, baselining, logical change tracking, merging,
and URL namespace versioning. The optional versioning capabilities
provided by a particular server can be discovered with an OPTIONS
request. The versioning options have been designed to be
logically orthogonal, so that a client can easily deal with servers
that support different sets of options. The exception is the
client-workspace and server-workspace options. These provide the
same logical functionality but with significantly different
client/server performance/complexity tradeoffs. It is expected that
a client will often be designed to interoperate with either a
client-workspace server or a server-workspace server, but not both.
This document will first define the properties and method semantics
for core versioning, and then define the additional properties and
method semantics for each versioning option.
Clemm, et al. [Page 6]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
1.1 Rationale
Versioning, parallel development, and configuration management are
important features for remote authoring of Web content. Version
management is concerned with tracking and accessing the history of
important states of a single Web resource, such as a standalone Web
page. Parallel development provides additional resource
availability in multi-user, distributed environments and lets
authors make changes on the same resource at the same time, and
merge those changes at some later date. Configuration management
addresses the problems of tracking and accessing multiple
interrelated resources over time as sets of resources, not simply
individual resources. Traditionally, artifacts of software
development, including code, design, test cases, requirements, and
help files, have been a focus of configuration management. Web
sites, comprised of multiple inter-linked resources (HTML,
graphics, sound, CGI, and others), are another class of complex
information artifacts that benefit from the application of
configuration management.
The benefits of versioning in the context of the worldwide web
include:
- It provides infrastructure for efficient and controlled
management of large evolving web sites. Modern configuration
management systems are built on some form of repository that can
track the version history of individual resources, and provide the
higher-level tools to manage those saved versions. Basic
versioning capabilities are required to support such systems.
- It allows parallel development and update of single resources.
Since versioning systems register change by creating new objects,
they enable simultaneous write access by allowing the creation of
multiple versions. Many also provide merge support to ease the
reverse operation.
- It provides a framework for coordinating changes to resources.
While specifics vary, most systems provide some method of
controlling or tracking access to enable collaborative resource
development.
- It represents the fact that 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.
- It provides 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
Clemm, et al. [Page 7]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
stable pointers into those resources, but also well defined methods
to determine the relationships of those states of a resource.
1.2 Relationship to DAV
To maximize interoperability and the use of existing protocol
functionality, versioning support is designed as extensions to the
WebDAV protocol [RFC2518]. The versioning extensions are designed
to be orthogonal to most aspects of the HTTP and WebDAV protocols,
but certain clarifications and extensions to RFC 2518 are required
for effective interoperable versioning. These clarifications and
extensions are described in Section 23.
1.3 Terms
This draft uses the terms defined in RFC 2616 and RFC 2518. In
addition, the following terms are defined.
Core Versioning
"Core versioning" is the set of properties and method semantics
that MUST be supported by all versioning servers.
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.
Version Resource
A "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 content and dead properties of a version MUST NOT
change. The server MUST allocate a distinct new URL for each new
version, and that URL MUST NOT ever identify any resource other
than that version.
Version History Resource
A "version history" is a resource that contains all the versions of
a particular version-controlled resource.
Clemm, et al. [Page 8]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
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
related to another version by 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" is the version in a version history that is an
ancestor of every other version in that version history.
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.
Clemm, et al. [Page 9]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
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
+---+
1.4 Optional Versioning Terms
The following terms are used to define the versioning options.
Version-Controlled Collection Resource
A "version-controlled collection" is a collection that is under
version control.
Collection Version Resource
A "collection version" is a version of a version-controlled
collection.
Working Resource
A "working resource" is a modifiable resource that results from
checking out a version. A working resource can be checked in to
create a new version.
Clemm, et al. [Page 10]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Workspace Resource
A "workspace" is a collection whose members are both version-
controlled and non-version-controlled resources. A workspace MUST
NOT contain two different version-controlled resources for the same
version history.
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.
Baseline Resource
A "baseline" is a special kind of version that selects the set of
versions that were identified by the DAV:checked-in property of
each member of a given collection. The baseline effectively
captures a "deep version" of that collection, which contains a
version of the collection itself as well as a version of every
member of that collection.
Baseline-Controlled Collection Resource
A "baseline-controlled collection" is a collection from which
baselines can be created.
Baseline Selector Resource
A "baseline selector" is a special kind of version-controlled
resource that is associated with a baseline-controlled collection,
and is checked out and checked in to create new baselines of that
collection.
Activity Resource
An "activity" is a non-versionable resource that selects a set of
versions that correspond to a single logical change, where the
versions selected from a given version history form a single line
of descent through that version history.
Variant Resource
A "variant" is a special kind of version-controlled resource whose
name is allocated by the server.
Variant-Controlled Resource
A "variant-controlled resource" is a special kind of version-
controlled resource that maintains a set of variants. Each variant
of a variant-controlled resource selects a version from the version
history of that variant-controlled resource.
Clemm, et al. [Page 11]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
1.5 Notational Conventions
The augmented BNF used by this document to describe protocol
elements is defined in RFC 2068, Section 2.1. Because this
augmented BNF uses the basic production rules provided in RFC 2068,
Section 2.2, those rules apply to this document as well.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in RFC 2119.
When a property of a resource is defined in this document, the term
"protected" is placed in parentheses following the property name to
indicate that the property value cannot be updated on that kind of
resource except by a method explicitly defined as updating that
specific property. In particular, a protected property cannot be
updated with a PROPPATCH request. Note that a given property can
be protected on one kind of resource, but not protected on another
kind of resource.
When 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 precondition or postcondition of a method is defined in this
document, it can be prefixed by a parenthesized XML element type.
If a precondition is violated by a request or a postcondition
cannot be satisfied, the XML element of the violated precondition
or unsatisfied postcondition will be returned in the response body
(see Section 23.2).
1.6 Common Property Values
1.6.1Boolean Value
Some properties take a Boolean value of either "false" or "true".
1.6.2String Value
A string is a sequence of characters. When a string is marshaled
in the header of an HTTP request, the characters are encoded using
the UTF-8 encoding scheme.
1.6.3Date-Time Value
Some properties take a date or time value. The syntax of date-time
is defined in RFC 2518, Section 23.2.
Clemm, et al. [Page 12]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
1.6.4DAV:href XML Element Value
The DAV:href XML element is defined in RFC 2518, Section 12.3.
1.7 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.8 Property Value Locking
If a write-locked resource has a 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.
2 CORE VERSIONING
Core versioning defines extensions to existing HTTP and WebDAV
methods, as well as new resource types, new live properties and new
methods. A server indicates that it supports core versioning by
including the string "version-control" as a field in the DAV header
in the response to an OPTIONS request. All methods, properties,
and behavior defined in core versioning MUST be supported by a
versioning server.
2.1 Core Versioning Semantics
2.1.1Creating a Version-Controlled Resource
In order to track the history of the content and dead properties of
a resource, an author can put the resource under version control
with a VERSION-CONTROL request. This creates a new version history
resource at a server defined location and creates a version in this
version history whose content and dead properties are a copy of the
current content and dead properties of the resource. The
DAV:checked-in property of the version-controlled resource is then
set to identify this version.
Note that a version-controlled resource and the current
DAV:checked-in version of that version-controlled resource are two
distinct resources, with their own content and properties. When a
method is applied to a version-controlled resource, it is applied
to that version-controlled resource and not to the DAV:checked-in
version 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
Clemm, et al. [Page 13]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
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.
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
new version resource is identified by the DAV:checked-in property
of the resource that is now under version control. 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==>
| +----+
| | | /repo/his/73
| +----+
| |
/foo.html | /foo.html |
| |
+----+ | +----+ checked-in +----+
| S1 | | | S1 | ---------- | S1 | /repo/ver/12
+----+ | +----+ +----+
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.1.2Modifying 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 author determines the checked-out resource is in a state that
should be retained, the author checks it in to create a new version
in the version history of that version-controlled resource. The
version that was checked out is remembered as the predecessor of
the new version.
In core versioning, a PUT or PROPPATCH to a version-controlled
resource with the DAV:auto-version property set will automatically
check out that resource prior to executing the PUT or PROPPATCH.
If that resource is write-locked, the resource remains checked-out
until the resource is unlocked, at which time the resource is
checked in and a new version is created in the version history of
that resource. If the resource is not write-locked, the resource
Clemm, et al. [Page 14]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
is automatically checked in and a new version is created
immediately after each successful PUT or PROPPATCH.
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
| | | +----+
2.2 Version-Controlled Resource Properties
WebDAV versioning introduces the following properties for a
version-controlled resource.
2.2.1DAV:checked-in (protected)
This property appears on a checked-in version-controlled resource,
and contains a URL for a version that has the same content and dead
properties as the version-controlled resource. This URL can be
used to retrieve this particular state of the version-controlled
resource after the version-controlled resource itself has been
modified.
Clemm, et al. [Page 15]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT checked-in (href)>
2.2.2DAV:checked-out (protected)
This property appears on a checked-out version-controlled resource,
and contains the value of the DAV:checked-in property at the time
the resource was checked out.
<!ELEMENT checked-out (href)>
2.2.3DAV:predecessor-set
This property appears on a checked-out version-controlled resource,
and determines the DAV:predecessor-set property of the version that
results from checking in this resource. A server MAY reject
attempts to modify the DAV:predecessor-set of a version-controlled
resource.
<!ELEMENT predecessor-set (href+)>
2.2.4DAV:precursor-set
This property appears on a checked-out version-controlled resource,
and determines the DAV:precursor-set property of the version that
results from checking in this resource.
<!ELEMENT precursor-set (href*)>
2.2.5DAV:auto-version
When the DAV:auto-version property of a checked-out version-
controlled resource is set, a modification request (such as
PUT/PROPPATCH) is automatically preceded by a checkout operation.
If the version-controlled resource is not write-locked, the
modification request is automatically followed by a checkin
operation. If the version-controlled resource is write-locked, the
resource is left checked-out and the automatic checkin operation is
deferred until the write lock is removed.
A server MAY refuse to allow the value of the DAV:auto-version
property to be modified.
<!ELEMENT auto-version (#PCDATA)>
PCDATA value: boolean
2.3 Version Properties
WebDAV versioning introduces the following properties for a
version.
Clemm, et al. [Page 16]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
2.3.1DAV:version (protected)
This property contains a server-defined URL that identifies this
version. This URL MUST NOT have previously identified any other
resource, and MUST NOT ever identify a resource other than this
version.
<!ELEMENT version (href)>
2.3.2DAV:predecessor-set (protected)
This property contains a URL for each predecessor of this version.
Except for the root version, which has no predecessors, each
version has at least one predecessor.
<!ELEMENT predecessor-set (href*)>
2.3.3DAV:successor-set (protected)
This property contains a URL for each version whose
DAV:predecessor-set identifies this version.
<!ELEMENT successor-set (href*)>
2.3.4DAV:checkout-set (protected)
This property contains a URL for each checked-out resource whose
DAV:checked-out property identifies this version.
<!ELEMENT checkout-set (href*)>
2.3.5DAV:checkin-date (protected)
This property contains the date on the server when the version was
checked in. This property MUST NOT be created by a server that
cannot provide a reasonable approximation of the current time.
<!ELEMENT checkin-date (#PCDATA)>
PCDATA value: date-time
2.3.6DAV:version-name (protected)
This property contains a server-defined string that is different
for each version in a given version history. This string is
intended for display to a user, unlike the URL of a version, which
is normally only used by a client and not displayed to a user.
<!ELEMENT version-name (#PCDATA)>
PCDATA value: string
Clemm, et al. [Page 17]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
2.3.7DAV:precursor-set (protected)
This property contains a URL for each version from a different
version history that was copied or merged into the checked-out
resource that created this version.
<!ELEMENT precursor-set (href*)>
2.4 VERSION-CONTROL Method
A VERSION-CONTROL request can be used to create a version-
controlled resource at the request-URL. It can be applied to a
versionable resource or to a version-controlled resource.
If the request-URL identifies a versionable resource, a new version
history resource is created, a new version is created whose content
and dead properties are those of the versionable resource, and the
resource is given a DAV:checked-in property that is initialized to
identify this new version.
If the request-URL identifies a version-controlled resource, the
request is ignored. This allows a client to be unaware of whether
or not a server automatically puts a resource under version control
when it is created.
If a VERSION-CONTROL request fails, the server state preceding the
request MUST be restored.
Marshalling:
If a response body is included, it MUST be a DAV:version-control
XML element.
<!ELEMENT version-control ANY>
ANY value: A sequence of elements with at most one DAV:already-
version-controlled element.
<!ELEMENT already-version-controlled EMPTY>
The response MUST include a Cache-Control:no-cache header.
Postconditions:
(DAV:put-under-version-control): If the request-URL identified a
versionable resource at the time of the request, a new version
history is created and a new version resource is created in the new
version history. The resource MUST have a DAV:checked-in property
that identifies the new version. The content, dead properties, and
DAV:resourcetype of the new version MUST be the same as those of
the resource. The DAV:checkin-date of the new version MUST be the
current date on the server. Note that an implementation can chose
to locate the version history and version resources anywhere that
it wishes. In particular, it could locate them on the same host
and server as the version-controlled resource, on a different
Clemm, et al. [Page 18]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
virtual host maintained by the same server, on the same host
maintained by a different server, or on a different host maintained
by a different server.
(DAV:already-under-version-control): If the request-URL identified
a resource already under version control at the time of the
request, the VERSION-CONTROL request MUST NOT change the state of
that version-controlled resource, and the DAV:checkout-response
body MUST contain a DAV:already-version-controlled element.
2.4.1Example - VERSION-CONTROL
>>REQUEST
VERSION-CONTROL /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, /foo.html is put under version control. A new
version history is created for it, and a new version is created
that has a copy of the content and dead properties of /foo.html.
The DAV:checked-in property of /foo.html identifies this new
version.
2.5 DAV:version-tree REPORT
The DAV:version-tree REPORT describes the requested properties of
all the versions in the version history of a version. This report
takes the form of a nested tree of versions. If the report is
requested for a version-controlled resource, it is redirected to
its DAV:checked-in or DAV:checked-out version.
Marshalling:
The DAV:version-tree REPORT request body MUST be a DAV:version-
tree-request XML element.
<!ELEMENT version-tree-request ANY>
ANY value: a sequence of zero or more elements, with at most one a
DAV:prop element.
prop: see RFC 2518, Section 12.11
The DAV:version-tree REPORT response body MUST be a DAV:version-
tree XML element.
<!ELEMENT version-tree (href, prop, version-tree*)>
Clemm, et al. [Page 19]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Postconditions:
(DAV:version-tree-OK): The response body MUST be a DAV:version-tree
element for the root version of the version history containing the
version identified by the request-URL. A DAV:version-tree element
contains a URL for a version followed by properties specified in
the request body and a DAV:version-tree for each successor of that
version. A server MAY omit the DAV:prop and the successor
DAV:version-tree elements for a version that has already appeared
in the DAV:version-tree report. This can provide significant space
savings when versions have multiple predecessors.
2.5.1Example - DAV:version-tree-report
The version history drawn below would produce the following version
tree report.
foo.html History
+---+
| | V1
+---+
/ \
/ \
+---+ +---+
| | V2 | | V2.1.1
+---+ +---+
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-tree-report xmlns:D="DAV:">
<D:prop>
<D:version-name/>
<D:creator-displayname/>
<D:predecessor-set/>
</D:prop>
</D:version-tree-report xmlns:D="DAV:">
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
Clemm, et al. [Page 20]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<D:version-tree xmlns:D="DAV:"/>
<D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
<D:prop>
<D:version-name>V1</D:version-name>
<D:creator-displayname>Fred</D:creator-displayname>
<D:predecessor-set/>
</D:prop>
<D:version-tree>
<D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
<D:prop>
<D:version-name>V2</D:version-name>
<D:creator-displayname>Fred</D:creator-displayname>
<D:predecessor-set>
<D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
</D:predecessor-set>
</D:prop>
</D:version-tree>
<D:version-tree>
<D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
<D:prop>
<D:version-name>V2.1.1</D:version-name>
<D:creator-displayname>Sally</D:creator-displayname>
<D:predecessor-set>
<D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
</D:predecessor-set>
</D:prop>
</D:version-tree>
</D:version-tree>
2.6 Additional OPTIONS Semantics
If the server supports versioning, it MUST include "version-
control" as a field in the DAV response header from an OPTIONS
request on any resource that supports any versioning properties,
reports, or methods.
2.7 Additional PUT Semantics
Additional Preconditions:
(DAV:cannot-modify-version-controlled-content): If the request-URL
identifies a resource with a DAV:checked-in property, the PUT MUST
fail unless DAV:auto-version is set for that resource.
(DAV:cannot-modify-version): If the request-URL identifies a
version, the PUT MUST fail.
Additional Postconditions:
If the request creates a new resource, the new resource MAY have
automatically been placed under version control, and all
postconditions for VERSION-CONTROL apply to the PUT.
Clemm, et al. [Page 21]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
(DAV:auto-checkout): If the DAV:checked-in and DAV:auto-version
properties of the resource were set prior to the request, and if
the resource is write-locked, then the value of the DAV:checked-out
property of the resource MUST be that of the DAV:checked-in
property prior to the request, the DAV:checked-in property MUST be
empty, and the DAV:predecessor-set property MUST be initialized to
be the same as the DAV:checked-out property.
(DAV:auto-checkout-checkin): If the DAV:checked-in and DAV:auto-
version property of the resource are set, and if the resource is
not write-locked, then the DAV:checked-in property of the resource
MUST identify a new revision whose content and dead properties are
the same as those of the resource. The DAV:predecessor-set of the
new revision MUST identify the version specified by the
DAV:checked-in property prior to the request.
2.8 Additional PROPPATCH Semantics
Additional Preconditions:
(DAV:cannot-modify-version-controlled-property): If the request-URL
identifies a checked-in version-controlled resource, an attempt to
modify a dead property MUST fail unless DAV:auto-version is set for
that version-controlled resource.
(DAV:cannot-modify-version): If the request-URL identifies a
version, an attempt to modify a dead property MUST fail.
(DAV:cannot-modify-protected-property): An attempt to use PROPPATCH
to modify a property (either core or optional) defined by this
document as being protected for that kind of resource MUST fail.
(DAV:cannot-modify-unsupported-property): An attempt to modify a
property defined by this document (either core or optional) whose
semantics are not enforced by the server MUST fail. This helps
ensure that a client will be notified when it is trying to use a
property whose semantics are not supported by the server.
Additional Postconditions:
(DAV:auto-checkout): If the DAV:checked-in and DAV:auto-version
property of the resource were set prior to the request, and if the
resource is write-locked, then the value of the DAV:checked-out
property of the resource MUST be that of the DAV:checked-in
property prior to the request, the DAV:checked-in property MUST be
empty, and the DAV:predecessor-set property MUST be initialized to
be the same as the DAV:checked-out property.
(DAV:auto-checkout-checkin): If the DAV:checked-in and DAV:auto-
version property of the resource are set, and if the resource is
not write-locked, then the DAV:checked-in property of the resource
MUST identify a new revision whose content and dead properties are
the same as those of the resource. The DAV:predecessor-set of the
Clemm, et al. [Page 22]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
new revision MUST identify the version specified by the
DAV:checked-in property prior to the request.
2.9 Additional DELETE Semantics
Additional Preconditions:
(DAV:cannot-delete-root-version): The root version of a version
history MUST NOT be deleted.
(DAV:cannot-delete-referenced-version): A version that is
identified in a DAV:checked-in or DAV:checked-out property MUST NOT
be deleted.
Additional Postconditions:
(DAV:no-version-delete): An implementation MAY fail an attempt to
DELETE a version.
(DAV:update-predecessor-set): If a version is deleted, any
reference to that version in a DAV:predecessor-set MUST be replaced
by a copy of the DAV:predecessor-set of the deleted version.
(DAV:update-successor-set): If a version is deleted, any reference
to that version in a DAV:successor-set MUST be replaced by a copy
of the DAV:successor-set of the deleted version.
(DAV:delete-checked-out-reference): If a checked-out version-
controlled resource is deleted, any reference to that version-
controlled resource in a DAV:checkout-set property MUST be removed.
2.10Additional COPY Semantics
Additional Postconditions:
The result of copying a version-controlled resource or a version is
a new non-version-controlled resource at the destination of the
COPY. The new resource MAY automatically be put under version
control, but the resulting version-controlled resource MUST be
associated with a new version history created for that new version-
controlled resource, and all postconditions for VERSION-CONTROL
apply to the COPY.
(DAV:initialize-precursor): If the source of the COPY was a version
and if the destination of the COPY supports the DAV:precursor-set
property, the DAV:precursor-set of the destination MUST identify
that version. If the source of the COPY was a version-controlled
resource, the DAV:precursor-set MUST identify the DAV:checked-in or
DAV:checked-out version of that resource.
(DAV:auto-checkout): If the DAV:checked-in and DAV:auto-version
property of the destination resource were set prior to the request,
Clemm, et al. [Page 23]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
and if the destination resource is write-locked, then the value of
the DAV:checked-out property of the destination resource MUST be
that of the DAV:checked-in property prior to the request, the
DAV:checked-in property MUST be empty, and the DAV:predecessor-set
property MUST be initialized to be the same as the DAV:checked-out
property.
(DAV:auto-checkout-checkin): If the DAV:checked-in and DAV:auto-
version property of the destination resource are set, and if the
destination resource is not write-locked, then the DAV:checked-in
property of the destination resource MUST identify a new revision
whose content and dead properties are the same as those of the
destination resource. The DAV:predecessor-set of the new revision
MUST identify the version specified by the DAV:checked-in property
prior to the request.
2.11Additional MOVE Semantics
Additional Preconditions:
(DAV:cannot-rename-resource): If the request-URL identifies a
version, the request MUST fail.
Additional Postconditions:
(DAV:preserve-history): When the request-URL identifies a version-
controlled resource, its DAV:checked-in and DAV:checked-out
properties MUST be the same before and after the request.
(DAV:update-checked-out-reference): If the request-URL identifies a
version-controlled resource, any reference to that version-
controlled resource in a DAV:checkout-set property MUST be updated
to refer to the new location of that version-controlled resource.
2.12Additional UNLOCK Semantics
Additional Preconditions:
(DAV:version-history-is-tree): If the request-URL identifies a
version-controlled resource that was automatically checked out
because DAV:auto-version was set, then the DAV:predecessor-set of
the resource MUST NOT be empty and the versions specified in the
DAV:predecessor-set MUST be in the same version history as the
DAV:checked-out version.
Additional Postconditions:
(DAV:create-version): If the request-URL identified a version-
controlled resource that was automatically checked out because
DAV:auto-version was set, a new version MUST have been created in
the version history of the DAV:checked-out version. The content,
dead properties, DAV:resourcetype, and DAV:predecessor-set of the
Clemm, et al. [Page 24]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
new version MUST be those of the checked-out resource. The
DAV:version-name of the new version MUST be set to a server-defined
value distinct from all other DAV:version-name values of other
versions in the version history of that version. The DAV:checkin-
date of the new version MUST be set to the current date on the
server. The DAV:version of the new version MUST be set to a new
server-allocated URL that MUST NOT have previously identified any
other resource, and MUST NOT ever identify a resource other than
this version. The DAV:checked-out property of the version-
controlled resource MUST have been removed, and a DAV:checked-in
property that identifies the new version MUST have been added.
3 CHECKOUT OPTION
In core versioning, WebDAV locking can be used to avoid the
proliferation of versions that would result if every modification
to a version-controlled resource produced a new version. The
checkout option provides an alternative mechanism that avoids the
complexity of the locking protocol. In particular, it does not
require the client to maintain any local state (such as a lock
token). Instead, a CHECKOUT method is provided for checking out a
version-controlled resource, a CHECKIN method is provided for
creating a new version by checking in a checked-out resource, and
an UNCHECKOUT method is provided for canceling a checkout and
returning the version-controlled resource to its state before the
checkout.
3.1 CHECKOUT Method
A CHECKOUT request can be applied to a checked-in version-
controlled resource to allow modifications to the content and dead
properties of that version-controlled resource.
If a CHECKOUT request fails, the server state preceding the request
MUST be restored.
Marshalling:
If a request body is included, it MUST be a DAV:checkout XML
element.
<!ELEMENT checkout ANY>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:must-be-checked-in): If a version-controlled resource is being
checked out, it MUST have a DAV:checked-in property value.
Clemm, et al. [Page 25]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Postconditions:
(DAV:is-checked-out): The checked-out resource MUST have a
DAV:checked-out property that contains the value of the
DAV:checked-in property preceding the checkout. The version-
controlled resource MUST NOT have a DAV:checked-in property value.
(DAV:initialize-predecessor-set): The DAV:predecessor-set property
of the checked-out resource MUST be initialized to be the
DAV:checked-out version.
3.1.1Example - CHECKOUT of a version-controlled resource
>>REQUEST
CHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, the version-controlled resource /foo.html is
checked out.
3.2 CHECKIN Method
A CHECKIN request can be applied to a checked-out version-
controlled resource to produce a new version whose content and dead
properties are those of the checked-out resource.
If a CHECKIN request fails, the server state preceding the request
MUST be restored.
Marshalling:
If a request body is included, it MUST be a DAV:checkin XML
element.
<!ELEMENT checkin ANY>
ANY value: A sequence of elements with at most one DAV:keep-
checked-out element.
<!ELEMENT keep-checked-out EMPTY>
The response MUST include a Location header.
The response MUST include a Cache-Control:no-cache header.
Clemm, et al. [Page 26]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Preconditions:
(DAV:must-be-checked-out): The request-URL MUST identify a resource
with a DAV:checked-out property.
(DAV:predecessor-in-checked-out-version-history): The versions
specified in the DAV:predecessor-set of the checked-out resource
MUST be in the same version history as the DAV:checked-out version.
(DAV:version-history-is-tree) The DAV:predecessor-set of the
checked-out resource MUST NOT be empty.
Postconditions:
(DAV:create-version): A new version MUST have been created in the
version history of the DAV:checked-out version. The URL for the
new version MUST be returned in a Location response header.
(DAV:initialize-version-content-and-properties): The content, dead
properties, DAV:resourcetype, and DAV:predecessor-set of the new
version MUST be those of the checked-out resource. The
DAV:version-name of the new version MUST be set to a server-defined
value distinct from all other DAV:version-name values of other
versions in the version history of that version. The DAV:checkin-
date of the new version MUST be set to the current date on the
server. The DAV:version of the new version MUST be set to a new
server-allocated URL that MUST NOT have previously identified any
other resource, and MUST NOT ever identify a resource other than
this version.
(DAV:checked-in): If the request-URL identifies a version-
controlled resource and DAV:keep-checked-out is not specified, the
DAV:checked-out property MUST have been removed and a DAV:checked-
in property containing the new version MUST have been added
(DAV:keep-checked-out): If DAV:keep-checked-out is specified, the
DAV:checked-out property of the checked-out resource MUST have been
updated to identify the new version.
3.2.1Example - CHECKIN
>>REQUEST
CHECKIN /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/his/23/ver/32
Cache-Control: no-cache
Clemm, et al. [Page 27]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
In this example, version-controlled resource /foo.html is checked
in, and a new version is created at
http://repo.webdav.org/his/23/ver/32.
3.3 UNCHECKOUT Method
An UNCHECKOUT request can be applied to a checked-out version-
controlled resource to cancel the CHECKOUT.
If an UNCHECKOUT request fails, the server state preceding the
request MUST be restored.
Marshalling:
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:must-be-checked-out-version-controlled-resource): The request-
URL MUST identify a version-controlled resource with a DAV:checked-
out property.
Postconditions:
(DAV:cancel-checked-out): The value of the DAV:checked-in property
is that of the DAV:checked-out property prior to the request, and
the DAV:checked-out property no longer is set.
(DAV:restore-content-and-dead-properties): The content and dead
properties of the version-controlled resource are those of its
DAV:checked-in version.
3.3.1Example - UNCHECKOUT
>>REQUEST
UNCHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, the content and dead properties of the version-
controlled resource identified by http://www.webdav.org/foo.html
are restored to their values preceding the most recent CHECKOUT of
that version-controlled resource.
Clemm, et al. [Page 28]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
3.4 Additional OPTIONS Semantics
If a server supports the checkout option, it MUST include
"checkout" as a field in the DAV response header from an OPTIONS
request on any resource that supports any versioning properties,
reports, or methods.
4 UPDATE OPTION
The update option provides a mechanism for restoring a previous
state of the version-controlled resource.
4.1 UPDATE Method
The UPDATE method modifies the content and dead properties of a
checked-in version-controlled resource to be those of a specified
version from the version history of that version-controlled
resource.
Marshalling:
The request-URL MUST identify the resource to be updated.
The request body MUST be a DAV:update element.
<!ELEMENT update ANY>
ANY value: A sequence of elements with at most one DAV:version
element.
<!ELEMENT version (href)>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:must-be-checked-in-version-controlled-resource): The request-
URL MUST identify a checked-in version-controlled resource.
(DAV:must-select-version): The DAV:version element in the request
body MUST identify a version in the same version history as the
DAV:checked-in version of the version-controlled resource
identified by the request-URL.
Postconditions:
(DAV:update-content-and-dead-properties): The content and dead
properties of the version-controlled resource MUST be the same as
those of the version specified by the DAV:version element in the
request body.
(DAV:update-checked-in-property): The DAV:checked-in property of
the version-controlled resource MUST contain the version identified
by the DAV:version element in the request body.
Clemm, et al. [Page 29]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
4.1.1Example - UPDATE
>>REQUEST
UPDATE /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:update xmlns:D="DAV:">
<D:version>
<D:href>http://repo.webdav.org/his/23/ver/33</D:href>
</D:version>
</D:update>
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, the content and dead properties of
http://repo.webdav.org/his/23/ver/33 are copied to the version-
controlled resource /foo.html, and the DAV:checked-in property of
/foo.html is updated to refer to
http://repo.webdav.org/his/23/ver/33.
4.2 Additional OPTIONS Semantics
If the server supports the update option, it MUST include "update"
as a field in the DAV response header from an OPTIONS request on
any resource that supports any versioning properties, reports, or
methods.
5 VERSION-HISTORY OPTION
It is often useful to have access to a version history even after
all version-controlled resources for that version history have been
deleted. A server can provide this functionality by supporting
version history resources. A version history resource exists in a
server defined namespace and therefore is unaffected by any
deletion or movement of version-controlled resources.
5.1 Version History Properties
The DAV:resourcetype of a version history MUST be DAV:version-
history.
The version-history option introduces the following properties for
a version history.
Clemm, et al. [Page 30]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
5.1.1DAV:version-set (protected)
This property contains a URL for each version of this version
history.
<!ELEMENT version-set (href+)>
5.1.2DAV:root-version (protected)
This property contains a URL for the root version of this version
history.
<!ELEMENT root-version (href)>
5.2 Additional Version-Controlled Resource Properties
The version-history option introduces the following properties for
a version-controlled resource.
5.2.1DAV:version-history (protected)
This property contains a URL for the version history associated
with this version-controlled resource.
<!ELEMENT version-history (href)>
5.3 Additional Version Properties
The version-history option introduces the following properties for
a version.
5.3.1DAV:version-history (protected)
This property contains a URL for the version history that contains
this version.
<!ELEMENT version-history (href)>
5.4 Additional OPTIONS Semantics
If the server supports the version-history option, it MUST include
"version-history" as a field in the DAV response header from an
OPTIONS request on any resource that supports any versioning
properties, reports, or methods.
The DAV:version-history-collection-set enumerates which collections
may contain version history resources. A version history
collection MAY be the root collection of a tree of collections, all
of which may contain version history resources. Since different
servers can control different parts of the URL namespace, different
resources on the same host MAY have different DAV:version-history-
collection-set values. The collections specified in the
Clemm, et al. [Page 31]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
DAV:version-history-collection-set MAY be located on different
hosts from the resource.
Additional Marshalling:
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one DAV:version-
history-collection-set element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one DAV:version-
history-collection-set element.
<!ELEMENT version-history-collection-set (href*)>
Additional Postconditions:
(DAV:version-history-collection-set-OK): If a DAV:version-history-
collection-set element is included in the request body, the
response body MUST contain a DAV:version-history-collection-set
element identifying which collections may contain version history
resources.
5.5 Additional DELETE Semantics
Additional Postconditions:
(DAV:delete-version-reference): If a version is deleted, any
reference to that version in a DAV:version-set MUST be removed.
(DAV:delete-version-set): If a version history is deleted, all
versions in the DAV:version-set of that version history MUST be
deleted.
5.6 Additional COPY Semantics
Additional Preconditions:
(DAV:cannot-copy-history): If the request-URL identifies a version
history, the request MUST fail. In order to create another version
history whose versions have the same content and dead properties,
the appropriate sequence of VERSION-CONTROL, CHECKOUT, PUT,
PROPPATCH, and CHECKIN requests must be made.
5.7 Additional MOVE Semantics
Additional Preconditions:
(DAV:cannot-rename-resource): If the request-URL identifies a
version history, the request MUST fail.
Clemm, et al. [Page 32]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
5.8 Additional VERSION-CONTROL Semantics
Additional Postconditions:
(DAV:set-version-history): The DAV:version-history of the version-
controlled resource MUST identify the version history of that
resource.
(DAV:new-version-history): If the request created a new version
history, the server MUST allocate a new server-defined URL for that
version history that MUST NOT have previously identified any other
resource, and MUST NOT ever identify a resource other than this
version history.
5.9 Additional CHECKIN Semantics
Additional Postconditions:
(DAV:preserve-version-history): The DAV:version-history of the new
version MUST be the DAV:version-history of the DAV:checked-out
version.
6 CLIENT-WORKSPACE OPTION
In order to allow two users to work concurrently on making changes
to the same resource, it is necessary to provide multiple checked
out resources for the same version history. Even if only one user
is making changes to a resource, it is sometimes desirable to be
able to make those changes (new versions) "in private" and then
expose that work at an appropriate later time. One way to provide
this functionality depends on persistent state being maintained on
the client. This is the client-workspace option defined in this
section. The other way to provide this functionality keeps all
persistent state on the server. This is the server-workspace
option defined in Section 7.
6.1 Working Resource Properties
A "working resource" is a resource created by the server 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. The server allocates a
distinct new URL for each new working resource.
A working resource has all the properties of a checked-out version-
controlled resource.
Clemm, et al. [Page 33]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
6.2 Additional OPTIONS Semantics
If the server supports the client-workspace option, it MUST include
"client-workspace" as a field in the DAV response header from an
OPTIONS request on any resource that supports any versioning
properties, reports, or methods.
6.3 Additional DELETE Semantics
Additional Postconditions:
(DAV:uncheckout-working-resource): If a working resource is
deleted, any reference to that working resource in a DAV:checkout-
set property MUST be removed. This effectively cancels the
CHECKOUT request that created the working resource.
6.4 Additional COPY Semantics
Additional Postconditions:
The result of copying a working resource is a new non-version-
controlled resource at the destination of the COPY. The new
resource MAY automatically be put under version control, but the
resulting version-controlled resource MUST be associated with a new
version history created for that new version-controlled resource.
6.5 Additional MOVE Semantics
Additional Preconditions:
(DAV:cannot-rename-resource): If the request-URL identifies a
working resource, the request MUST fail.
6.6 Additional CHECKOUT Semantics
A CHECKOUT request can be applied to a version to create a new
working resource. The content and dead properties of the working
resource are a copy of the version that was checked out.
Additional Marshalling:
<!ELEMENT checkout ANY>
ANY value: A sequence of elements with at most one DAV:apply-to-
version element.
<!ELEMENT apply-to-version EMPTY>
The response MAY include a Location header.
Clemm, et al. [Page 34]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Additional Postconditions:
(DAV:create-working-resource): If the request-URL identified a
version, the Location response header MUST contain the URL of a new
working resource. The DAV:checked-out property of the new working
resource MUST identify the version that was checked out. The
content and dead properties of the working resource MUST be the
same as the content and dead properties of the DAV:checked-out
version.
(DAV:create-working-resource-from-checked-in-version): If the
request-URL identified a version-controlled resource, and
DAV:apply-to-version is specified in the request body, the CHECKOUT
is applied to the DAV:checked-in version of the version-controlled
resource, and not the version-controlled resource itself. A new
working resource is created and the version-controlled resource
remains checked-in.
6.6.1Example - CHECKOUT of a version
>>REQUEST
CHECKOUT /his/12/ver/V3 HTTP/1.1
Host: repo.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/wr/157
Cache-Control: no-cache
In this example, the version identified by
http://repo.webdav.org/his/12/ver/V3 is checked out, and the new
working resource is located at http://repo.webdav.org/wr/157.
6.7 Additional CHECKIN Semantics
A CHECKIN request can be applied to a working resource to produce a
new version whose content and dead properties are those of the
working resource. Note that checking in a working resource does
not change the content or dead properties of any version-controlled
resource, therefore an UPDATE or MERGE request must be used to
update a version-controlled resource with the content and dead
properties of a version created by checking in a working resource.
Additional Postconditions:
(DAV:delete-working-resource): If the request-URL identifies a
working resource and if DAV:keep-checked-out is not specified, the
working resource is deleted.
Clemm, et al. [Page 35]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
6.7.1Example - CHECKIN of a working resource
>>REQUEST
CHECKIN /wr/157 HTTP/1.1
Host: repo.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/his/23/ver/15
Cache-Control: no-cache
In this example, the working resource /wr/157 checked in, and a new
version is created at http://repo.webdav.org/his/23/ver/15.
7 SERVER-WORKSPACE OPTION
It is often desirable to allow several clients on behalf of a
single user to access a related set of checked-out resources. In
particular, this allows a user to access these resources from
several physical locations, such as from another office, from home,
from a remote site, or while traveling, without being forced to
prematurely checkin those checked-out resources. Sometimes it is
even desirable to provide shared access to checked-out resources
for several closely cooperating users (using WebDAV locking to
avoid overwrite problems).
If only one set of checked-out resources is required, then this can
be achieved with core versioning by simply modifying write-locked
version-controlled resources. This approach is often unacceptable
because it exposes the intermediate states of the checked-out
resources to every client, and does not allow for a second set of
checked-out resources to be defined for a group that wishes to be
isolated from the intermediate states of another group.
A related problem is that it is often desirable to isolate clients
from a logical change that involves renaming shared resources,
until that logical change is complete and tested. When all clients
use a common set of shared version-controlled resources, every
client sees the result of a MOVE as soon as it occurs.
An additional problem is that it is often necessary to perform
testing on the server rather than on the client. Since a test
routine on the server has no way of knowing what working resources
or what versions are to be tested, only versions exposed through
version-controlled resources can be tested. This not only does not
allow testing of working resources, but also does not provide for
any parallel testing of different version configurations.
To address these problems, the server-workspace option introduces a
"workspace resource". A workspace resource is a collection whose
Clemm, et al. [Page 36]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
members are a set of related version-controlled and non-version-
controlled resources. In order to expose multiple views of a set
of related version-controlled resources in the URL namespace,
multiple workspaces may be used. In order to make a change made to
a version-controlled resource in one workspace visible in another
workspace, that version-controlled resource must be checked in, and
then the corresponding version-controlled resource in the other
workspace can be updated to display the content and dead properties
of the new version.
In order to ensure unambiguous merging (see Section 8) and
baselining (see Section 10) semantics, a workspace may contain at
most one version-controlled resource for a given version history
(although multiple collections in a workspace may contain bindings
to the same version-controlled resource). This is required for
unambiguous merging because the MERGE method must identify which
version-controlled resource is to be the merge target of a given
version. This is required for unambiguous baselining because a
baseline can only contain one version for a given version-
controlled resource.
Initially, an empty workspace can be created. Non-version-
controlled resources can then be added to the workspace with
standard WebDAV requests such as PUT and MKCOL. Version-controlled
resources can be added to the workspace with VERSION-CONTROL
requests. Alternatively, collections in the workspace can be
placed under baseline control, and then initialized by existing
baselines. In this case, the server creates a new version-
controlled resource in the workspace corresponding to each version
in the baseline.
7.1 Workspace Properties
The server-workspace option introduces the following properties for
a workspace.
7.1.1DAV:workspace-checkout-set (protected)
This property contains a URL for each checked-out resource that is
a member of this workspace.
<!ELEMENT workspace-checkout-set (href*)>
7.2 Additional Resource Properties
The server-workspace option introduces the following properties for
an HTTP resource.
Clemm, et al. [Page 37]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
7.2.1DAV:workspace (protected)
If the resource is associated with a workspace, this property
contains a URL that identifies this workspace.
<!ELEMENT workspace (href)>
The DAV:workspace property of a workspace MUST identify that
workspace. The DAV:workspace property of any other type of
resource MUST be the same as the DAV:workspace of its parent
collection.
7.3 DAV:version-controlled-resource-url REPORT
The DAV:version-controlled-resource-url REPORT can be applied to a
version history to locate the version-controlled resource for that
version history in a given workspace.
Marshalling:
The DAV:version-controlled-resource-url REPORT request body MUST be
a DAV:version-controlled-resource-url-request XML element.
<!ELEMENT version-controlled-resource-url-request (href)>
The DAV:version-controlled-resource REPORT response body MUST be a
DAV:version-controlled-resource XML element.
<!ELEMENT version-controlled-resource-url (href)>
Preconditions:
(DAV:workspace-required): The DAV:href in the request body MUST
identify a workspace.
Postconditions:
(DAV:version-controlled-resource-url-OK): The DAV:href of the
response body MUST identify a version-controlled resource that is a
member of the specified workspace, and whose DAV:version-history
property identifies the version history specified in the request
body.
7.3.1Example - DAV:version-controlled-resource-url REPORT
>>REQUEST
REPORT /his/23 HTTP/1.1
Host: repo.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Clemm, et al. [Page 38]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<?xml version="1.0" encoding="utf-8" ?>
<D:version-controlled-resource-url-request xmlns:D="DAV:">
<D:href>http://www.webdav.org/ws/public</D:href>
</D:version-controlled-resource-url-request>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-controlled-resource-url>
<D:href xmlns:D="DAV:">
http://www.webdav.org/ws/public/mycollection/test.html
</D:href>
</D:version-controlled-resource-url>
In this example, /ws/public/mycollection/test.html is identified as
the version-controlled resource whose version history is
http://repo.webdav.org/his/23.
7.4 MKWORKSPACE Method
A MKWORKSPACE request creates a new workspace resource. A server
MAY restrict workspace creation to particular collections, but a
client can determine the location of these collections from a
DAV:workspace-collection-set OPTIONS request.
If a MKWORKSPACE request fails, the server state preceding the
request MUST be restored.
Marshalling:
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:resource-must-be-null): A resource MUST NOT exist at the
request-URL.
(DAV:workspace-location-ok): The request-URL MUST identify a
location where a workspace can be created.
Postconditions:
(DAV:initialize-workspace-properties): A new workspace exists at
the request-URL. The DAV:resource type of the workspace MUST be
DAV:collection. The DAV:workspace of the workspace MUST contain
the request-URL. The DAV:workspace-checkout-set of the workspace
MUST be empty.
Clemm, et al. [Page 39]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
7.4.1Example - MKWORKSPACE
>>REQUEST
MKWORKSPACE /ws/public HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, a new workspace is created at
http://www.webdav.org/ws/public.
7.5 Additional OPTIONS Semantics
If a server supports the server-workspace option, it MUST include
"server-workspace" as a field in the DAV response header from an
OPTIONS request on any resource that supports any versioning
properties, reports, or methods.
If a server support the server-workspace option, it MUST also
support the checkout option and the version-history option.
Often a versioning implementation constrains where a workspace can
be located in the URL space. The DAV:workspace-collection-set
enumerates which collections may contain workspaces. A workspace
collection MAY be the root collection of a tree of collections, all
of which may contain workspaces. Since different servers can
control different parts of the URL namespace, different resources
on the same host MAY have different DAV:workspace-collection-set
values. The collections specified in the DAV:workspace-collection-
set MAY be located on different hosts from the resource.
Additional Marshalling:
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one DAV:workspace-
collection-set element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one DAV:workspace-
collection-set element.
<!ELEMENT workspace-collection-set (href*)>
Additional Postconditions:
(DAV:workspace-collection-set-OK): If DAV:workspace-collection-set
is included in the request body, the response body MUST contain a
Clemm, et al. [Page 40]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
DAV:workspace-collection-set element identifying which collections
may contain workspaces.
7.6 Additional MOVE Semantics
Additional Postconditions:
(DAV:workspace-member-moved): The DAV:workspace of the destination
MUST be updated to have the same value as the DAV:workspace of the
parent collection of the destination.
(DAV:workspace-moved): If the request-URL identifies a workspace,
any reference to that workspace in a DAV:workspace property MUST be
updated to refer to the new location of that workspace.
7.7 Additional VERSION-CONTROL Semantics
A VERSION-CONTROL request can be used to create a new version-
controlled resource for an existing version history. This allows
the creation of version-controlled resources for the same version
history in multiple workspaces.
Additional Marshalling:
<!ELEMENT version-control ANY>
ANY value: A sequence of elements with at most one DAV:version
element.
<!ELEMENT version (href)>
Additional Preconditions:
(DAV:cannot-add-to-existing-history): If the request-URL identifies
a versionable resource or a version-controlled resource, the
DAV:version-control request body element MUST NOT contain a
DAV:version element.
(DAV:must-be-version): The DAV:href of the DAV:version element
MUST identify a version.
(DAV:one-version-controlled-resource-per-history-per-workspace): If
the DAV:version-control request body identifies a version, and if
the request-URL is a member of a workspace, then there MUST NOT
already be a version-controlled member of that workspace whose
DAV:checked-in or DAV:checked-out property identifies a different
version from the version history of the specified version.
Additional Postconditions:
(DAV:new-version-controlled-resource): If the request-URL
identified a null resource, a new version-controlled resource
exists at the request-URL whose content and dead properties are
Clemm, et al. [Page 41]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
initialized by those of the version in the request body, and whose
DAV:checked-in property identifies that version.
7.7.1Example - VERSION-CONTROL (using an existing version history)
>>REQUEST
VERSION-CONTROL /ws/public/bar.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-control xmlns:D="DAV:">
<D:version>
<D:href>http://repo.webdav.org/his/12/ver/V3</D:href>
</D:version>
</D:version-control>
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, the null resource /ws/public/bar.html is put under
version control, and the content and dead properties of the new
version-controlled resource are those of the version identified by
http://repo.webdav.org/his/12/ver/V3.
8 MERGE OPTION
When an author wants to accept the changes (new versions) created
by someone else, it is important not to just update the version-
controlled resources in the author's workspace with those new
versions, since this could result in "backing out" changes the
author has made to those version-controlled resources. Instead,
the versions created in another workspace should be "merged" into
the author's version-controlled resources.
The version history of a version-controlled resource provides the
information needed to determine what should be the result of the
merge. In particular, the merge should select whichever version is
later in the line of descent from the root version. In case the
versions to be merged are on different lines of descent (neither
version is a descendant of the other), neither version should be
selected, but instead, a new version should be created that
contains the logical merge of the content and dead properties of
those versions. The MERGE request can be used to check out each
version-controlled resource with such a conflict, and set the
DAV:merge-set property of each checked-out resource to identify the
version to be merged. The author is responsible for modifying the
content and dead properties of the checked-out resource so that it
Clemm, et al. [Page 42]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
represents the logical merge of that version, and then adding that
version to the DAV:predecessor-set of the checked-out resource.
If the server is capable of automatically performing the merge, it
MAY update the content, dead properties, and DAV:predecessor-set of
the checked-out resource itself. Before checking in the
automatically merged resource, the author is responsible for
verifying that the automatic merge is correct.
8.1 Additional Version-Controlled Resource Properties
The merge option introduces the following properties for a version-
controlled resource.
8.1.1DAV:merge-set
This property of a checked-out version-controlled resource contains
a URL for each version that is to be merged into this version-
controlled resource.
<!ELEMENT merge-set (href*)>
8.1.2DAV:auto-merge-set
This property of a checked-out version-controlled resource contains
a URL for each version that the server has merged into this
version-controlled resource. The client should confirm that the
merge has been performed correctly before moving a URL from the
DAV:auto-merge-set to the DAV:predecessor-set of a checked-out
version-controlled resource.
<!ELEMENT auto-merge-set (href*)>
8.2 MERGE Method
The MERGE method performs a logical merge of a specified version
into a specified version-controlled resource. If the specified
version is neither an ancestor nor a descendant of the DAV:checked-
in or DAV:checked-out version of the version-controlled resource,
the MERGE checks out the version-controlled resource (if it is not
already checked out) and adds the URL of the specified version to
the DAV:merge-set of the version-controlled resource. It is then
the client's responsibility to update the content and dead
properties of the checked-out version-controlled resource so that
it reflects the logical merge of the specified version into the
current state of the version-controlled resource. The client
indicates that it has completed the update of the version-
controlled resource, by deleting the version URL from the
DAV:merge-set of the checked-out version-controlled resource, and
adding it to the DAV:predecessor-set. As an error check for a
client forgetting to complete a merge, the server MUST fail an
Clemm, et al. [Page 43]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
attempt to CHECKIN a version-controlled resource with a non-empty
DAV:merge-set.
When a server has the ability to automatically update the content
and dead properties of the version-controlled resource to reflect
the logical merge of the specified version, it may do so unless
DAV:no-auto-merge is specified in the MERGE request body. In order
to notify the client that a version has been automatically merged,
the MERGE request MUST add the URL of the auto-merged version to
the DAV:auto-merge-set property of the version-controlled
resource, and not to the DAV:merge-set property. The client
indicates that it has verified that the auto-merge is valid, by
deleting the version URL from the DAV:auto-merge-set, and adding it
to the DAV:predecessor-set.
In general, a MERGE request identifies a "merge source" that
specifies a set of versions (the "merge versions") and a "merge
destination" that specifies a set of version-controlled resources
(the "merge targets"). The set of merge versions is determined as
follows:
- If the merge source is a version, that version is the merge
version.
- If the merge source is a version-controlled resource, the
DAV:checked-in version of that version-controlled resource is the
merge version.
- If the merge source is a collection, the DAV:checked-in version
of each version-controlled resource in that collection (as well as
the DAV:checked-in version of the collection if it is version-
controlled) is a merge version.
For each merge version, the server determines the "merge target"
for that merge version. The merge target is the member of the
merge destination that is a version-controlled resource whose
DAV:checked-in or DAV:checked-out version is from the same version
history as the merge version. If a merge version has no merge
target, that merge version is reported by the MERGE as having been
ignored.
Marshalling:
The merge destination is identified by the request-URL.
The merge source is identified by the DAV:source element in the
request body.
The request body MUST be a DAV:merge element.
<!ELEMENT merge ANY>
ANY value: A sequence of elements with one DAV:source element, at
most one DAV:no-auto-merge element, at most one DAV:no-checkout
element, at most one DAV:prop element, and at most one of any
element that can occur in a DAV:checkout element.
<!ELEMENT source (href)>
Clemm, et al. [Page 44]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT no-auto-merge EMPTY>
<!ELEMENT no-checkout EMPTY>
prop: see RFC 2518, Section 12.11
The response body MUST contain a DAV:merge-response element.
<!ELEMENT merge-response ANY>
ANY value: A sequence of elements with at most one DAV:updated-set
element, at most one DAV:merged-set element, and at most one
DAV:ignored-set element.
<!ELEMENT updated-set (response+)>
<!ELEMENT merged-set (response+)>
<!ELEMENT ignored-set (href+)>
response: see RFC 2518, Section 12.9.1
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:cannot-merge-checked-out-resource): The DAV:source element
MUST NOT identify a checked-out resource. If the DAV:source
element identifies a collection, the collection MUST NOT have a
member that is a checked-out resource.
The checkouts performed to resolve conflicts MUST NOT violate any
of the pre-conditions of the CHECKOUT operation.
(DAV:checkout-not-allowed): If DAV:no-checkout is specified in the
request body, it MUST be possible to perform the merge without
checking out any of the merge targets.
Postconditions:
(DAV:ancestor-version): If the merge target is a version-controlled
resource whose DAV:checked-in version or DAV:checked-out version is
a descendant of the merge version, the merge target MUST NOT have
been modified by the MERGE.
(DAV:descendant-version): If the merge target was a checked-in
version-controlled resource whose DAV:checked-in version was an
ancestor of the merge version, an UPDATE request MUST have been
applied to the merge target to set its content and dead properties
to be those of the merge version, and the merge target MUST appear
in the DAV:updated-set XML element in the response body. If the
UPDATE method is not supported, the merge target MUST have been
checked out, the content and dead properties of the merge target
MUST have been set to those of the merge version, the merge version
MUST have been added to the DAV:auto-merge-set of the merge target,
and the merge target MUST appear in the DAV:merged-set.
(DAV:checked-out-for-merge): If the merge target was a checked-in
version-controlled resource whose DAV:checked-in version was
neither a descendant nor an ancestor of the merge version, a
Clemm, et al. [Page 45]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
CHECKOUT MUST have been applied to the merge target. All XML
elements in the DAV:merge XML element that could appear in a
DAV:checkin XML element MUST have been used as arguments to the
CHECKOUT request.
(DAV:update-merge-set): If the merge target was checked out by the
MERGE (or was already checked out before the MERGE), and if
DAV:checked-out version of the merge target is not a descendant of
the merge version, the merge version MUST be added to either the
DAV:merge-set or the DAV:auto-merge-set of the merge target, and
the merge target MUST appear in the DAV:merged-set element in the
response body. If a merge version has been added to the DAV:auto-
merge-set, the content and dead properties of the merge target MUST
have been modified by the server to reflect the result of a logical
merge of the merge version and the merge target. If a merge
version has been added to the DAV:merge-set, the content and dead
properties of the merge target MUST NOT have been modified by the
server. If DAV:no-auto-merge is specified in the request body, the
merge version MUST NOT have been added to the DAV:auto-merge-set.
If a merge version has no merge target, a URL for the merge version
MUST appear in the DAV:ignored-set.
If DAV:prop is specified in the request body, the properties
specified in the DAV:prop element MUST be reported in the
DAV:response elements in the DAV:updated-set and DAV:merged-set.
8.2.1Example - MERGE
>>REQUEST
MERGE /ws/public HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge xmlns:D="DAV:">
<D:source>
<D:href>http://www.webdav.org/ws/dev/sally</D:href>
</D:source>
</D:merge>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Cache-Control: no-cache
<?xml version="1.0" encoding="utf-8" ?>
<D:merge-response xmlns:D="DAV:">
<D:update-set>
Clemm, et al. [Page 46]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<D:href>
http://www.webdav.org/ws/public/src/parse.c
</D:href>
<D:href>
http://www.webdav.org/ws/public/doc/parse.html
</D:href>
</D:update-set>
<D:ignore-set>
<D:href>http://repo.webdav.org/his/23/ver/42</D:href>
</D:ignore-set>
</D:merge-response>
In this example, the DAV:checked-in versions from the workspace
http://www.webdav.org/ws/dev/sally are merged into the version-
controlled resources in the workspace
http://www.webdav.org/ws/public. Two resources in the workspace
were updated, and one version was ignored.
8.3 DAV:merge-preview REPORT
A merge preview describes the changes that would result if the
versions specified by the DAV:source element in the request body
were merged into the resource identified by the request-URL
(commonly, a collection).
Marshalling:
The DAV:merge-preview REPORT request body MUST be a DAV:merge-
preview-request XML element.
<!ELEMENT merge-preview-request (source)>
<!ELEMENT source (href)>
The DAV:merge-preview REPORT response body MUST be a DAV:merge-
preview XML element.
<!ELEMENT merge-preview (update-preview-set, merge-preview-set,
ignore-preview-set)>
<!ELEMENT update-preview-set (update-preview*)>
<!ELEMENT update-preview (target, version)>
<!ELEMENT merge-preview-set (conflict*)>
<!ELEMENT conflict (target, common-ancestor, version)>
<!ELEMENT target (href)>
<!ELEMENT version (href)>
<!ELEMENT common-ancestor (href)>
<!ELEMENT ignored-preview-set (href*)>
Clemm, et al. [Page 47]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Postconditions:
The DAV:conflict element identifies a merge target that requires a
merge.
The DAV:common-ancestor element identifies the version that is a
common ancestor of both the merge version and the DAV:checked-in or
DAV:checked-out version of the merge target.
The DAV:update-preview element identifies a merge target whose
DAV:checked-in property would change as a result of the MERGE, and
identifies the merge version for that merge target.
The DAV:ignored-preview-set element contains a URL for each version
that has no merge target and therefore would be ignored by the
merge.
8.3.1Example - DAV:merge-preview-report
>>REQUEST
REPORT /ws/public HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge-preview-request xmlns:D="DAV:">
<D:source>
<D:href>http://www.webdav.org/ws/dev/fred</D:href>
</D:source>
</D:merge-preview-request>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge-preview xmlns:D="DAV:">
<D:update-preview-set>
<D:conflict>
<D:target>
<D:href>http://www.webdav.org/ws/public/foo.html</D:href>
</D:target>
<D:common-ancestor>
<D:href>http://repo.webdav.org/his/23/ver/18</D:href>
</D:common-ancestor>
<D:version>
<D:href>http://repo.webdav.org/his/23/ver/42</D:href>
</D:version>
</D:conflict>
Clemm, et al. [Page 48]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<D:update-preview>
<D:target>
<D:href>http://www.webdav.org/ws/public/bar.html</D:href>
</D:target>
<D:version>
<D:href>http://www.repo/his/42/ver/3</D:href>
</D:version>
</D:update-preview>
</D:update-preview-set>
</D:merge-preview>
In this example, the merge preview report indicates that version
/his/23/ver/42 would be merged in /ws/public/foo.html, and version
/his/42/ver/3 would update /ws/public/bar.html if the workspace
http://www.webdav.org/ws/dev/fred was merged into the workspace
http://www.webdav.org/ws/public.
8.4 Additional OPTIONS Semantics
If the server supports the merge option, it MUST include "merge" as
a field in the DAV response header from an OPTIONS request on any
resource that supports any versioning properties, reports, or
methods.
8.5 Additional DELETE Semantics
Additional Postconditions:
(DAV:delete-version-reference): If a version is deleted, any
reference to that version in a DAV:merge-set or DAV:auto-merge-set
property MUST be removed.
8.6 Additional CHECKIN Semantics
Additional Preconditions:
(DAV:merge-must-be-complete): The DAV:merge-set and DAV:auto-
merge-set of the checked-out resource MUST be empty.
9 LABEL OPTION
A version "label" is a string that distinguishes one version of a
version history from all other versions of that version history. A
label can automatically be assigned by a server, or it can be
assigned by a client in order to provide a meaningful name for that
version. A given version label can be assigned to at most one
version of a given version history, but client assigned labels can
be reassigned to another version at any time. Note that although a
given label can be applied to at most one version from the same
Clemm, et al. [Page 49]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
version history, the same label can be applied to versions from
different version histories.
For certain methods, if the request-URL identifies a version-
controlled resource, a label can be specified in a Label request
header to cause the method to be applied to the version selected by
that label from the version history of that version-controlled
resource.
Note that it is hard for a distributed versioning server to support
labels. Two temporarily disconnected servers that have copies of a
version history can assign the same label to different versions of
that version history, resulting in two versions in that version
history with the same label when the two servers are synchronized.
9.1 Additional Version Properties
The label option introduces the following properties for a version.
9.1.1DAV:label-name-set (protected)
This property contains the labels that currently select this
version.
<!ELEMENT label-name-set (label-name*)>
<!ELEMENT label-name (#PCDATA)>
PCDATA value: string
9.2 LABEL Method
A LABEL request can be applied to a version to modify the labels
that select that version. The case of a label name MUST be
preserved when it is stored and retrieved. When comparing two
label names to decide if they match or not, a server SHOULD use a
case-sensitive octet-by-octet comparison of the two label names.
If a LABEL request is applied to a version-controlled resource, the
operation MUST be applied to the DAV:checked-in version of that
version-controlled resource.
Marshalling:
The request body MUST be a DAV:label element.
<!ELEMENT label ANY>
ANY value: A sequence of elements with at most one DAV:add,
DAV:set, or DAV:remove element.
<!ELEMENT add (label-name)>
<!ELEMENT set (label-name)>
<!ELEMENT remove (label-name)>
<!ELEMENT label-name (#PCDATA)>
Clemm, et al. [Page 50]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
PCDATA value: string
The request MAY include a Label header.
The request MAY include a Depth header. Standard depth semantics
apply, and the request is applied to the collection identified by
the request-URL and to all members of the collection that satisfy
the Depth value. If a Depth header is included and the request
fails on any resource, the response MUST be a 207 Multi-Status that
identifies all resources for which the request has failed.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:must-not-be-checked-out): If the request-URL identifies a
version-controlled resource, the version-controlled resource MUST
NOT be checked out.
(DAV:must-select-version): If a Label request header is included
and the request-URL identifies a version-controlled resource, the
specified label MUST select a version in the version history of the
version-controlled resource.
(DAV:must-be-new-label): If DAV:add is specified, the specified
label MUST NOT currently select a version of the version history of
that version-controlled resource.
(DAV:label-must-exist): If DAV:remove is specified, the specified
label MUST select that version.
Postconditions:
(DAV:add-label): If DAV:add or DAV:set is specified, the specified
label selects the version.
(DAV:remove-label): If DAV:remove is specified, the specified label
no longer selects any version of the version history of the
version-controlled resource.
9.2.1Example - Setting a label
>>REQUEST
LABEL /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:label xmlns:D="DAV:"> <D:set>
<D:label-name>released</D:label-name>
</D:set> </D:label>
Clemm, et al. [Page 51]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, the label "released" is applied to the
DAV:checked-in version of /foo.html.
9.3 Label Header
For certain methods (e.g. GET, PROPFIND), if the request-URL
identifies a version-controlled resource, a label can be specified
in a Label request header to cause the method to be applied to the
version selected by that label from the version history of that
version-controlled resource.
The following defines the BNF for the Label header:
Label := "Label" ":" string
An example of a Label header is:
Label: released
A Label header MUST have no effect on a request whose request-URL
does not identify a version-controlled resource. In particular, it
MUST have no effect on a request whose request-URL identifies a
version or a version history.
A server MUST return an HTTP-1.1 Vary header containing Label in a
successful response to a cacheable request (e.g. GET, PROPFIND)
that includes a Label header.
9.4 Additional OPTIONS Semantics
If the server supports the label option, it MUST include "label" as
a field in the DAV response header from an OPTIONS request on any
resource that supports any versioning properties, reports, or
methods.
9.5 Additional GET Semantics
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version): If a Label request header is included
and the request-URL identifies a version-controlled resource, the
Clemm, et al. [Page 52]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
specified label MUST select a version in the version history of the
version-controlled resource.
Additional Postconditions:
If the request-URL identifies a version-controlled resource and a
Label request header is included, the response MUST contain the
content of the specified version rather than that of the version-
controlled resource.
9.6 Additional PROPFIND Semantics
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version): If a Label request header is included
and the request-URL identifies a version-controlled resource, the
specified label MUST select a version in the version history of the
version-controlled resource.
Additional Postconditions:
If the request-URL identifies a version-controlled resource and a
Label request header is included, the response MUST contain the
properties of the specified version rather than that of the
version-controlled resource.
9.7 Additional COPY Semantics
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version): If a Label request header is included
and the request-URL identifies a version-controlled resource, the
specified label MUST select a version in the version history of the
version-controlled resource.
Additional Postconditions:
If the request-URL identifies a version-controlled resource and a
Label request header is included, the request MUST have copied the
properties and content of the specified version rather than that of
the version-controlled resource.
Clemm, et al. [Page 53]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
9.8 Additional CHECKOUT Semantics
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version): If a Label request header is included
and the request-URL identifies a version-controlled resource, the
specified label MUST select a version in the version history of the
version-controlled resource.
Additional Postconditions:
If a version-controlled resource was checked out, and a Label
request header is included, the CHECKOUT MUST have been applied to
the version selected by the specified label, and not to the
version-controlled resource itself. A new working resource MUST
have been created and the version-controlled resource MUST remain
checked in.
9.9 Additional UPDATE Semantics
A label can be specified to update the content and dead properties
of the version-controlled resource to be those of the version
selected by the specified label from the version history of the
version-controlled resource identified.
Additional Marshalling:
<!ELEMENT update ANY>
ANY value: A sequence of elements with at most one DAV:label-name
element.
<!ELEMENT label-name (#PCDATA)>
PCDATA value: string
The request MAY include a Depth header.
Additional Preconditions:
(DAV:must-select-version): If the request includes a DAV:label
element in the request body, the label MUST select a version in the
version history of the version-controlled resource identified by
the request-URL.
(DAV:depth-update): If the request includes a Depth header,
standard depth semantics apply, and the request is applied to the
collection identified by the request-URL and to all members of the
collection that satisfy the Depth value. The request MUST be
applied to a collection before being applied to any members of that
collection, since an update of a version-controlled collection
might change the membership of that collection.
Clemm, et al. [Page 54]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Additional Postconditions:
If a Label request header is included, the content and dead
properties of the version-controlled resource are updated to be
those of the version selected by that label.
10 BASELINE OPTION
A collection that contains a large number of version-controlled
resources can consume a large amount of space on a server. This
can make it prohibitively expensive to remember the state of an
existing collection by creating a copy of that collection. A
"baseline" is a special kind of version resource that captures a
"deep version" of a collection. In particular, it captures the
DAV:checked-in version of each version-controlled resource that is
a member of that collection, as well as the DAV:checked-in version
of the collection if the collection itself is a version-controlled
resource. A "baseline history" is a special kind of version
history whose versions are baselines. New baselines are created by
checking out and then checking in a special kind of version-
controlled resource called a "baseline selector".
A collection that is under baseline control is called a "baseline-
controlled collection". In order to allow efficient baseline
implementation, the state of a baseline of a collection is limited
to be a set of versions and their names relative to the collection,
and the operations on a baseline are limited to the creation of a
baseline from a collection, and restoring or merging the baseline
back into a collection.
Clemm, et al. [Page 55]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
In the following diagram, /x/a.html, /x/y/b.html, and /x/y/c.html
are the version-controlled members of /x, and the baseline B1.1 of
/x selects versions V1, V3, and V5.
/x/a.html /x/y/b.html /x/y/c.html
History History History
+---+
| | V2
+---+
|
|
+------------------|-------------------------------+
| | |
| +---+ +---+ +---+ Baseline |
| | | V1 | | V3 | | V5 B1.1 |
| +---+ +---+ +---+ |
| | | |
+------------------|------------|------------------+
| |
| |
+---+ +---+
| | V4 | | V6
+---+ +---+
10.1Baseline Selector Properties
Since a baseline selector is a version-controlled resource, it has
all the properties of a version-controlled resource. In addition,
the baseline option introduces the following properties for a
baseline selector.
10.1.1 DAV:baseline-controlled-collection (protected)
This property contains the URL of the collection that contains the
version-controlled resources whose DAV:checked-in versions are
being tracked by this baseline selector. The DAV:baseline-selector
of the DAV:baseline-controlled-collection of a baseline selector
MUST identify that baseline selector.
<!ELEMENT baseline-controlled-collection (href)>
10.1.2 DAV:subbaseline-set
The URL's in the DAV:subbaseline-set property MUST identify a set
of other baselines. The set of versions specified in the
DAV:version-set of a baseline is logically extended by the versions
selected by these other baselines. This extended version set MUST
NOT contain more than one version from any version history. A
server that supports the baseline option MAY chose to not support
the DAV:subbaseline-set property.
Clemm, et al. [Page 56]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT subbaseline-set (href*)>
10.2Baseline Properties
The DAV:resourcetype of a baseline MUST be DAV:baseline. Since a
baseline is a version resource, it has all the properties of a
version resource. In addition, the baseline option introduces the
following properties for a baseline.
10.2.1 DAV:version-set (protected)
This property contains a URL for each version selected by the
baseline. At most one version from a given version history can be
selected by a baseline's DAV:version-set property.
<!ELEMENT version-set (href*)>
10.2.2 DAV:subbaseline-set (protected)
The URL's in the DAV:subbaseline-set property MUST identify a set
of other baseline. The set of versions specified in the
DAV:version-set of a baseline is logically extended by the versions
selected by these other baselines. This extended version set MUST
NOT contain more than one version from any version history. A
server that supports the baseline option MAY chose to not support
the DAV:subbaseline-set property.
<!ELEMENT subbaseline-set (href*)>
10.3Additional Collection Properties
The baseline option introduces the following properties for a
collection.
10.3.1 DAV:baseline-selector (protected)
This property indicates that the collection is under baseline
control. It contains the URL of a baseline selector that is used
to access baselines of this collection. A server MAY automatically
assign a DAV:baseline-selector property to a collection when it is
created, or a client can use the BASELINE-CONTROL method to request
that a baseline selector be created for a specified collection.
<!ELEMENT baseline-selector (href)>
10.4BASELINE-CONTROL Method
A collection can be placed under baseline control with a BASELINE-
CONTROL request. When a collection is placed under baseline
control, the DAV:baseline-selector property of the collection is
set to identify a new baseline selector. This baseline selector
Clemm, et al. [Page 57]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
can be checked out and then checked in to create a new baseline for
that collection.
If a baseline is specified in the BASELINE-CONTROL request body,
the DAV:checked-in version of the new baseline selector will be
that baseline. If no baseline is specified, a new baseline history
is created whose root baseline is empty (i.e. its DAV:version-set
is empty).
Marshalling:
If a request body is included, it MUST be a DAV:baseline-control
XML element.
<!ELEMENT baseline-control ANY>
ANY value: A sequence of elements with at most one DAV:baseline
element.
<!ELEMENT baseline (href)>
Preconditions:
(DAV:baseline-selector-must-be-empty): The DAV:baseline-selector
property of the collection identified by the request-URL MUST be
empty.
(DAV:must-be-baseline): The DAV:href of the DAV:baseline element
in the request body MUST identify a baseline.
(DAV:must-have-no-version-controlled-members): If a DAV:baseline
element is specified in the request body, the collection identified
by the request-URL MUST have no version-controlled members.
(DAV:one-baseline-controlled-collection-per-history-per-workspace):
If the request-URL identifies a workspace or a member of a
workspace, and if the DAV:baseline element in the request body
identifies a baseline history, then there MUST NOT be another
collection in that workspace whose DAV:baseline-selector property
identifies a baseline selector for that baseline history.
Postconditions:
(DAV:create-baseline-selector): A new baseline selector is created,
whose DAV:baseline-controlled-collection property contains the
request-URL.
(DAV:reference-baseline-selector): The DAV:baseline-selector of the
collection identifies the new baseline selector.
(DAV:select-existing-baseline): If the request body specifies a
baseline, the DAV:checked-in property of the new baseline selector
MUST have been set to identify this baseline. A version-controlled
member of the collection will be created for each version in the
baseline, where the version-controlled member will have the content
Clemm, et al. [Page 58]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
and dead properties of that version, and will have the same name
relative to the collection as the corresponding version-controlled
resource had when the baseline was created. Any nested collections
that are needed to provide the appropriate name for a version-
controlled member will be created.
(DAV:create-empty-baseline): If no baseline is specified in the
request body, a new baseline history with an empty root baseline is
created at a server-defined URL, and the DAV:checked-in property of
the new baseline selector identifies the root baseline of the new
baseline history.
10.4.1 Example - BASELINE-CONTROL
>>REQUEST
BASELINE-CONTROL /src HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:baseline-control xmlns:D="DAV:">
<D:href>http://repo.webdav.org/bl-his/22/bl/17</D:href>
</D:baseline-control>
>>RESPONSE
HTTP/1.1 200 OK
In this example, the collection identified by
http://www.webdav.org/src is placed under baseline control and is
initialized with version-controlled members whose DAV:checked-in
versions are those selected by the baseline identified by
http://repo.webdav.org/bl-his/22/bl/17.
10.5DAV:baseline-version REPORT
The DAV:baseline-version REPORT can be applied to a version history
to identify the version that is selected from that version history
by a given baseline.
Marshalling:
The DAV:baseline-version REPORT request body MUST be a
DAV:baseline-version-request XML element.
<!ELEMENT baseline-version-request (href)>
The DAV:baseline-version REPORT response body MUST be a
DAV:baseline-version-request XML element.
Clemm, et al. [Page 59]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT baseline-version (href)>
Preconditions:
(DAV:must-be-baseline): The DAV:href in the request body MUST
identify a baseline.
Postconditions:
(DAV:baseline-version-OK): The DAV:href of the response body MUST
identify the version of the given version history that is a member
of the DAV:version-set of the given baseline.
10.6DAV:baseline-comparison REPORT
A DAV:baseline-comparison REPORT contains the differences between
the baseline identified by the request-URL (the "request baseline")
and the baseline specified in the body of the request (the "compare
baseline").
Marshalling:
The DAV:baseline-comparison REPORT request body MUST be a
DAV:baseline-comparison-request XML element.
<!ELEMENT baseline-comparison-request (href)>
The DAV:baseline-comparison REPORT response body MUST be a
DAV:baseline-comparison XML element.
<!ELEMENT baseline-comparison
(added-version | deleted-version | changed-version)*>
<!ELEMENT added-version (href)>
<!ELEMENT deleted-version (href)>
<!ELEMENT changed-version (href, href)>
Preconditions:
(DAV:must-be-baseline): The DAV:href in the request body MUST
identify a baseline.
(DAV:baselines-from-same-history): A server MAY require that the
baselines being compared be from the same baseline history.
Postconditions:
A DAV:added-version element identifies a version that appears in
the DAV:version-set of the compare baseline, but no version in the
version history of that version appears in the DAV:version-set of
the request baseline.
A DAV:deleted-version element identifies a version that appears in
the DAV:version-set of the request baseline, but no version in the
Clemm, et al. [Page 60]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
version history of that version appears in the DAV:version-set of
the compare baseline.
A DAV:changed-version element identifies two versions from the same
version history that appear in the DAV:version-set of the request
baseline and the compare baseline, respectively.
10.6.1 Example - DAV:baseline-comparison REPORT
>>REQUEST
REPORT /bl-his/12/bl/14 HTTP/1.1
Host: repo.webdav.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:baseline-comparison-request xmlns:D="DAV:">
<D:href>http://repo.webdav.org/bl-his/12/bl/15</D:href>
</D:baseline-comparison-request>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:baseline-comparison xmlns:D="DAV:">
<D:added-version>
<D:href>http://repo.webdav.org/his/23/ver/8</D:href>
</D:added-version>
<D:changed-version>
<D:href>http://repo.webdav.org/his/29/ver/12</D:href>
<D:href>http://repo.webdav.org/his/29/ver/19</D:href>
</D:changed-version>
<D:deleted-version>
<D:href>http://repo.webdav.org/his/12/ver/4</D:href>
</D:deleted-version>
</D:baseline-comparison>
In this example, the differences between baseline 14 and baseline
15 of http://repo.webdav.org/bl-his/12 are identified.
10.7Additional OPTIONS Semantics
If a server supports the baseline option, it MUST include
"baseline" as a field in the DAV response header from an OPTIONS
request on any resource that supports any versioning properties,
reports, or methods.
Clemm, et al. [Page 61]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
The DAV:baseline-controlled-collection-set enumerates which
collections are under baseline control.
Additional Marshalling:
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one DAV:baseline-
controlled-collection-set element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one DAV:baseline-
controlled-collection-set element.
<!ELEMENT baseline-controlled-collection-set (href*)>
Additional Postconditions:
(DAV:baseline-controlled-collection-set-OK): If DAV:baseline-
controlled-collection-set is included in the request body, the
response body MUST contain a DAV:baseline-controlled-collection-set
element identifying which collections are under baseline control.
10.8Additional MKCOL Semantics
Additional Postconditions:
If a server automatically puts a newly created collection under
baseline control, all postconditions for BASELINE-CONTROL apply to
the MKCOL.
10.9Additional COPY Semantics
Additional Postconditions:
If a server automatically puts a newly created collection under
baseline control, all postconditions for BASELINE-CONTROL apply to
the COPY.
10.10 Additional CHECKIN Semantics
Additional Preconditions:
(DAV:no-checked-out-baseline-controlled-collection-members): If
the request-URL identifies a baseline selector, all version-
controlled members of the DAV:baseline-controlled-collection of the
baseline selector MUST be checked-in.
Additional Postconditions:
(DAV:create-baseline-version-set): If the request-URL identifies a
baseline selector, the DAV:version-set of the new baseline contains
Clemm, et al. [Page 62]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
the DAV:checked-in version of each version-controlled member of the
DAV:baseline-controlled-collection of the baseline selector, as
well as the current DAV:checked-in version of this collection if it
is a version-controlled collection.
(DAV:auto-baseline): If the request updated the DAV:checked-in
property of any version-controlled member of a baseline-controlled
collection, and if DAV:auto-version is set for the baseline
selector of that baseline-controlled collection, then the baseline
selector is automatically checked out and checked in to create a
new baseline.
10.11 Additional UPDATE Semantics
Additional Preconditions:
(DAV:baseline-controlled-members-must-be-checked-in): If the
request-URL identifies a baseline selector, then all version-
controlled members of the DAV:baseline-controlled-collection of
that baseline selector MUST be checked-in.
Additional Postconditions:
(DAV:set-baseline-controlled-collection-members): If the request-
URL identifies a baseline selector and the DAV:version element
identifies a baseline, then the version-controlled members of the
DAV:baseline-controlled-collection of that baseline selector MUST
have been updated so that they have the same relative name,
content, and dead properties as when that baseline was created. In
particular:
- A version-controlled member MUST have been deleted if no version
from its version history is in the DAV:version-set of the baseline.
- A version-controlled member MUST have been renamed if its name
relative to the baseline-controlled collection is different from
the relative name of the corresponding version-controlled member
when the baseline was created.
- A new version-controlled member MUST have been created for each
version in the DAV:version-set of the baseline for which there is
no corresponding version-controlled member in the baseline-
controlled collection.
- An UPDATE request MUST have been applied to each version-
controlled member whose DAV:checkin-set does not identify a version
in the DAV:version-set of the baseline.
(DAV:auto-baseline): If the request modified the DAV:checked-in
property of any version-controlled member of a baseline-controlled
collection, and if DAV:auto-version is set for the baseline
selector of that baseline-controlled collection, then that baseline
selector MUST have been automatically checked out and checked in to
create a new baseline.
Clemm, et al. [Page 63]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
10.12 Additional MERGE Semantics
If the merge version is a baseline, the merge target is a baseline
selector for the baseline history of that baseline, where the
baseline-controlled collection of that baseline selector is a
member of the merge destination of the request.
Additional Postconditions:
(DAV:merge-baseline): If the merge target is a baseline selector
whose DAV:checked-out baseline is not a descendant of the merge
baseline, then the merge baseline MUST have been added to the
DAV:auto-merge-set of a baseline selector. Each baseline in the
DAV:subbaseline-set of that baseline MUST have been merged into the
merge destination, and each version in the DAV:version-set of that
baseline MUST have been merged into the DAV:baseline-controlled-
collection of that baseline selector.
(DAV:auto-baseline): If the request updated the DAV:checked-in
property of any version-controlled member of a baseline-controlled
collection, and if DAV:auto-version is set for the baseline
selector of that baseline-controlled collection, then the baseline
selector MUST have been automatically checked out and checked in to
create a new baseline.
11 ACTIVITY OPTION
An "activity" is a non-versionable resource that selects a set of
versions that are on a single "line of descent", where a line of
descent is a sequence of versions connected by successor
relationships. If an activity selects versions from multiple
version histories, the versions selected in each version history
must be on a single line of descent.
A common problem that motivates the use of activities is that it is
often desirable to perform several different logical changes in a
single workspace, and then selectively merge a subset of those
logical changes to other workspaces. An activity can be used to
represent a single logical change, where an activity tracks all the
resources that were modified to effect that single logical change.
When a version-controlled resource is checked out, the author
specifies which activity should be associated with a new version
that will be created when that version-controlled resource is
checked in. It is then possible to select a particular logical
change for merging into another workspace, by specifying the
appropriate activity in a MERGE request.
Another common problem is that although a version-controlled
resource may need to have multiple lines of descent, all work done
by members of a given team must be on a single line of descent (to
avoid merging between team members). An activity resource provides
the mechanism for addressing this problem. When a version-
controlled resource is checked out, a client can request that an
Clemm, et al. [Page 64]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
existing activity be used or that a new activity be created.
Activity semantics then ensures that all versions in a given
version history that are associated with an activity are on a
single line of descent. If all members of a team share a common
activity (or sub-activities of a common activity), then all changes
made by members of that team will be on a single line of descent.
The following diagram illustrates activities. Version V5 is the
latest version of foo.html selected by activity Act-2, and version
V8 is the latest version of bar.html selected by activity Act-2.
foo.html History bar.html History
+---+ +---+
Act-1| |V1 Act-1| |V6
+---+ +---+
| |
| |
+---+ +---+
Act-1| |V2 Act-2| |V7
+---+ +---+
/ \ |
/ \ |
+---+ +---+ +---+
Act-1| | Act-2| |V4 Act-2| |V8
+---+ +---+ +---+
| |
| |
+---+ +---+
Act-2| |V5 Act-3| |V9
+---+ +---+
Activities appear under a variety of names in existing versioning
systems. When an activity is used to capture a logical change, it
is commonly called a "change set". When an activity is used to
capture a line of descent, it is commonly called a "branch".
11.1Activity Properties
The activity option introduces the following properties for an
activity.
11.1.1 DAV:version-set (protected)
This property contains a URL for each version whose DAV:activity-
set property contains this activity. Multiple versions of a single
version history can be selected by an activity's DAV:version-set
property, but all DAV:version-set versions from a given version
history must be on a single line of descent from the root version
of that version history.
Clemm, et al. [Page 65]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT version-set (href*)>
11.1.2 DAV:activity-checkout-set (protected)
This property contains a URL for each checked-out resource whose
DAV:activity-set contains this activity.
<!ELEMENT activity-checkout-set (href*)>
11.1.3 DAV:subactivity-set
This property contains a URL for each activity that forms a part of
the logical change being captured by this activity. An activity
behaves as if its DAV:version-set is extended by the DAV:version-
set of each activity specified in the DAV:subactivity-set. In
particular, the versions in this extended set MUST be on a single
line of descent, and when an activity selects a version for
merging, the latest version in this extended set is the one that
will be merged. A server that supports the activity option MAY
chose to not support the DAV:subactivity-set property.
<!ELEMENT subactivity-set (href*)>
11.1.4 DAV:current-workspace-set (protected)
This property contains a URL for each workspace whose DAV:current-
activity-set contains this activity.
<!ELEMENT current-workspace-set (href*)>
11.2Additional Version Properties
The activity option introduces the following properties for a
version.
11.2.1 DAV:activity-set
This property contains the URL's for the activities that indicate
to which logical changes this activity contributes, and on what
lines of descent this version appears. A server MAY restrict the
DAV:activity-set to contain a single activity.
<!ELEMENT activity-set (href*)>
11.3Additional Version-Controlled Resource Properties
The activity option introduces the following properties for a
version-controlled resource.
Clemm, et al. [Page 66]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
11.3.1 DAV:unreserved
This property of a checked-out resource indicates whether the
DAV:activity-set of another checked-out resource associated with
the version history of this version-controlled resource can have an
activity that is in the DAV:activity-set property of this checked-
out resource.
A result of the requirement that an activity must form a single
line of descent through a given version history is that if multiple
checked-out resources for a given version history are checked out
unreserved into a single activity, only the first CHECKIN will
succeed. Before the other checked-out resources can be checked in,
the author will have to merge the latest version of that activity
into the checked-out resource and then modify the DAV:predecessor-
set of that checked-out resource to be that version.
<!ELEMENT unreserved (#PCDATA)>
PCDATA value: boolean
11.3.2 DAV:activity-set
This property of a checked-out resource determines the
DAV:activity-set property of the version that results from checking
in this resource.
11.4Additional Workspace Properties
The activity option introduces the following properties for a
workspace.
11.4.1 DAV:current-activity-set
This property identifies the activities that currently are being
performed in this workspace. When a member of this workspace is
checked out, if no activity is specified in the checkout request,
the DAV:current-activity-set will be used. This allows an
activity-unaware client to update a workspace in which activity
tracking is required. The DAV:current-activity-set MAY be
restricted to contain at most one activity.
<!ELEMENT current-activity-set (href*)>
11.5MKACTIVITY Method
A MKACTIVITY request creates a new activity resource. A server MAY
restrict activity creation to particular collections, but a client
can determine the location of these collections from a
DAV:activity-collection-set OPTIONS request.
Clemm, et al. [Page 67]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
Marshalling:
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:resource-must-be-null): A resource MUST NOT exist at the
request-URL.
(DAV:activity-location-ok): The request-URL MUST identify a
location where an activity can be created.
Postconditions:
(DAV:create-activity): A new activity exists at the request-URL.
(DAV:initialize-activity-properties): The DAV:resourcetype of the
activity MUST be DAV:activity. The DAV:version-set,
DAV:subactivity-set, and DAV:current-workspace-set of the activity
MUST be empty.
11.5.1 Example - MKACTIVITY
>>REQUEST
MKACTIVITY /act/test-23 HTTP/1.1
Host: repo.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, a new activity is created at
http://repo.webdav.org/act/test-23.
11.6DAV:latest-activity-version REPORT
The DAV:latest-activity-version REPORT can be applied to a version
history to identify the latest version that is selected from that
version history by a given activity.
Marshalling:
The DAV:latest-activity-version REPORT request body MUST be a
DAV:latest-activity-version-request XML element.
<!ELEMENT latest-activity-version-request (href)>
The DAV:version-controlled-resource REPORT response body MUST be a
DAV:version-controlled-resource XML element.
Clemm, et al. [Page 68]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT latest-activity-version (href)>
Preconditions:
(DAV:must-be-activity): The DAV:href in the request body MUST
identify an activity.
Postconditions:
(DAV:latest-activity-version-OK): The DAV:href of the response body
MUST identify the version of the given version history that is a
member of the DAV:version-set of the given activity and has no
ancestor that is a member of the DAV:version-set of the given
activity.
11.7Additional OPTIONS Semantics
If the server supports the activity option, it MUST include
"activity" as a field in the DAV response header from an OPTIONS
request on any resource that supports any versioning properties,
reports, or methods.
Often a versioning implementation constrains where an activity can
be located in the URL space. The DAV:activity-collection-set
enumerates which collections may contain activities. An activity
collection MAY be the root collection of a tree of collections, all
of which may contain activities. Since different servers can
control different parts of the URL namespace, different resources
on the same host MAY have different DAV:activity-collection-set
values. The collections specified in the DAV:activity-collection-
set MAY be located on different hosts from the resource.
Additional Marshalling:
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one DAV:activity-
collection-set element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one DAV:activity-
collection-set element.
<!ELEMENT activity-collection-set (href*)>
Additional Postconditions:
(DAV:activity-collection-set-OK): If DAV:activity-collection-set is
included in the request body, the response body MUST contain a
DAV:activity-collection-set element identifying which collections
may contain activities.
Clemm, et al. [Page 69]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
11.8Additional DELETE Semantics
Additional Postconditions:
(DAV:delete-checked-out-reference): If a checked-out resource is
deleted, any reference to that version in a DAV:activity-checkout-
set property MUST be removed.
(DAV:delete-version-reference): If a version is deleted, any
reference to that version in a DAV:version-set property MUST be
removed.
(DAV:delete-activity-reference): If an activity is deleted, any
reference to that activity in a DAV:activity-set, DAV:subactivity-
set, or DAV:current-activity-set MUST be removed.
(DAV:delete-workspace-reference): If a workspace is deleted, any
reference to that workspace in a DAV:current-workspace-set MUST be
removed.
11.9Additional MOVE Semantics
Additional Postconditions:
(DAV:update-checked-out-reference): If a checked-out resource is
moved, any reference to that resource in a DAV:activity-checkout
property MUST be updated to refer to the new location of that
resource.
(DAV:update-activity-reference): If the request-URL identifies an
activity, any reference to that activity in a DAV:activity-set,
DAV:subactivity-set , or DAV:current-activity-set MUST be updated
to refer to the new location of that activity.
(DAV:update-workspace-reference): If the request-URL identifies a
workspace, any reference to that workspace in a DAV:current-
workspace-set property MUST be updated to refer to the new location
of that workspace.
11.10 Additional CHECKOUT Semantics
A CHECKOUT request MAY specify the DAV:activity-set for the
checked-out resource..
Additional Marshalling:
<!ELEMENT checkout ANY>
ANY value: A sequence of elements with at most one DAV:activity-set
and at most one DAV:unreserved.
<!ELEMENT activity-set (href+ | new)>
<!ELEMENT new EMPTY>
Clemm, et al. [Page 70]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT unreserved EMPTY>
Additional Preconditions:
(DAV:one-checkout-per-activity-per-history): If there is a request
activity set, unless DAV:unreserved is specified, another checkout
from a version of that version history MUST NOT select an activity
in that activity set.
(DAV:linear-activity): If there is a request activity set, unless
DAV:unreserved is specified, the selected version MUST be a
descendant of all other versions of that version history that
select that activity.
Additional Postconditions:
(DAV:initialize-activity-set): The DAV:activity-set of the checked-
out resource is set as follows: if DAV:new is specified as the
DAV:activity-set in the request body, then a new activity created
by the server is used; otherwise, if activities are specified in
the request body, then those activities are used; otherwise, if the
version-controlled resource is a member of a workspace and the
DAV:current-activity-set of the workspace is set, then those
activities are used; otherwise, the DAV:activity-set of the
DAV:checked-out version is used.
(DAV:initialize-unreserved): If DAV:unreserved was specified in the
CHECKOUT request body, then the DAV:unreserved property of the
checked-out resource MUST be "true".
11.10.1 Example - CHECKOUT with an activity
>>REQUEST
CHECKOUT /ws/public/foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:checkout xmlns:D="DAV:">
<D:activity-set>
<D:href>http://repo.webdav.org/act/fix-bug-23</D:href>
</D:activity-set>
</D:checkout>
>>RESPONSE
HTTP/1.1 200 OK
In this example, the CHECKOUT is being performed in the
http://repo.webdav.org/act/fix-bug-23 activity.
Clemm, et al. [Page 71]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
11.11 Additional CHECKIN Semantics
Additional Preconditions:
(DAV:linear-activity): Any version which is in the version history
of the checked-out resource and whose DAV:activity-set contains an
activity from the DAV:activity-set of the checked-out resource MUST
be in the DAV:predecessor-set or an ancestor of a version in the
DAV:predecessor-set of the checked-out resource.
Additional Postconditions:
(DAV:initialize-activity-set): The DAV:activity-set of the new
version is the DAV:activity-set of the checked-out resource.
(DAV:update-version-set): For each activity in the DAV:activity-set
property of the new version, a URL for the new version is added to
the DAV:version-set property of that activity.
11.12 Additional MERGE Semantics
If the DAV:source element of the request body identifies an
activity, then all checked-out resources in that activity (or any
subactivity of that activity) are checked in, and then for each
version history containing a version selected by that activity, the
latest version selected by that activity is a merge version. Note
that the versions selected by an activity are the versions in its
DAV:version-set unioned with the versions selected by the
activities in its DAV:subactivity-set.
A checked-out baseline in the activity is checked-in only after all
other checked-out resources have been checked in and merged to
their merge target. This ensures that modifications to members of
a collection are captured by any new baseline of that collection.
If a working baseline is checked in, the baseline-controlled
collection that determines the DAV:version-set of the new baseline
is the merge target of that working baseline.
Additional Preconditions:
(DAV:atomic-activity-checkin): If the DAV:source element identifies
an activity, the server MAY fail the request if any of the checked-
out resources in the DAV:activity-checkout-set of the activity
cannot be checked in.
Additional Postconditions:
(DAV:checkin-activity): If the DAV:source element identified an
activity, before determining the merge versions, the server MUST
have checked in each checked-out resource that was in the
DAV:activity-checkout-set. Before checking in a checked-out
baseline, the server MUST have already checked in and merged all
checked-out non-baseline resources. If a checked-out baseline was
Clemm, et al. [Page 72]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
a working baseline, the baseline-controlled collection that
determined the DAV:version-set for the new baseline MUST have been
the merge target for that new baseline.
12 VERSION-CONTROLLED-COLLECTION OPTION
As with a non-collection, when a collection is put under version
control, a version history resource is created to contain versions
for that version-controlled collection. In order to preserve
standard versioning semantics (a version of a collection should not
be modifiable), and in order to provide for significant
implementation optimizations (version history URL's can be used to
capture the state of the collection's bindings), a collection
version only captures bindings to version-controlled internal
members of that collection.
A key difference between a version-controlled collection and a
collection version is that while a version-controlled collection
contains bindings to other version-controlled resources, a
collection version does not contain bindings to other versions, but
rather contains bindings to version histories. If, instead, a
collection version contained bindings to other versions, creating a
new version of a resource would require creating a new version of
all the collections that contain that resource, which would cause
activities in a workspace to become entangled. For example,
suppose a "feature-12" activity created a new version of
/x/y/a.html. If a collection version contained bindings to
versions of its members, a new version of /x/y would have to be
created to contain the new version of /x/y/a.html, and a new
version of /x would have to be created to contain the new version
of /x/y. Now suppose a "bugfix-47" activity created a new version
of /x/z/b.html. Again, a new version of /x/z and a new version of
/x would have to be created to contain the new version of
/x/y/b.html. But now it is impossible to merge just "bugfix-47"
into another workspace without "feature-12", because the version of
/x that contains the desired version of /x/z/b.html also contains
version of /x/y/a.html created for "feature-12". If, instead, a
collection version contains bindings to version histories, changing
the version selected by a member of that collection would not
require a new version of the collection (the new version is still
in the same version history so no new collection version is
required), and therefore "feature-12" and "bugfix-47" would not
become entangled.
Clemm, et al. [Page 73]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
In the following example, there are three version histories, named
VH14, VH19, and VH24. The versions of VH14 are collections, and
version V2 of VH14 has two bindings, one named "a" to VH19, and the
other named "b" to VH24. The collection /x is a version-controlled
collection for VH14 whose DAV:checked-in version is V2. The
bindings of V2 have induced corresponding bindings in /x. In
particular, /x/a is a version-controlled resource for VH19 (whose
DAV:checked-in version currently is V4), and /x/b is a version-
controlled resource for VH24 (whose DAV:checked-in version
currently is V8).
VH19
+---------+
| +---+ |
| | |V4 |
| +---+ |
| | |
| | |
| +---+ |
| | |V5 |
VH14 | +---+ |
+---------+ | | |
| +---+ | | | |
a +---+ | | |V1 | | +---+ |
---->| |checked-in=V4 | +---+ | a | | |V6 |
/ +---+ | | ------>| +---+ |
/ | | / | +---------+
+---+ | +---+ |
/x | |checked-in=V2 | | |V2 |
+---+ | +---+ | VH24
\ | | \ | b +---------+
\ b +---+ | | ------>| +---+ |
---->| |checked-in=V8 | +---+ | | | |V7 |
+---+ | | |V3 | | +---+ |
| +---+ | | | |
+---------+ | | |
| +---+ |
| | |V8 |
| +---+ |
| | |
| | |
| +---+ |
| | |V9 |
| +---+ |
+---------+
For any method that modifies the bindings of a collection (e.g.
DELETE, MOVE, COPY), when that collection is under version control
and when the binding is to a version-controlled resource, the
method MUST fail unless the version-controlled collection has a
DAV:auto-version property. If the version-controlled collection
has a DAV:auto-version property, the version-controlled collection
is checked out, the update is applied to the checked-out version-
Clemm, et al. [Page 74]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
controlled collection, and the checked-out version-controlled
collection is checked in. This functionality allows a versioning
unaware client to add a version to the collection version history.
If any part of the checkout-update-checkin sequence fails, the
server state preceding the request MUST be restored. If the
version-controlled collection is write-locked, the automatic
checkin is deferred until the collection is unlocked.
12.1Non-Version-Controlled Members of Version-Controlled Collections
Although a collection version only captures bindings to version-
controlled members, a server MAY allow a version-controlled
collection to contain bindings to both version-controlled and non-
version-controlled resources. Since bindings to non-version-
controlled resources are not controlled, those bindings can be
changed without checking out the version-controlled collection.
This feature is essential for the support of lock null resources,
since a lock null resource is a temporary member of a collection
that should only exist for the duration of the lock, and should not
be captured in the version history of that collection.
An UPDATE or MERGE request can add a member to version-controlled
collection that has the same name as an existing non-version-
controlled member. In this case, the non-version-controlled member
takes precedence and is said to "eclipse" the new versioned-
controlled member. If the non-version-controlled member is removed
(e.g. by a DELETE or MOVE), the version-controlled member is
exposed.
12.2Working Collections
When a server supports the client-workspace option, a client can
check out a collection version to create a "working collection".
The working collection is initialized to contain the same version
history members as the collection version that was checked out.
The members of a working collection can be deleted or moved to
another working collection. Non-version-controlled resources can
be added to a working collection with methods such as PUT, COPY,
and MKCOL. When a working collection is checked in, a VERSION-
CONTROL request is automatically applied to every non-version-
controlled member of the working collection, and each non-version-
controlled member is replaced by its newly created version history.
12.3Additional OPTIONS Semantics
If the server supports the version-controlled-collection option, it
MUST include "version-controlled-collection" as a field in the DAV
response header from an OPTIONS request on any resource that
supports any versioning properties, reports, or methods.
Clemm, et al. [Page 75]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
12.4Additional PUT Semantics
Additional Preconditions:
(DAV:cannot-modify-parent-version): If the parent of the request-
URL identifies a collection version and the request-URL does not
identify a resource, the request MUST fail.
12.5Additional DELETE Semantics
Additional Preconditions:
(DAV:cannot-modify-checked-in-parent): If the request-URL
identifies a version-controlled resource, the DELETE MUST fail when
the collection containing the version-controlled resource is a
checked-in version-controlled collection, unless DAV:auto-version
is set for that version-controlled collection.
(DAV:cannot-modify-parent-version): If the parent of the request-
URL identifies a collection version, the request MUST fail.
12.6Additional MKCOL Semantics
Additional Preconditions:
(DAV:cannot-modify-parent-version): If the parent of the request-
URL identifies a collection version, the request MUST fail.
Additional Postconditions:
If a server automatically puts a newly created collection under
version control, all postconditions for VERSION-CONTROL apply to
the MKCOL.
12.7Additional MOVE Semantics
Additional Preconditions:
(DAV:cannot-modify-parent-version): If the parent of the source of
the request identifies a collection version, the request MUST fail.
(DAV:cannot-modify-destination-parent-version): If the parent of
the destination of the request identifies a collection version, the
request MUST fail.
(DAV:cannot-modify-checked-in-parent): If the source of the
request is a version-controlled resource, the request MUST fail
when the collection containing the source is a checked-in version-
controlled collection, unless DAV:auto-version is set for that
version-controlled collection.
Clemm, et al. [Page 76]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
(DAV:cannot-modify-destination-checked-in-parent): If the source of
the request is a version-controlled resource, the request MUST fail
when the collection containing the destination is a checked-in
version-controlled collection, unless DAV:auto-version is set for
that version-controlled collection.
12.8Additional VERSION-CONTROL Semantics
Additional Preconditions:
(DAV:cannot-modify-parent-version): If the parent of the request-
URL identifies a collection version, the request MUST fail.
(DAV:cannot-modify-checked-in-parent): If the parent of the
request-URL is a checked-in version-controlled collection, the
request MUST fail unless DAV:auto-version is set for that version-
controlled collection.
12.9Additional CHECKIN Semantics
Additional Preconditions:
(DAV:no-eclipsed-baseline-controlled-collection-members): In order
to checkin a baseline selector, a member of the DAV:baseline-
controlled-collection of the baseline selector MUST NOT be
eclipsed.
Additional Postconditions:
(DAV:initialize-collection-version-bindings): If the request-URL
identified a version-controlled collection, then the new collection
version MUST contain bindings to the version histories of the
version-controlled members of the version-controlled collection.
(DAV:version-control-working-collection-members): If the request-
URL identified a working collection, a VERSION-CONTROL request MUST
have been automatically applied to every non-version-controlled
member of the working collection, and each non-version-controlled
members MUST have been replaced by its newly created version
history. If a working collection member was a non-version-
controlled collection, every member of the non-version-controlled
collection MUST have been placed under version control before the
non-version-controlled collection was placed under version control.
12.10 Additional UPDATE and MERGE Semantics
Additional Postconditions:
(DAV:update-version-controlled-collection-members): If the request
modified the DAV:checked-in version of a version-controlled
Clemm, et al. [Page 77]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
collection, then the version-controlled members of that version-
controlled collection MUST have been updated. In particular:
- A version-controlled member MUST have been deleted if its version
history is not a member of the new DAV:checked-in version.
- A version-controlled member MUST have been renamed if its version
history has a different name in the new DAV:checked-in version.
- A new version-controlled member MUST have been created when a
version history is a member of the DAV:checked-in version but there
was no member of the version-controlled collection with that
version history.
If a new version-controlled member is in a workspace that already
has a version-controlled resource for that version history, then
the new version-controlled member MUST be just a binding (i.e.
another name for) that existing version-controlled resource.
Otherwise, the content and dead properties of the new version-
controlled member MUST have been initialized to be those of the
version specified for that version history by the request. If no
version is specified for that version history by the request, the
root version of that version history MUST have been used.
13 FORK-CONTROL OPTION
Some servers provide the ability for a client to control whether a
fork can be created from a given version. Note that fork-control
does not guarantee the absence of forking, because in a distributed
versioning system, a server does not always have access to all
other servers that allow successors to be created for a given
version. For example, if a version has no successors and is
available on two temporarily disconnected servers, even if that
version is marked as being non-forking, each server would allow it
to be given a single successor, and when the servers are
synchronized, the version will end up with two successors.
13.1Additional Version Properties
The fork-control option introduces the following properties for a
version.
13.1.1 DAV:checkout-fork
This property controls the behavior of CHECKOUT when a version
already is checked out or has a successor. If the DAV:checkout-
fork of a version is DAV:forbidden, a CHECKOUT request MUST fail if
it would result in that version appearing in the DAV:predecessor-
set or DAV:checked-out property of more than one version or
checked-out resource. If DAV:checkout-fork is DAV:discouraged,
such a CHECKOUT request MUST fail unless DAV:fork-ok is specified
in the CHECKOUT request body.
<!ELEMENT checkout-fork (ok|discouraged|forbidden)>
<!ELEMENT ok EMPTY>
Clemm, et al. [Page 78]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT discouraged EMPTY>
<!ELEMENT forbidden EMPTY>
13.1.2 DAV:checkin-fork
This property controls the behavior of CHECKIN when a version
already has a successor. If the DAV:checkin-fork of a version is
DAV:forbidden, a CHECKIN request MUST fail if it would result in
that version appearing in the DAV:predecessor-set of more than one
version. If DAV:checkin-fork is DAV:discouraged, such a CHECKIN
request MUST fail unless DAV:fork-ok is specified in the CHECKIN
request body.
<!ELEMENT checkin-fork (ok|discouraged|forbidden)>
<!ELEMENT ok EMPTY>
<!ELEMENT discouraged EMPTY>
<!ELEMENT forbidden EMPTY>
13.2Additional Version-Controlled Resource Properties
The fork-control option introduces the following properties for a
version-controlled resource.
13.2.1 DAV:checkout-fork
This property of a checked-out version-controlled resource
determines the DAV:checkout-fork property of the version that
results from checking in this version-controlled resource.
13.2.2 DAV:checkin-fork
This property of a checked-out version-controlled resource
determines the DAV:checkin-fork property of the version that
results from checking in this version-controlled resource.
13.3Additional OPTIONS Semantics
If the server supports the fork-control option, it MUST include
"fork-control" as a field in the DAV response header from an
OPTIONS request on any resource that supports any versioning
properties, reports, or methods.
13.4Additional CHECKOUT Semantics
Additional Marshalling:
<!ELEMENT checkout ANY>
ANY value: A sequence of elements with at most one DAV:fork-ok
element.
Clemm, et al. [Page 79]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
<!ELEMENT fork-ok EMPTY>
Additional Preconditions:
(DAV:checkout-of-version-with-descendant-is-forbidden): If the
DAV:checkout-fork property of the version being checked out is
DAV:forbidden, the request MUST fail if a version contains that
version in its DAV:predecessor-set.
(DAV:checkout-of-version-with-descendant-is-discouraged): If the
DAV:checkout-fork property of the version being checked out is
DAV:discouraged, the request MUST fail if a version contains that
version in its DAV:predecessor-set unless DAV:fork-ok is specified
in the request.
(DAV:checkout-of-checked-out-version-is-forbidden): If the
DAV:checkout-fork property of the version being checked out is
DAV:forbidden, the request MUST fail if a checked-out resource
contains that version in its DAV:checked-out property.
(DAV:checkout-of-checked-out-version-is-discouraged): If the
DAV:checkout-fork property of the version being checked out is
DAV:discouraged, the request MUST fail if a checked-out resource
contains that version in its DAV:checked-out property unless
DAV:fork-ok is specified in the request.
13.5Additional CHECKIN Semantics
Additional Marshalling:
<!ELEMENT checkin ANY>
ANY value: A sequence of elements with at most one DAV:fork-ok
element.
<!ELEMENT fork-ok EMPTY>
Additional Preconditions:
(DAV:checkin-fork-forbidden): A CHECKIN request MUST fail if it
would cause a version whose DAV:checkin-fork is DAV:forbidden to
appear in the DAV:predecessor-set of more than one version.
(DAV:checkin-fork-discouraged): A CHECKIN request MUST fail if it
would cause a version whose DAV:checkin-fork is DAV:discouraged to
appear in the DAV:predecessor-set of more than one version, unless
DAV:fork-ok is specified in the CHECKIN request body.
14 VARIANT OPTION
The variant option provides a mechanism for a server to expose a
subset of the versions from the history of a version-controlled
resource as a set of special version-controlled resources called
Clemm, et al. [Page 80]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
"variants" of that version-controlled resource. When variants of a
version-controlled resource are being maintained, that version-
controlled resource is called a "variant-controlled resource".
Variants of a resource might be distinguished by language, format,
or any other category of interest to a client.
Like any other version-controlled resource, a variant can be
checked out in order to modify its content or dead properties.
When a variant of a variant-controlled resource is checked in, a
new version is added to the version history of the variant-
controlled resource. When the variant-controlled resource itself
is checked out and checked in, both a new version and a new variant
is created. The new variant becomes the "default variant" of that
variant-controlled resource.
Unlike the URL for a version, which uniquely identifies exactly
that version and is therefore inevitably quite obscure, the URL for
a variant is intended to be meaningful to a user, but there is no
guarantee that a URL for a variant will continue to identify that
variant. In particular, the URL for a variant of a version-
controlled resource will usually change whenever that version-
controlled resource is moved.
14.1Variant-Controlled Resource Properties
Since a variant-controlled resource is a version-controlled
resource, it has all the properties of a version-controlled
resource. In addition, the variant option introduces the following
properties for a variant-controlled resource.
14.1.1 DAV:variant-set (protected)
This property contains a URL for each variant of the variant-
controlled resource.
<!ELEMENT variant-set (href*)>
14.1.2 DAV:default-variant (protected)
This property contains a URL for the default variant of the
variant-controlled resource. Whenever the DAV:checked-in value of
the default variant is updated, the content, dead properties, and
DAV:checked-in property of the variant-controlled resource are
updated to be those of the default variant.
<!ELEMENT default-variant (href)>
14.2Additional DELETE Semantics
Additional Preconditions:
Clemm, et al. [Page 81]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
(DAV:delete-variant-reference): The request-URL MUST NOT identify a
variant identified by the DAV:default-variant of a variant-
controlled resource.
Additional Postconditions:
(DAV:delete-variant-reference): If the request-URL identifies a
variant, any reference to that variant in a DAV:variant-set MUST be
removed.
14.3Additional MOVE Semantics
Additional Preconditions:
(DAV:cannot-rename-variant): If the request-URL identifies a
variant, the request MUST fail.
14.4Additional VERSION-CONTROL Semantics
A VERSION-CONTROL request may specify that variants MUST be
maintained for the version-controlled resource.
Additional Marshalling:
<!ELEMENT version-control ANY>
ANY value: A sequence of elements with at most one DAV:variant-
control element.
<!ELEMENT variant-control EMPTY>
Additional Postconditions:
(DAV:variant-control): The DAV:default-variant property of the
version-controlled resource MUST identify a new variant resource
whose DAV:checked-in property identifies the new version. The
DAV:variant-set of the version-controlled resource MUST contain
this new variant.
14.5Additional CHECKIN Semantics
Additional Postconditions:
(DAV:create-new-variant): If the request-URL identifies a variant-
controlled resource, the DAV:default-variant of the variant-
controlled resource MUST have been updated to identify a new
variant whose DAV:checked-in property identifies the new version,
and the DAV:variant-set of the variant-controlled resource MUST
have been updated to contain this new variant.
(DAV:update-variant-controlled-resource): If the request-URL
identifies the default variant of a variant-controlled resource,
Clemm, et al. [Page 82]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
then the DAV:checked-in property of the variant-controlled resource
MUST have been updated to identify the new version. If the
variant-controlled resource is checked in, then the content and
dead properties of the variant-controlled resource MUST have been
updated to be those of the new version.
(DAV:delete-variant-predecessor): If the DAV:checked-in property of
a variant is modified, the version previously identified by the
DAV:checked-in property MAY have been automatically deleted by the
server.
14.6Additional UPDATE Semantics
Additional Marshalling:
<!ELEMENT update ANY>
ANY value: A sequence of elements with at most one DAV:variant
element.
<!ELEMENT variant (href)>
Preconditions:
(DAV:must-select-variant): If the request-URL identifies a variant-
controlled resource, the request body MUST contain a DAV:variant
element that identifies a variant in the DAV:variant-set of the
variant-controlled resource.
Additional Postconditions:
(DAV:update-default-variant): If the request-URL identifies a
variant-controlled resource, the DAV:default-variant property of
the variant-controlled resource MUST have been updated to identify
the variant identified by the DAV:variant element in the request
body. The content, dead properties, and DAV:checked-in property of
the variant-controlled resource MUST have been updated to be those
of that variant.
(DAV:update-variant-controlled-resource): If the request-URL
identifies the default variant of a variant-controlled resource,
then the DAV:checked-in property of the variant-controlled resource
MUST have been updated to identify the new version. If the
variant-controlled resource is checked in, then the content and
dead properties of the version-controlled resource MUST have been
updated to be those of the new version.
15 INTERNATIONALIZATION CONSIDERATIONS
This specification has been designed to be compliant with the IETF
Policy on Character Sets and Languages [RFC2277]. Specifically,
where human-readable strings exist in the protocol, either their
charset is explicitly stated, or XML [REC-XML] mechanisms are used
to specify the charset used. Additionally, these human-readable
Clemm, et al. [Page 83]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
strings all have the ability to express the natural language of the
string.
Most of the human-readable strings in this protocol appear in
properties, such as DAV:creator-displayname. As defined by the
WebDAV Distributed Authoring Protocol [RFC2518], properties have
their values marshaled as XML. XML has explicit provisions for
character set tagging and encoding, and requires that XML
processors read XML elements encoded, at minimum, using the UTF-8
[RFC2279] encoding of the ISO 10646 multilingual plane. The
charset parameter of the Content-Type header, together with the XML
"encoding" attribute, provide charset identification information
for MIME and XML processors. Proper use of the charset header with
XML is described in RFC 2376. XML also provides a language tagging
capability for specifying the language of the contents of a
particular XML element. XML uses either IANA registered language
tags (see RFC 1766) or ISO 639 language tags in the "xml:lang"
attribute of an XML element to identify the language of its content
and attributes.
DeltaV applications, since they build upon WebDAV, are subject to
the internationalization requirements specified in RFC 2518,
Section 16. In brief, these requirements mandate the use of XML
character set tagging, character set encoding, and language tagging
capabilities. Additionally, they strongly recommend reading RFC
2376 for instruction on the use of MIME media types for XML
transport and the use of the charset header.
Within this specification, a label is a human-readable string that
is marshaled in the Label header and as XML in request entity
bodies. When used in the Label header, the value of the label is
encoded using UTF-8.
16 SECURITY CONSIDERATIONS
Security considerations from RFC 2518 are also applicable to WebDAV
Versioning.
17 AUTHENTICATION
Authentication mechanisms defined in WebDAV will also apply to
WebDAV Versioning.
18 IANA CONSIDERATIONS
This document uses the namespace defined by RFC 2518 for XML
elements. All other IANA considerations from RFC 2518 are also
applicable to WebDAV Versioning.
Clemm, et al. [Page 84]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
19 INTELLECTUAL PROPERTY
The following notice is copied from RFC 2026, Section 10.4, and
describes the position of the IETF concerning intellectual property
claims made against this document.
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use other technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on
the procedures of the IETF with respect to rights in standards-
track and standards-related documentation can be found in BCP-11.
Copies of claims of rights made available for publication and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use
of such proprietary rights by implementers or users of this
specification can be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to practice
this standard. Please address the information to the IETF
Executive Director.
20 ACKNOWLEDGEMENTS
This protocol is the collaborative product of the DeltaV design
team: Jim Amsden (IBM, DeltaV Chair), Boris Bokowski (OTI),
Geoffrey Clemm (Rational), Bruce Cragun (Novell), Jim Doubek
(Macromedia), David Durand (INSO), Lisa Dusseault (Xythos), Tim
Ellison (OTI), Henry Harbury (Merant), James Hunt, Chris Kaler
(Microsoft), Jeff McAffer (OTI), Bradley Sergeant, Greg Stein, and
Jim Whitehead (UC Irvine). We would like to acknowledge the
foundation laid for us by the authors of the WebDAV and HTTP
protocols upon which this protocol is layered, and the invaluable
feedback from the WebDAV and DeltaV working groups.
21 REFERENCES
[ISO-639] ISO, "Code for the representation of names of languages",
ISO 639:1988, 1998.
[RFC1766] H.T.Alvestrand, "Tags for the Identification of
Languages", Uninett, 1995.
[RFC2026] S.Bradner, "The Internet Standards Process", Harvard,
1996.
Clemm, et al. [Page 85]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
[RFC2119] S.Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", Harvard, 1997.
[RFC2277] H.T.Alvestrand, "IETF Policy on Character Sets and
Languages", BCP 18, Uninett, 1998.
[RFC2279] F.Yergeau, "UTF-9, a transformation format of Unicode and
ISO 10646", Alis Technologies, 1998.
[RFC2376] E.Whitehead, M.Murata, "XML Media Types", U.C.Irvine,
Fuji-Xerox, 1998.
[RFC2396] T.Berners-Lee, R.Fielding, L.Masinter, "Uniform Resource
Identifiers (URI): Generic Syntax", MIT, U.C.Irvine, Xerox, 1998.
[RFC2518] Y.Goland, E.Whitehead, A.Faizi, S.R.Carter, D.Jensen,
"HTTP Extensions for Distributed Authoring - WEBDAV", Microsoft,
U.C.Irvine, Netscape, Novell, 1999.
[RFC2616] R.Fielding, J.Gettys, J.C.Mogul, H.Frystyk, L.Masinter,
P.Leach, and T.Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", U.C.Irvine, Compaq, Xerox, Microsoft, MIT/LCS, 1999.
22 AUTHORS' ADDRESSES
Geoffrey Clemm
Rational Software
20 Maguire Road, Lexington, MA 02421
Email: geoffrey.clemm@rational.com
Jim Amsden
IBM
3039 Cornwallis, Research Triangle Park, NC 27709
Email: jamsden@us.ibm.com
Christopher Kaler
Microsoft
One Microsoft Way, Redmond, WA 90852
Email: ckaler@microsoft.com
Jim Whitehead
University of California, Irvine
Irvine, CA 92697
Email:ejw@ics.uci.edu
23 APPENDIX A: CLARIFICATIONS AND EXTENSIONS TO RFC 2518
In order for clients and servers to successfully interoperate
through the versioning protocol, the following clarifications and
extensions to RFC 2518 are required. These clarifications and
extensions are included in this document, so that the
implementation of versioning clients and servers is not delayed
until a new revision of RFC 2518 has been accepted.
Clemm, et al. [Page 86]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
23.1Additional Resource Properties
WebDAV versioning introduces the following properties for any
WebDAV resource.
23.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 (string*)>
<!ELEMENT string (#PCDATA)>
23.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 (name*)>
<!ELEMENT name (#PCDATA)>
23.2Response Bodies for 403 and 409 Status Responses
A 403 (Forbidden) status indicates that an error has occurred that
the client cannot resolve, and therefore the request should not be
resubmitted. A 409 (Conflict) status indicates that an error has
occurred that the client can resolve, after which the request could
be resubmitted. According to RFC 2616, Section 10.4: "The 4xx
class of status code is intended for cases in which the client
seems to have erred. Except when responding to a HEAD request, the
server SHOULD include an entity containing an explanation of the
error situation, and whether it is a temporary or permanent
condition."
In order to allow better client handling of 403 and 409 responses,
WebDAV Versioning associates an XML element type with each method
precondition defined in this document. When a particular
precondition is violated by a request, the appropriate XML element
MUST be returned in the response body. This element MUST be the
top-level element of the response body unless otherwise negotiated
by the request. In a 207 Multi-Status response, this element would
appear under the appropriate DAV:response-description element.
23.2.1 Example - CHECKOUT request with DAV:must-not-be-checked-out
response
>>REQUEST
Clemm, et al. [Page 87]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
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:must-not-be-checked-out xmlns:D="DAV:"/>
In this example, the request to CHECKOUT /foo.html fails because
/foo.html is already checked out.
23.3Clarification of COPY Semantics with Overwrite:T
RFC 2518, Section 8.8.4 states:
"If a resource exists at the destination and the Overwrite header
is "T" then prior to performing the copy the server MUST perform a
DELETE with "Depth: infinity" on the destination resource."
This definition unfortunately does not allow you to update an
existing resource. 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.
Roy Fielding (an author of RFC 2518) has stated that in spite of
what is stated in RFC 2518, the intent for Overwrite:T with a COPY
request was that it should not delete the destination resource, but
rather should just update it (unlike the MOVE request which should
act as stated in RFC 2518, and delete the destination prior to the
MOVE).
Implementations of the versioning protocol MUST support "update"
semantics of COPY with Overwrite:T. In particular, the quoted
sentence should be ignored, and instead, results of a COPY MUST
update an existing resource at the destination rather than deleting
it and creating a new resource. If a client wishes the destination
to be deleted prior to the COPY, it MUST explicitly issue a DELETE
request.
23.4REPORT Method
A REPORT request is an extensible mechanism for obtaining
information about a resource. Unlike a resource property, which
has a single value, the value of a report can depend on additional
Clemm, et al. [Page 88]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
information specified in the REPORT request body and in the REPORT
request headers.
Marshalling:
The request body of a REPORT request specifies which report is
being requested, as well as any additional information that will be
used to customize the report.
The request MAY include a Depth header.
The response body MUST contain the requested report.
Postconditions:
The REPORT method MUST NOT change the content or dead properties of
any resource managed by the server.
If a Depth request header is included, the response MUST be a 207
Multi-Status. The REPORT request MUST be applied separately to the
collection itself and to all members of the collection that satisfy
the Depth value. The DAV:prop element of a DAV:response for a
given resource MUST contain the requested report for that resource.
23.4.1 Example - REPORT
>>REQUEST
REPORT /usa/texas HTTP/1.1
Host: www.geography.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<weather-report-request>
<date>01/03/2000</date>
</weather-report-request>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<weather-report>
Sunny and Cool
</weather-report>
In this example, the weather in Texas on January 3, 2000 is
reported as being sunny and cool.
Clemm, et al. [Page 89]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
23.4.2 Example - REPORT with Depth
>>REQUEST
REPORT /usa/texas HTTP/1.1
Host: www.geography.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Depth: infinity
<?xml version="1.0" encoding="utf-8" ?>
<weather-report-request>
<date>01/03/2000</date>
</weather-report-request>
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.geography.org/usa/texas</D:href>
<D:propstat>
<D:prop>
<weather-report>Sunny and Cool</weather-report>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.geography.org/usa/texas/austin</D:href>
<D:propstat>
<D:prop>
<weather-report>Cloudy and Cool</weather-report>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
In this example, the weather in Texas on January 3, 2000 is
reported as being sunny and cool, while the weather in Austin (the
only member of the Texas collection) is reported as being cloudy
and cool.
23.5DAV:property REPORT
Many properties consist of a set of one or more DAV:href elements.
The DAV:property REPORT provides a mechanism for retrieving in one
Clemm, et al. [Page 90]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
request the properties from the resources identified by those
DAV:href elements.
Marshalling:
The DAV:property REPORT request body MUST be a DAV:property-request
XML element.
<!ELEMENT property-request (property*)>
<!ELEMENT property (property*)>
<!ATTLIST property name NMTOKEN #REQUIRED>
name value: a property element type
The request MAY include a Depth header.
The DAV:property REPORT response body MUST be a DAV:multistatus XML
element.
multistatus: see RFC 2518, Section 12.9
Postconditions:
The properties reported in the DAV:prop elements of the
DAV:multistatus element are those identified by the DAV:property
elements in the DAV:property-request element. If there are
DAV:property elements nested within a DAV:property element, then
every DAV:href in the value of the corresponding property is
replaced by a DAV:response element whose DAV:prop elements report
the values of the properties identified by the nested DAV:property
elements. The nested DAV:property elements can in turn contain
DAV:property elements, so that multiple levels of DAV:href
expansion can be requested.
23.5.1 Example - DAV:property-report
This example describes how to query a version-controlled resource
to determine the DAV:creator-display-name and DAV:activity-set of
every version in the version history of that version-controlled
resource.
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:property-report xmlns:D="DAV:">
<D:property name="D:version-history">
<D:property name="D:version-set">
<D:property name="D:creator-displayname"/>
<D:property name="D:activity-set"/>
Clemm, et al. [Page 91]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
</D:property >
</D:property >
</D:property >
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/foo.html</D:href>
<D:propstat>
<D:prop>
<D:version-history>
<D:response>
<D:href>http://repo.webdav.org/his/23</D:href>
<D:propstat>
<D:prop>
<D:version-set>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/1<D:href>
<D:propstat>
<D:prop>
<D:creator-displayname>Fred</D:creator-
displayname>
<D:activity-set>
http://www.webdav.org/ws/dev/sally
</D:activity-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/2<D:href>
<D:propstat>
<D:prop>
<D:creator-displayname>Sally</D:creator-
displayname>
<D:activity-set> <D:href>
http://repo.webdav.org/act/add-refresh-
cmd
</D:href> </D:activity-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:version-set> </D:prop>
</D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:version-history> </D:prop>
</D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:multistatus>
Clemm, et al. [Page 92]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
In this example, the DAV:creator-displayname and DAV:activity-set
properties of the versions in the DAV:version-set of the
DAV:version-history of http://www.webdav.org/foo.html are reported.
23.6Additional OPTIONS Semantics
An OPTIONS request can be used to determine the methods, live
properties, and reports that are supported by the resource
identified by the request
Additional Marshaling:
If a request body is included, it MUST be a DAV:options XML
element.
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one DAV:supported-
method-set, DAV:supported-live-property-set, and DAV:supported-
report-set element.
<!ELEMENT supported-method-set (supported-method*)>
<!ELEMENT supported-method ANY>
<!ATTLIST supported-method name NMTOKEN #REQUIRED>
name value: a method name
<!ELEMENT supported-live-property-set (supported-live-property*)>
<!ELEMENT supported-live-property ANY>
<!ATTLIST supported-live-property name NMTOKEN #REQUIRED>
name value: a property element type
<!ELEMENT supported-report-set (supported-report*)>
<!ELEMENT supported-report ANY>
<!ATTLIST supported-report name NMTOKEN #REQUIRED>
name value: a report element type
If a response body is included, it MUST be a DAV:options-response
XML element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one DAV:supported-
method-set, DAV:supported-live-property-set, and DAV:supported-
report-set element.
Additional Postconditions:
(DAV:supported-method-set-OK): If DAV:supported-method-set is
included in the request body, the response body MUST contain a
DAV:supported-method-set element identifying which of the specified
methods are supported by the resource identified by the request-
URL. If the DAV:supported-method-set in the request body is empty,
then the response body MUST identify all methods supported by the
resource.
Clemm, et al. [Page 93]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
(DAV:supported-live-property-set-OK): If DAV:supported-live-
property-set is included in the request body, the response body
MUST contain a DAV:supported-live-property-set element identifying
which of the specified live properties are supported by the
resource identified by the request-URL. If the DAV:supported-live-
property-set in the request body is empty, then the response body
MUST identify all live properties supported by the resource.
(DAV:supported-report-set-OK): If DAV:supported-report-set is
included in the request body, the response body MUST contain a
DAV:supported-report-set element identifying which of the specified
reports are supported by the resource identified by the request-
URL. If the DAV:supported-report-set in the request body is empty,
then the response body MUST identify all reports supported by the
resource.
23.6.1 Example - OPTIONS
>>REQUEST
OPTIONS /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:supported-method-set>
<D:supported-method D:name="VERSION-CONTROL"/>
<D:supported-method D:name="BASELINE-CONTROL"/>
</D:supported-method-set>
<D:supported-live-property-set>
<D:supported-live-property D:name="D:version-history"/>
</D:supported-live-property-set>
<D:supported-report-set/>
</D:options>
>>RESPONSE
HTTP/1.1 200 OK
DAV: 1, 2, version-control
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options-response xmlns:D="DAV:">
<D:supported-method-set>
<D:supported-method D:name="VERSION-CONTROL"/>
</D:supported-method-set>
<D:supported-live-property-set/>
<D:supported-report-set>
<D:supported-report D:name="D:property-report"/>
</D:supported-report-set>
Clemm, et al. [Page 94]
INTERNET-DRAFT WebDAV Versioning January 5, 2001
</D:options-response>
In this example, the server indicates that it is a class 2 WebDAV
versioning server, that the resource /foo.html supports the method
VERSION-CONTROL but not the method BASELINE-CONTROL, that the
resource /foo.html does not support the DAV:version-history live
property, and that the resource /foo.html supports the
DAV:property-report report.
Clemm, et al. [Page 95]
