INTERNET-DRAFT Geoffrey Clemm, Rational Software
draft-ietf-deltav-versioning-07 Jim Amsden, IBM
Chris Kaler, Microsoft
Jim Whitehead, U.C. Irvine
Expires February 9, 2001 August 9, 2000
Versioning Extensions to WebDAV
Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026.
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 so as to
facilitate widespread deployment of applications capable of utilizing
the WebDAV Versioning services. WebDAV Versioning includes:
- Core versioning with automatic versioning for versioning-unaware
clients,
- Workspace, activity and baseline management,
- URL namespace versioning.
Clemm, et al. [Page 1]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Table of Contents
1 INTRODUCTION...........................................5
1.1 Relationship to DAV...................................6
1.2 Terms.................................................6
1.3 Notational Conventions................................8
2 WEBDAV VERSIONING SEMANTICS............................9
2.1 Creating and Modifying a Version-Controlled Resource..9
2.2 Changing the Target of a Version Selector............10
2.3 Labeling a Version...................................10
3 VERSIONING PROPERTIES BY RESOURCE TYPE................10
3.1 Common Property Values...............................11
3.1.1 boolean Syntax...................................11
3.1.2 label Syntax.....................................11
3.1.3 date-time Syntax.................................11
3.1.4 href XML Element.................................11
3.2 Resource Properties..................................11
3.2.1 DAV:creator-displayname..........................11
3.2.2 DAV:comment......................................12
3.3 Version Selector Properties..........................12
3.3.1 DAV:target (protected)...........................12
3.3.2 DAV:auto-version.................................12
3.3.3 DAV:version-name (protected).....................12
3.4 Version Properties...................................12
3.4.1 DAV:version (protected)..........................12
3.4.2 DAV:predecessor-set (protected)..................13
3.4.3 DAV:checkin-date (protected).....................13
3.4.4 DAV:label-name-set (protected)...................13
3.5 Working Resource Properties..........................13
3.5.1 DAV:checked-out (protected)......................13
4 VERSIONING HEADERS....................................13
4.1 Target-Selector......................................13
5 VERSIONING AND EXISTING METHODS.......................14
5.1 New Status Codes.....................................14
5.2 OPTIONS..............................................14
5.2.1 Example - OPTIONS................................14
5.3 GET..................................................15
5.4 PUT..................................................15
5.5 PROPFIND.............................................15
5.6 PROPPATCH............................................15
5.7 DELETE...............................................16
5.8 COPY.................................................16
5.9 MOVE.................................................16
5.10 LOCK...............................................16
6 VERSIONING METHODS....................................16
6.1 VERSION-CONTROL......................................16
6.1.1 Example - VERSION-CONTROL (creating a new version history) 18
6.1.2 Example - VERSION-CONTROL (using an existing version history) 18
Clemm, et al. [Page 2]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
6.2 CHECKOUT.............................................18
6.2.1 Example - CHECKOUT...............................19
6.3 CHECKIN..............................................20
6.3.1 Example - CHECKIN................................21
6.4 UNCHECKOUT...........................................21
6.4.1 Example - UNCHECKOUT.............................22
6.5 SET-TARGET...........................................22
6.5.1 Example - SET-TARGET.............................23
6.6 LABEL................................................23
6.6.1 Example - Replacing a label......................24
6.7 REPORT...............................................25
6.7.1 Example - REPORT.................................25
7 VERSIONING REPORTS....................................26
7.1 DAV:successor-report.................................26
7.1.1 Example - DAV:successor-report...................26
7.2 DAV:checkout-report..................................26
7.2.1 Example - DAV:checkout-report....................27
7.3 DAV:latest-checkin-report............................27
7.3.1 Example - DAV:latest-checkin-report..............27
7.4 DAV:version-tree-report..............................28
7.4.1 Example - DAV:version-tree-report................28
8 ADVANCED VERSIONING...................................30
8.1 Advanced Versioning Terms............................30
9 ADVANCED VERSIONING SEMANTICS.........................32
9.1 Workspaces...........................................32
9.2 Baselines............................................33
9.3 Activities, Change Sets, and Branches................33
9.4 Parallel Development and Merging.....................34
9.5 Version-Controlled Collections.......................34
9.6 Mutable Versions.....................................36
10 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE......37
10.1 Version Selector Properties........................37
10.1.1 DAV:version-history (protected)..................37
10.2 Version Properties.................................37
10.2.1 DAV:version-history (protected)..................37
10.2.2 DAV:activity-set.................................37
10.2.3 DAV:checkout-fork................................37
10.2.4 DAV:checkin-fork.................................38
10.2.5 DAV:mutable......................................38
10.3 Working Resource Properties........................38
10.3.1 DAV:version-history (protected)..................38
10.3.2 DAV:merge-set....................................38
10.3.3 DAV:auto-merge-set...............................39
10.3.4 DAV:unreserved...................................39
10.3.5 DAV:predecessor-set..............................39
10.3.6 DAV:activity-set.................................39
10.3.7 DAV:checkout-fork................................39
10.3.8 DAV:checkin-fork.................................39
10.3.9 DAV:mutable......................................40
10.4 Version History Properties.........................40
Clemm, et al. [Page 3]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
10.4.1 DAV:version-set (protected)......................40
10.4.2 DAV:initial-version (protected)..................40
10.4.3 DAV:working-resource-set (protected).............40
10.5 Workspace Properties...............................40
10.5.1 DAV:current-activity-set.........................40
10.5.2 DAV:parent-workspace (protected).................41
10.5.3 DAV:child-workspace-set (protected)..............41
10.6 Collection Properties..............................41
10.6.1 DAV:baseline-selector (protected)................41
10.7 Baseline Properties................................41
10.7.1 DAV:version-set (protected)......................41
10.8 Activity Properties................................42
10.8.1 DAV:version-set (protected)......................42
10.8.2 DAV:subactivity-set..............................42
11 ADVANCED VERSIONING HEADERS..........................42
11.1 Workspace..........................................42
12 ADVANCED VERSIONING AND EXISTING METHODS.............43
12.1 New Status Codes...................................43
12.2 OPTIONS............................................44
12.2.1 Example - OPTIONS................................44
12.3 GET................................................44
12.4 PUT................................................44
12.5 DELETE.............................................44
12.6 MKCOL..............................................45
12.7 COPY...............................................45
12.8 MOVE...............................................45
12.9 VERSION-CONTROL....................................45
12.10 CHECKOUT...........................................46
12.10.1........................Example - Advanced CHECKOUT 47
12.11 CHECKIN............................................48
12.12 UNCHECKOUT.........................................49
12.13 SET-TARGET.........................................49
13 ADVANCED VERSIONING METHODS..........................50
13.1 MKWORKSPACE........................................50
13.1.1 Example - MKWORKSPACE............................51
13.2 MKACTIVITY.........................................51
13.2.1 Example - MKACTIVITY.............................52
13.3 BASELINE-CONTROL...................................52
13.3.1 Example - BASELINE-CONTROL.......................53
13.4 MERGE..............................................53
13.4.1 Example - MERGE..................................55
14 ADVANCED VERSIONING REPORTS..........................56
14.1 DAV:property-report................................56
14.1.1 Example - DAV:property-report....................56
14.2 DAV:repository-report..............................58
14.3 DAV:workspace-url-report...........................58
14.3.1 Example - DAV:workspace-url-report...............58
14.4 DAV:baselined-collection-report....................59
14.4.1 Example - DAV:baselined-collection-report........59
14.5 DAV:merge-preview-report...........................60
Clemm, et al. [Page 4]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
14.5.1 Example - DAV:merge-preview-report...............60
14.6 DAV:compare-report.................................61
14.6.1 Example - DAV:compare-report.....................62
14.6.2 Example - DAV:repository-report..................63
14.7 DAV:current-workspace-report.......................63
14.7.1 Example - DAV:current-workspace-report...........63
14.8 DAV:version-selector-url-report....................64
14.8.1 Example - DAV:version-selector-url-report........64
15 INTERNATIONALIZATION CONSIDERATIONS..................64
16 SECURITY CONSIDERATIONS..............................65
17 SCALABILITY..........................................65
18 AUTHENTICATION.......................................65
19 IANA CONSIDERATIONS..................................65
20 INTELLECTUAL PROPERTY................................65
21 ACKNOWLEDGEMENTS.....................................66
22 INDEX................................................66
23 REFERENCES...........................................66
24 AUTHORS' ADDRESSES...................................67
25 APPENDICES...........................................67
26 OVERWRITE HEADER.....................................67
27 OPEN ISSUES AND PENDING CHANGES......................67
1 INTRODUCTION
This document defines WebDAV Versioning extensions, an application
of HTTP/1.1 for handling resource versioning in a WebDAV
environment. [Goals] describes the motivation and requirements for
these extensions. WebDAV Versioning defines two levels of
versioning functionality: core versioning and advanced versioning.
Core versioning provides versioning of largely independent
resources. It allows authors to concurrently create, label, and
access distinct versions of a resource, and provides automatic
versioning for versioning-unaware clients. All core versioning
functionality MUST be provided by a resource that supports
versioning.
Advanced versioning provides more sophisticated capabilities such
as logical change tracking, workspace management, and versioning
the URL namespace. A particular resource may support only a subset
Clemm, et al. [Page 5]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
of the advanced versioning capabilities. The advanced versioning
capabilities provided by a particular resource can be discovered
with an OPTIONS request.
This document will first define the terminology, semantics,
properties, methods, and headers for core versioning, and then
define the additional terminology, semantics, properties, and
methods for advanced versioning.
1.1 Relationship to DAV
To maximize interoperability and the use of existing protocol
functionality, versioning support is designed as extensions to the
WebDAV [RFC2518] protocol. The versioning extensions are designed
to be orthogonal to most aspects of the HTTP and WebDAV protocols,
except for specific interactions identified in sections 5 and 12.
The semantics of version-controlled collections relies on the
binding model defined by the WebDAV binding extensions [Binding].
1.2 Terms
This draft uses the terms defined in HTTP [RFC2616] and WebDAV
[RFC2518]. In addition, the following terms are defined:
Versionable Resource
A "versionable resource" is a resource that can be put under
version control.
Version
A "version" is an unmodifiable resource that contains the content
and dead properties of a particular state of a resource under
version control. A "version URL" is a URL chosen by the server to
identify a particular version.
Version History
A "version history" is a resource created when a resource is put
under version control to contain the versions of that resource.
A "version history URL" is a URL chosen by the server to identify a
version history resource.
Version Selector
A "version selector" is a resource that provides access to a
version of a particular version history. When a versionable
resource is put under version control, a new version history
resource is created and the versionable resource is replaced with a
version selector resource that selects the initial version of that
version history.
Clemm, et al. [Page 6]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Target
The version selected by a version selector resource is called the
"target" of that version selector. The content and dead properties
displayed by a version selector are those of the target version.
Working Resource
A "working resource" is a modifiable resource that results from
checking out a version selector resource. A "working resource URL"
is a URL chosen by the server to identify a particular working
resource.
Version Label
A "version label" is a string chosen by a client to identify a
particular version of a version history.
Initial Version
An "initial version" is the first version of a version history.
Predecessor, Successor, Ancestor, Descendant
A "predecessor" of a version is another version that was checked
out or merged to create the version. 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.
Clemm, et al. [Page 7]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
The following diagram illustrates several of the previous
definitions.
History of foo.html
+---+
Initial Version ----> | | V1
+---+
| ^
| |
+---+ |
Label ------> "beta1" | | V2 | Ancestor
+---+ |
/ \ |
/ \ |
+---+ +---+
| | V3 | | V4
^ +---+ +---+
| | | |
Predecessor | | | |
| +---+ +---+ |
| | V5 | | V6 | Descendant
| +---+ +---+ |
Successor | \ / |
| \ / v
v +---+
| | V7
+---+
Fork
When a second successor is added to a version, this creates a
"fork" in the version history. In the preceding diagram, there is
a fork at version V2.
1.3 Notational Conventions
The augmented BNF used by this document to describe protocol
elements is exactly the same as the one described in Section 2.1 of
[RFC2068]. Because this augmented BNF uses the basic production
rules provided in Section 2.2 of [RFC2068], 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 [RFC2119].
The term "protected" is placed in parentheses following the
definition of a property that cannot be updated with a PROPPATCH
request.
Clemm, et al. [Page 8]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
A phrase of the form "the method XXX is applied to a yyy" means
"the method XXX is applied to a URL that identifies a resource of
type yyy".
2 WEBDAV VERSIONING SEMANTICS
2.1 Creating and Modifying 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.
This creates a new version history resource, creates an initial
version in that version history that contains the current content
and dead properties of the versionable resource, and then replaces
the versionable resource with a version selector resource that
selects this initial version.
===VERSION-CONTROL==>
| foo.html
foo.html | foo.html History
|
+----+ | +----+ +----+
| S1 | | | ----------> | S1 |
+----+ | +----+ +----+
In order to modify the content or dead properties of a version
selector resource, an author must first check it out to create a
working resource. The author can then modify the state of the
working resource by setting its content or properties any number of
times. When the author determines the working resource is in a
state that should be retained, the author checks it in to create a
new version in the version history. The version that was checked
out is remembered as the predecessor of the new version. Unless
the server supports mutable versions, an author cannot modify the
content or dead properties of a version, but instead must create
descendants of that version.
Clemm, et al. [Page 9]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
The following diagram illustrates the effect of the
checkout/checkin process on a version history resource.
===CHECKOUT==> ===CHECKIN==>
foo.html | foo.html | foo.html
History | History | History
| |
+----+ | +----+ | +----+
| S1 | V1 | | S1 | V1 | | S1 | V1
+----+ | +----+ | +----+
| | | | |
| | | | |
+----+ | +----+ | +----+
| S2 | V2 | | S2 | V2 | | S2 | V2
+----+ | +----+ | +----+
| | |
| | |
| +----+ | +----+
| | WR | | | S3 | V3
| +----+ | +----+
2.2 Changing the Target of a Version Selector
Another way to modify the state of a version selector is to use a
SET-TARGET request to select another version to be the target of
that version selector. The SET-TARGET request will set the content
and dead properties of the version selector to be those of the
specified version.
2.3 Labeling a Version
At any time, a version can be given a client-assigned label 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 may be reassigned to another version at any
time. Note that although a given label cannot be applied to more
than one version from the same version history, the same label can
be applied to versions from different version histories.
For certain methods, a Target-Selector request header can be used
to make a version selector display the content and properties of
the version selected by the Target-Selector label, instead of those
of the target of that version selector.
3 VERSIONING PROPERTIES BY RESOURCE TYPE
This section defines the new resource types and properties
introduced by WebDAV versioning. When a property cannot be updated
Clemm, et al. [Page 10]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
by a PROPPATCH request, it is identified in this document as a
"protected" property.
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
server-defined.
3.1 Common Property Values
3.1.1boolean Syntax
Some properties take a Boolean value.
boolean = "F" | "T"
3.1.2label Syntax
A label is a sequence of characters. When a label is marshaled in
the header of an HTTP request, the characters are encoded using the
UTF-8 encoding scheme.
3.1.3date-time Syntax
Some properties take a date or time value. The syntax of date-time
is defined in section 23.2 of [RFC2518].
3.1.4DAV:href XML Element
The DAV:href XML element is defined in section 12.3 of [RFC2518].
3.2 Resource Properties
WebDAV versioning introduces the following dead properties for a
resource. These properties can be placed on any resource, and are
defined here only to provide a standard name for a property
containing this type of information about a resource.
3.2.1DAV: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.
Clemm, et al. [Page 11]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
3.2.2DAV: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.
3.3 Version Selector Properties
WebDAV versioning introduces the following properties for a version
selector.
3.3.1DAV:target (protected)
This property contains the version URL of the version that is the
target of this version selector.
This property can be modified by the CHECKIN and SET-TARGET
methods.
3.3.2DAV:auto-version
When the DAV:auto-version property of a version selector is set, a
request that attempts to modify that version selector (such as
PUT/PROPPATCH) is automatically preceded by a CHECKOUT and
automatically followed by a CHECKIN. This allows a versioning-
unaware client to modify a version selector.
PCDATA value: boolean
3.3.3DAV:version-name (protected)
This property contains a server-defined string that is different
for each version in a given version history.
3.4 Version Properties
WebDAV versioning introduces the following properties for a
version.
3.4.1DAV:version (protected)
This property contains the version URL for this version.
Clemm, et al. [Page 12]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
3.4.2DAV:predecessor-set (protected)
This property contains a version URL for each predecessor of this
version. Except for the initial version, which has no
predecessors, there is either the single predecessor that was
checked out to create the version, or there are the multiple
predecessors that were merged to create the version.
3.4.3DAV: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.
PCDATA value: date-time
3.4.4DAV:label-name-set (protected)
This property contains the labels that currently select this
version.
PCDATA value: label-name
3.5 Working Resource Properties
WebDAV versioning introduces the following properties for a working
resource.
3.5.1DAV:checked-out (protected)
This property contains the version URL of the version that defined
the initial state of the working resource.
4 VERSIONING HEADERS
4.1 Target-Selector
The following defines the BNF for the Target-Selector header:
Target-Selector := "Target-Selector" ":" label
An example of a Target-Selector header is:
Target-Selector: released
Clemm, et al. [Page 13]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
When a method supports the Target-Selector header, if the request-
URL identifies a version selector, the request MUST act as if the
content and dead properties of the version selector were that of
the version identified by the label specified in the Target-
Selector header.
A Target-Selector header has no effect on a request-URL that does
not identify a version selector. In particular, it has no effect
on a version URL, a working resource URL, or a version history URL.
A server MUST return a Vary header containing Target-Selector in a
response to a cacheable request (e.g. GET, PROPFIND) that includes
a Target-Selector header.
5 VERSIONING AND EXISTING METHODS
For any method that updates the content or dead properties of a
resource, when that method is applied to a version selector, the
method MUST fail unless the version selector has a DAV:auto-version
property. If the version selector has a DAV:auto-version property,
the version selector is checked out, the update is applied to the
resulting working resource, and the working resource is checked in.
This functionality allows a versioning unaware client to modify a
version selector. If any part of the checkout/update/checkin
sequence fails, the status from the failed part of the request MUST
be returned, and the server state preceding the request sequence
MUST be restored.
5.1 New Status Codes
4xx (No Version Selected): The label specified in a Target-Selector
header selects no version of this version selector.
4xx (Cannot modify content or property of a version)
5.2 OPTIONS
When a resource supports core versioning, the DAV response header
for an OPTIONS request MUST contain "core-versioning".
5.2.1Example - OPTIONS
>>REQUEST
OPTIONS /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
Clemm, et al. [Page 14]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
HTTP/1.1 200 OK
DAV: 1, 2, core-versioning
Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, VERSION-CONTROL
5.3 GET
Additional Marshalling:
A Target-Selector request header MAY be specified.
Additional Postconditions:
If the request URL identifies a version selector, the response will
contain the content of the target of the version selector.
5.4 PUT
Additional Preconditions:
If the request URL identifies a version selector, the PUT MUST fail
unless DAV:auto-version is set for that version selector.
If the request URL identifies a version, the PUT MUST fail.
Additional Postconditions:
If the PUT creates a new resource, it is server defined whether it
is under version control.
5.5 PROPFIND
Additional Marshalling:
A Target-Selector request header MAY be specified.
Additional Postconditions:
If the request-URL identifies a version selector, the response will
contain both the live properties of the version selector and the
dead properties of the target of the version selector.
5.6 PROPPATCH
Additional Preconditions:
If the request URL identifies a version selector, an attempt to
modify a dead property MUST fail unless DAV:auto-version is set for
that version selector.
If the request-URL identifies a version, the PROPPATCH MUST fail.
Clemm, et al. [Page 15]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
An attempt to modify a property (either core or advanced) defined
by this document as being protected MUST fail.
An attempt to modify a property (either core or advanced) whose
semantics defined by this document 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.
5.7 DELETE
Additional Preconditions:
If the request-URL identifies a version or a working resource, the
result is undefined. The CHECKIN and UNCHECKOUT methods can be
used to delete a working resource.
5.8 COPY
Additional Marshalling:
A Target-Selector request header MAY be specified.
Additional Postconditions:
It is server defined whether the new resource created at the
Destination is under version control.
5.9 MOVE
Additional Preconditions:
If the request-URL is a version URL, the request MUST fail.
5.10LOCK
Additional Preconditions:
If a LOCK request includes a Target-Selector request header, the
result is undefined.
6 VERSIONING METHODS
6.1 VERSION-CONTROL
A VERSION-CONTROL request can be used to create a version
controlled resource at the request-URL.
Clemm, et al. [Page 16]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
If the request-URL identifies a versionable resource, a new version
history resource is created, an initial version is created whose
content and dead properties are that of the versionable resource,
and the versionable resource is replaced by a version selector
resource whose target is the initial version of the new version
history.
If the request body identifies a version, the request-URL MUST
identify a null resource, and a new version selector whose target
is the specified version is created at the request-URL.
If a VERSION-CONTROL request fails, the server state preceding the
request MUST be restored.
Marshalling:
The request body MUST be a DAV:version-control XML element.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
The request-URL MUST identify a versionable resource, a null
resource, or a version selector.
If the request-URL identifies a versionable resource or a version
selector, the DAV:version-control request body element MUST be
empty.
If the request-URL identifies a null resource, the DAV:version-
control request body element must contain a version URL.
Return Status Codes:
200 (OK): A version selector resource already exists at the
request-URL.
201 (Created): A new version selector resource was created at the
request-URL.
Postconditions:
If the request-URL identified a version selector at the time of the
request, the VERSION-CONTROL request MUST NOT change the state of
that version selector.
If the request-URL identified a versionable resource at the time of
the request, a new version history is created, a copy of the
versionable resource is made the initial version of the new version
selector, and the versionable resource is replaced by a new version
selector resource whose DAV:target identifies the initial version
of the new version history. The DAV:predecessor-set of the initial
Clemm, et al. [Page 17]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
version is empty, and the DAV:checkin-date is the current date on
the server.
If the request-URL identified a null resource, a new version
selector resource is created at the request-URL whose target is the
version specified in the request body.
6.1.1Example - VERSION-CONTROL (creating a new version history)
>>REQUEST
VERSION-CONTROL /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
6.1.2Example - VERSION-CONTROL (using an existing version history)
>>REQUEST
VERSION-CONTROL /bar.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://repo.webdav.org/his/12/rev/V3
>>RESPONSE
HTTP/1.1 201 Created
6.2 CHECKOUT
A CHECKOUT request can be applied to a version selector to create a
new working resource. The content and properties of the working
resource are a copy of a version selected by the CHECKOUT request.
If a version is specified in the CHECKOUT request body, that is the
selected version; otherwise, if a version is selected by a Target-
Selector request header, that is the selected version; otherwise,
the target of the version selector is the selected version.
If a CHECKOUT request fails, the server state preceding the request
MUST be restored.
Marshalling:
Clemm, et al. [Page 18]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
If a request body is included, it MUST be a DAV:checkout XML
element.
The request MAY include a Target-Selector header.
The response MUST include a Location header.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
The request-URL MUST identify a version selector.
If a version is specified in the CHECKOUT request body, it MUST be
a version in the same version history as the current target of the
version selector.
If a label is specified in a Target-Selector header, it MUST select
a version in the version history of the target of the version
selector.
If the version selector is locked, the lock token MUST be specified
in the CHECKOUT request.
Response Status Codes:
201 (Created): The server created a new working resource.
405 (Method Not Allowed): The request-URL did not identify a
version selector.
Postconditions:
The Location response header MUST contain the URL of the new
working resource.
The DAV:checked-out property of the new working resource identifies
the selected version. The content and dead properties of the
working resource are the same as the content and dead properties of
the selected version. The DAV:version-history property of the
working resource is the same as that of the selected version.
6.2.1Example - CHECKOUT
>>REQUEST
CHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
Clemm, et al. [Page 19]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
>>RESPONSE
HTTP/1.1 200 OK
Location: http://www.webdav.org/ws/core/3/foo.html
6.3 CHECKIN
A CHECKIN request can be applied to a working resource to produce a
new version that is a copy of the working 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.
The response MUST include a Location header.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
The request-URL MUST identify a working resource.
If the version selector is write-locked, then the appropriate lock
token MUST be included in the request.
Response Status Codes:
201 (Created): The version was successfully created.
405 (Method Not Allowed): The request-URL did not identify a
working resource.
409 (Conflict): A precondition was violated.
Postconditions:
A new version in the version history of the version selector is
created.
The DAV:version of the new version is set to a server-defined URL.
The DAV:predecessor-set of the new version is set to the
DAV:checked-out property of the working resource.
The DAV:checkin-date of the new version is set to the current date
on the server.
Clemm, et al. [Page 20]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
The content and dead properties of the working resource are copied
into the new version.
Unless DAV:keep-checked-out is specified, the working resource is
deleted. If DAV:keep-checked-out is specified, the DAV:checked-out
property of the working resource is set to be the version URL of
the new version.
The DAV:target of the version selector is set to contain the
version URL of the new version.
The version URL for the new version is returned in a Location
response header.
6.3.1Example - CHECKIN
>>REQUEST
CHECKIN /ws/core/3/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/rev/32
6.4 UNCHECKOUT
An UNCHECKOUT request can be applied to a working 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:
The request-URL MUST identify a working resource.
If the request-URL is write-locked, the UNCHECKOUT request MUST
include the appropriate lock token.
Response Status Codes:
200 (OK): The checkout was successfully cancelled.
405 (Method Not Allowed): The URL did not identify a working
resource.
Clemm, et al. [Page 21]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Postconditions:
The working resource is deleted.
6.4.1Example - UNCHECKOUT
>>REQUEST
UNCHECKOUT /ws/core/3/foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
6.5 SET-TARGET
A SET-TARGET request can be applied to a version selector to change
the DAV:target of that version selector.
A SET-TARGET can be applied to a collection with a Depth header
even if the collection is not a version selector, in order to
perform the SET-TARGET on all its version selector members. Use of
a version element in a Depth SET-TARGET does not make sense since
the SET-TARGET would succeed on only one of the version selectors.
Marshalling:
The SET-TARGET request body MUST be a DAV:set-target XML element.
The request MAY include a Depth header.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
The request-URL MUST identify a version selector.
If a version is specified in the SET-TARGET request body, it MUST
be a version in the same version history as the current target of
the version selector.
If a label is specified in a Target-Selector header, it MUST select
a version in the version history of the target of the version
selector.
If the request-URL is write-locked, the SET-TARGET request MUST
include the appropriate lock token.
Clemm, et al. [Page 22]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Response Status Codes:
200 (OK): The version selector was successfully updated.
207 (Multi-status): The SET-TARGET was applied to a collection.
400 (Bad Request): The request body was invalid.
405 (Method Not Allowed): The request-URL did not identify a
version selector.
Postconditions:
The DAV:target of the version selector MUST be set to the specified
version.
If a Depth header is specified, the SET-TARGET request is applied
separately to the collection and to each of the members of the
collection that satisfy the depth constraint.
6.5.1Example - SET-TARGET
>>REQUEST
SET-TARGET /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
stable
>>RESPONSE
HTTP/1.1 200 OK
6.6 LABEL
A LABEL request can be applied to a version to modify or list the
labels on that version. If a LABEL request is applied to a version
selector, the operation is applied to the target of that version
selector unless a Target-Selector header is specified.
Marshalling:
The request body MUST be a DAV:label element.
Clemm, et al. [Page 23]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
PCDATA value: label-name
The request MAY include a Target-Selector header.
The request MAY include a Depth header.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
The request-URL MUST identify a version or a version selector.
If DAV:add is specified, the specified label MUST NOT currently
select a version of the version history of that version selector.
If DAV:remove is specified, the specified label MUST select that
version.
Response Status Codes:
200 (OK): The label modification was successful.
400 (Bad Request): The body of the request was not valid.
405 (Method Not Allowed): The request-URL did not identify a
version or a version selector.
Postconditions:
If DAV:add or DAV:replace is specified, the specified label selects
the version.
If DAV:remove is specified, the specified label no longer selects
any version of the version history of the version selector.
6.6.1Example - Replacing a label
>>REQUEST
LABEL /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
released
>>RESPONSE
HTTP/1.1 200 OK
Clemm, et al. [Page 24]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
6.7 REPORT
A REPORT request is an extensible mechanism for obtaining
information about resources. Unlike a resource property, a report
can depend on the state of resources in addition to the one
identified by the request-URL. The REPORT method MUST NOT change
the state of any resource managed by the server.
The request body of a REPORT request specifies which report is
being requested. The response body of a REPORT request contains
the requested report.
Every resource MUST support DAV:available-report, which lists the
reports supported at the request-URL.
The response body of DAV:available-report is a DAV:report-set
element containing empty XML elements identifying the reports
available at that request URL.
6.7.1Example - REPORT
Following is an example of a DAV:available-report:
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
>>RESPONSE
HTTP/1.1 200 OK
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Clemm, et al. [Page 25]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
7 VERSIONING REPORTS
Versioning introduces the following reports (the REPORT method is
defined in section 6.7).
7.1 DAV:successor-report
This report can be applied to a version or a version selector, and
lists the version URL of each version whose DAV:predecessor-set
contains the selected version.
The request MAY include a Target-Selector header.
The response body of a DAV:successor-report MUST be a
DAV:successor-set element.
7.1.1Example - DAV:successor-report
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://repo.webdav.org/his/23/rev/2
http://repo.webdav.org/his/23/rev/2.1.1
7.2 DAV:checkout-report
This report can be applied to a version or a version selector, and
lists all working resources whose DAV:checked-out property
identifies the selected version.
The request MAY include a Target-Selector header.
Clemm, et al. [Page 26]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
The response body of a DAV:checkout-report MUST be a DAV:working-
resource-set element.
7.2.1Example - DAV:checkout-report
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://repo.webdav.org/ws/1/foo.html
http://repo.webdav.org/ws/3/foo.html
7.3 DAV:latest-checkin-report
This report can be applied to a version selector, and returns the
version URL of the version with the latest DAV:checkin-date from
the version history of the version selector. If the version history
does not maintain DAV:checkin-date properties, no version will be
identified. If multiple versions contain the latest DAV:checkin-
date, the server arbitrarily picks one to identify as the latest.
The response body of a DAV:latest-checkin-report MUST be a DAV:href
element.
7.3.1Example - DAV:latest-checkin-report
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Clemm, et al. [Page 27]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://repo.webdav.org/his/23/rev/5
7.4 DAV:version-tree-report
The DAV:version-tree-report describes all the versions of the
version history of a version selector in the form of a nested tree
of versions.
The response body of a DAV:version-tree-report MUST be a
DAV:version-tree element.
A DAV:version-tree element contains a version URL followed by the
DAV:creator-displayname, DAV:comment, DAV:predecessor-set,
DAV:checkin-date, and DAV:label-name-set properties of that
version, the DAV:working-resource-set resulting from a
DAV:checkout-report for that version, and a DAV:version-tree for
each successor of that version.
A server MAY omit all elements other than DAV:version for a version
that has previously appeared in the DAV:version-tree element. This
can provide significant space savings when a version has multiple
predecessors.
7.4.1Example - DAV:version-tree-report
The version tree drawn below would produce the following version
tree report.
foo.html History
+---+
| | V1
+---+
/ \
/ \
Clemm, et al. [Page 28]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
+---+ +---+
| | 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
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://repo.webdav.org/his/23/rev/V1
Fred
get it started
http://repo.webdav.org/his/23/rev/V2
Fred
Fix the spelling
http://repo.webdav.org/his/23/rev/V1
http://repo.webdav.org/his/23/rev/V2.1.1
Sally
Translate into French
http://repo.webdav.org/his/23/rev/V1
Clemm, et al. [Page 29]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
8 ADVANCED VERSIONING
8.1 Advanced Versioning Terms
Workspace
A "workspace " is a collection that contains a set of related
versionable resources, version selectors, and working resources.
Clemm, et al. [Page 30]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Baseline
A baseline is a resource associated with a collection that captures
the target of each version selector that is a member of that
collection.
In the following diagram, /x/a.html, /x/y/b.html, and /x/y/c.html
are 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
+---+ +---+
Merging
"Merging" is a mechanism for updating a collection with a specified
set of versions. For each version to be merged, the version
selector in the collection whose version history contains that
version is identified. If the specified version is a descendant of
the target of the identified version selector, the merge changes
the target of the version selector to be the specified version. If
the specified version is an ancestor of the target of the
identified version selector, the merge leaves that version selector
unchanged. If the specified version is neither a descendant nor an
ancestor of the target of the identified version selector, the
merge checks out the version selector, and the client is then
responsible for updating the resulting working resource so that its
state corresponds to the logical merge of the specified version
with the checked out version.
Clemm, et al. [Page 31]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Activity
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. An activity will often
correspond to some unit of work or conceptual change.
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
+---+ +---+
9 ADVANCED VERSIONING SEMANTICS
9.1 Workspaces
In core versioning, working resources are identified by server
defined URL's. In order to allow a client to associate user
meaningful names with a related set of working resources, advanced
versioning provides a "workspace" resource. A workspace is a
collection whose members are a set of related versionable
resources, version selectors, and working resources. When a
version selector that is a member of a workspace is checked out, it
is replaced by the new working resource. When a working resource
that is a member of a workspace is checked in, it is replaced by a
version selector that selects the new version as its target.
Clemm, et al. [Page 32]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Initially, an empty workspace can be created. Versionable
resources can then be added to the workspace with standard WebDAV
requests such as PUT and MKCOL. As resources are identified whose
history should be tracked, they can be put under version control.
Alternatively, a workspace can be initialized by the state of an
existing workspace. In this case, a version selector is created in
the new workspace corresponding to each version selector in the
existing workspace, where corresponding version selectors in
different workspaces will share the same version history.
In order to ensure unambiguous merging and baselining semantics, a
workspace may contain at most one version selector for a given
version history (although a server may support multiple bindings in
a workspace to the same version selector). In order to expose
multiple views of a set of related version selectors in the URL
namespace, multiple workspaces must be used. In order to make a
change made to a version selector in one workspace visible in
another workspace, that version selector must be checked in, and
then the corresponding version selector in the other workspace can
be updated to select the new version.
9.2 Baselines
A workspace that contains a large number of version selectors can
consume a large amount of space on a server. This can make it
prohibitively expensive to remember the state of an existing
workspace by creating a copy of that workspace. A "baseline"
resource provides a mechanism to efficiently capture the state of a
workspace. In order to allow efficient baseline implementation,
the state of a baseline is limited to be a set of versions, and the
operations on a baseline are limited to the creation of a baseline
from a workspace, and restoring or merging the baseline back into a
workspace.
9.3 Activities, Change Sets, and Branches
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
represents a single logical change, where an activity tracks all
the resources that were modified to effect that single logical
change. When a version selector is checked out, the author
specifies which activity should be associated with a new version
that will be created when that version selector is checked in. It
is then possible to select a subset of the logical changes for
merging into another workspace, by specifying the appropriate
activities in a MERGE request.
Another common problem is that although a resource under version
control 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
Clemm, et al. [Page 33]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
avoid merging between team members). An activity resource provides
the mechanism for addressing this problem. When a version selector
is checked out, a client can request that an 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.
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".
9.4 Parallel Development and Merging
When an author wants to accept the changes made in another
workspace, it is important to not just select those versions as the
targets of the corresponding version selectors in the author's
workspace, since this would hide any changes made to those version
selectors in the author's workspace. Instead, the versions created
in another workspace should be "merged" into the author's
workspace.
The version history of a version selector 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 initial version. In case the versions
to be merged are on different lines of descent (neither version is
an ancestor 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 properties of those versions. The MERGE
request can be used to check out each version selector with such a
conflict, and set the DAV:merge-set property of each new working
resource to identify the versions to be merged. The author is
responsible for modifying the content of a working resource so that
it represents the logical merge of those versions, and then adding
the versions that were successfully merged to the DAV:predecessor-
set of the working resource.
If the server is capable of automatically performing the MERGE, it
MAY update the content of the working resource and the
DAV:predecessor set itself. An automatic merge is indicated by the
absence of a DAV:merge-set. Before checking in the working
resource, the author is responsible for verifying that the
automatic merge is correct.
9.5 Version-Controlled Collections
The state of a collection consists of a set of properties and a set
of named bindings to internal members of that collection. When a
Clemm, et al. [Page 34]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
collection is put under version control, the collection is replaced
by a version selector, and a history resource is created to contain
versions for that collection.
The only bindings captured by a collection version are those to
version-controlled resources. This not only preserves standard
versioning semantics (a version of a collection should not be
modifiable), but also provides for significant implementation
optimizations (version history URL's can be used to capture the
state of the collection bindings). A collection version selector
MAY contain bindings to unversioned resources, but these bindings
are not captured in the collection version history, and can be
changed without checking out the collection version selector. 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.
A SET-TARGET or MERGE request can add a binding to collection
version selector that has the same name as an existing binding to a
non-versioned member. In this case, the existing binding takes
precedence and is said to "eclipse" the new binding to a versioned
member. If the existing binding is removed (e.g. by a DELETE or
MOVE), the binding to the versioned member is exposed.
A collection version contains bindings to version histories rather
than to versions, so that creating a new version of a resource does
not require creating a new version of all the collections that
contain that resource, and so that activities in a workspace do not
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". But if a collection version instead 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 35]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
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 selector
for VH14 whose target is V2. The bindings of V2 have induced
corresponding bindings in /x. In particular, /x/a is a version
selector for VH19 (whose target currently is V4), and /x/b is a
version selector for VH24 (whose target currently is V8).
VH19
+---------+
| +---+ |
| | |V4 |
| +---+ |
| | |
| | |
| +---+ |
| | |V5 |
VH14 | +---+ |
+---------+ | | |
| +---+ | | | |
a +---+ | | |V1 | | +---+ |
---->| | Target=V4 | +---+ | a | | |V6 |
/ +---+ | | ------>| +---+ |
/ | | / | +---------+
+---+ | +---+ |
/x | | Target=V2 | | |V2 |
+---+ | +---+ | VH24
\ | | \ | b +---------+
\ b +---+ | | ------>| +---+ |
---->| | Target=V8 | +---+ | | | |V7 |
+---+ | | |V3 | | +---+ |
| +---+ | | | |
+---------+ | | |
| +---+ |
| | |V8 |
| +---+ |
| | |
| | |
| +---+ |
| | |V9 |
| +---+ |
+---------+
9.6 Mutable Versions
Normally, a version cannot be changed and provides a reliable
environment for state recovery, change tracking, stable workspaces,
and merging. If a server supports mutable versions, the client may
request that a checkin should overwrite the version that was
Clemm, et al. [Page 36]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
checked out, instead of creating a new version. This can be an
advantage when a simple history is more important than the benefits
provided by an immutable version history, but does introduce a
significant performance penalty in distributed environments,
because the state of a mutable version cannot be reliably cached.
10 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE
This section defines the new resource types and properties
introduced by WebDAV advanced versioning.
10.1Version Selector Properties
WebDAV advanced versioning introduces the following properties for
a version selector.
10.1.1 DAV:version-history (protected)
This property contains a version history URL for the version
history for this version selector.
10.2Version Properties
WebDAV advanced versioning introduces the following properties for
a version:
10.2.1 DAV:version-history (protected)
This property contains a version history URL for the version
history associated with this version.
10.2.2 DAV:activity-set
This property contains the URL's for the activities that indicate
what lines of descent this version appears on. A server MAY
restrict the DAV:activity-set to contain a single activity.
10.2.3 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 working
Clemm, et al. [Page 37]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
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.
10.2.4 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.
10.2.5 DAV:mutable
This property indicates whether the version can be updated by a
CHECKIN with DAV:overwrite.
PCDATA value: boolean
10.3Working Resource Properties
WebDAV advanced versioning introduces the following properties for
a working resource:
10.3.1 DAV:version-history (protected)
This property contains a version history URL for the version
history associated with this working resource.
10.3.2 DAV:merge-set
The DAV:merge-set of a working resource contains a version URL for
each version that is to be merged into this working resource.
Clemm, et al. [Page 38]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
10.3.3 DAV:auto-merge-set
The DAV:auto-merge-set of a working resource contains a version URL
for each version that the server has merged into this working
resource. The client should confirm that the merge has been
performed correctly before moving a version URL from the DAV:auto-
merge-set to the DAV:predecessor-set of a working resource.
10.3.4 DAV:unreserved
This property indicates whether the DAV:activity-set of another
working resource associated with the version history of this
working resource can have an activity that is in the DAV:activity-
set property of this working resource.
If multiple working resources for a given version history are
checked out unreserved into a single activity, only the first
CHECKIN will succeed. Before the other working resources can be
checked in, the author will have to merge the latest version of
that activity into the working resource and then modify the
DAV:predecessor-set of that working resource.
PCDATA value: boolean
10.3.5 DAV:predecessor-set
This property determines the DAV:predecessor-set property of the
version that results from checking in this working resource. The
order of the DAV:href elements in DAV:predecessor-set MUST be
maintained by the server.
10.3.6 DAV:activity-set
This property determines the DAV:activity-set property of the
version that results from checking in this working resource.
10.3.7 DAV:checkout-fork
This property determines the DAV:checkout-fork property of the
version that results from checking in this working resource.
10.3.8 DAV:checkin-fork
This property determines the DAV:checkin-fork property of the
version that results from checking in this working resource.
Clemm, et al. [Page 39]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
10.3.9 DAV:mutable
This property determines the DAV:mutable property of the version
that results from checking in this working resource.
10.4Version History Properties
The DAV:resourcetype of a version history MUST be DAV:version-
history.
WebDAV advanced versioning introduces the following properties for
a version history:
10.4.1 DAV:version-set (protected)
This property contains a version URL for each version of this
version history.
10.4.2 DAV:initial-version (protected)
This property contains a version URL for the initial version of
this version history.
10.4.3 DAV:working-resource-set (protected)
This property contains a URL for each working resource whose
DAV:version-history property identifies this version history.
10.5Workspace Properties
The DAV:resourcetype of a workspace MUST be DAV:collection. WebDAV
advanced versioning introduces the following properties for a
workspace:
10.5.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.
Clemm, et al. [Page 40]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
10.5.2 DAV:parent-workspace (protected)
This property identifies the workspace that was used to initialize
this workspace.
10.5.3 DAV:child-workspace-set (protected)
This property identifies the workspaces whose DAV:parent-workspace
identify this workspace.
10.6Collection Properties
WebDAV advanced versioning introduces the following properties for
a collection:
10.6.1 DAV:baseline-selector (protected)
This property contains the URL of a baseline selector that is used
to track 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.
When the baseline selector of a collection is checked out, the
resulting working baseline tracks the target of each version
selector that is a member of the collection. When the working
baseline is checked in, its state is captured by a new baseline in
the baseline history.
10.7Baseline Properties
The DAV:resourcetype of a baseline MUST be DAV:baseline. WebDAV
advanced versioning introduces the following properties for a
baseline.
10.7.1 DAV:version-set (protected)
This property contains a version URL for each version selected by
the baseline. At most one version of a given version history can
be selected by a baseline's DAV:version-set property.
Clemm, et al. [Page 41]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
10.8Activity Properties
The DAV:resourcetype of an activity MUST be DAV:activity. WebDAV
advanced versioning introduces the following properties for an
activity:
10.8.1 DAV:version-set (protected)
This property contains a version 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 initial version of that version history.
10.8.2 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
into a workspace, the latest version in this extended set is the
one that will be merged.
11 ADVANCED VERSIONING HEADERS
11.1Workspace
The following defines the BNF for the Workspace header:
Workspace := "Workspace" ":" URL
A Workspace header provides a convenient mechanism for making
"workspace relative" requests. When a Workspace header is included
in a request, the internal members of that workspace are treated by
that request as if they were internal members of "/". For example,
the following two requests are equivalent:
COPY /doc/index.html HTTP/1.1
Host: www.webdav.org
Destination: /newdoc/index.html
Workspace: /workspace/mywksp
COPY /workspace/mywksp/doc/index.html HTTP/1.1
Host: www.webdav.org
Destination: /workspace/mywksp/newdoc/index.html
Clemm, et al. [Page 42]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
When a Workspace header is included in a request to create a new
internal members of "/", a new internal member is added to the
workspace instead of "/". For example, the following two requests
are equivalent:
MKCOL /src HTTP/1.1
Host: www.webdav.org
Workspace: /workspace/mywksp
MKCOL /workspace/mywksp/src HTTP/1.1
Host: www.webdav.org
A request that includes a Workspace header MUST fail if an internal
member of the specified workspace has the same name as an internal
member of "/".
A response to a cacheable request (e.g. GET, PROPFIND) that
includes a Workspace header MUST include a Vary header containing
"Workspace".
12 ADVANCED VERSIONING AND EXISTING METHODS
For any request that includes a Workspace header, the request-URL
and every request header URL must be treated as if it were prefixed
with the workspace URL specified in the Workspace header.
For any method that modifies the bindings of a collection (e.g.
DELETE, MOVE, COPY), when that collection is a collection version
selector and when the binding is to a version selector, the method
MUST fail unless the collection version selector has a DAV:auto-
version property. If the collection version selector has a
DAV:auto-version property, the collection version selector is
checked out, the update is applied to the resulting working
collection, and the working 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.
12.1New Status Codes
4xx (Cannot CHECKOUT without DAV:fork-ok, version already checked
out)
4xx (Cannot CHECKOUT, version already checked out)
4xx (Cannot CHECKIN without DAV:fork-ok, version already has a
successor)
4xx (Cannot CHECKIN, version already has a successor)
Clemm, et al. [Page 43]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
12.2OPTIONS
When a resource supports advanced versioning, the DAV response
header for an OPTIONS request MUST indicate which advanced
versioning extensions are supported. The possible extensions are:
"property-report", "workspace", "mkworkspace", "workspace-header",
"workspace-url-report", "version-selector-url-report", "baseline",
"baseline-control", "activity", "mkactivity", "workspace-current-
activity", "subactivity", "working-resource-unreserved", "working-
resource-predecessor-set", "working-resource-merge-set", "merge",
"merge-preview-report", "collection-versioning", "checkout-fork",
"checkin-fork", "mutable-version".
12.2.1 Example - OPTIONS
>>REQUEST
OPTIONS /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
DAV: 1, 2, core-versioning, workspace, merge
Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, CHECKOUT, MERGE
12.3GET
Additional Preconditions:
If the request URL identifies a version history, an activity, or a
baseline, the result is undefined.
12.4PUT
Additional Preconditions:
If the request URL identifies a version history, an activity, or a
baseline, the result is undefined.
12.5DELETE
Additional Preconditions:
If the request-URL identifies a version selector, the DELETE MUST
fail when the collection containing the version selector is a
collection version selector, unless DAV:auto-version is set for
that collection version selector.
Additional Postconditions:
Clemm, et al. [Page 44]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
If the request-URL identifies a version history, the result is
undefined.
12.6MKCOL
Additional Postconditions:
It is server defined whether the new collection is under version
control and whether it is under baseline control.
12.7COPY
Additional Preconditions:
If the request-URL identifies a version history, the request MUST
fail. In order to create another version history with a similar
history, the appropriate sequence of VERSION-CONTROL, CHECKOUT,
PUT, PROPPATCH, and CHECKIN requests must be made.
Additional Postconditions:
It is server defined whether any new resource created by COPY is
under version control, and whether any new collection created by
COPY is under baseline control.
If a COPY creates a new version selector at the destination, it
MUST create a new version history to be associated with that new
version selector.
12.8MOVE
Additional Preconditions:
If the request-URL identifies a version selector, the request MUST
fail when the collection containing the version selector is a
collection version selector, unless DAV:auto-version is set for
that collection version selector.
If the request-URL identifies a version selector, the request MUST
fail when the collection containing the destination is a collection
version selector, unless DAV:auto-version is set for that
collection version selector.
If the request-URL identifies a version history, an activity, or a
baseline, the request MUST fail.
12.9VERSION-CONTROL
Additional Preconditions:
Clemm, et al. [Page 45]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
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
be another member of that workspace whose DAV:version-history
property specifies the version history that contains that version.
If the collection containing the request-URL is a collection
version selector, the request MUST fail unless DAV:auto-version is
set for that collection version selector.
Additional Postconditions:
If the request body specifies a version, the DAV:version-history of
the new version selector identifies the version history that
contains that version.
If a new version history is created and if the version selector is
a member of a workspace, the DAV:activity-set of the initial
version of the new version history is the DAV:current-activity-set
of that workspace.
12.10 CHECKOUT
When activities are supported, a CHECKOUT request MAY specify a
request activity set in the request body. If the version selector
is a member of a workspace, and no activity is specified in the
request body, the DAV:current-activity-set of the workspace is the
request activity set.
Additional Marshalling:
Additional Preconditions:
If there is a request activity set, unless DAV:unreserved is
specified, another working resource for that version history MUST
NOT select an activity in that activity set, and the selected
version MUST be a descendant of all other versions of that version
history that select that activity.
If DAV:unreserved is specified, all other working resources of that
version history whose DAV:activity-set contains one of the request
activities MUST have a DAV:unreserved property whose value is "T".
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 or if a working resource
Clemm, et al. [Page 46]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
contains that version in its DAV:checkout property. If the value
is DAV:discouraged, such a request MUST fail unless DAV:fork-ok is
specified in the request.
Additional Postconditions:
The URL of the working resource is added to the DAV:working-
resource-set property of its version history.
If a Workspace request header is specified, the version selector at
the request-URL MUST be replaced by the new working resource.
If the version selector was a baseline selector, the version
selector at the request-URL MUST be replaced by the new working
resource.
If the version selector was a collection, the new working
collection MUST contain bindings to all members of that collection
version selector.
The DAV:predecessor-set property of the new working resource is
initialized to be the same version as the DAV:checked-out property.
The DAV:activity-set of the new working 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 selector 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 checked out version is used.
If DAV:unreserved was specified in the CHECKOUT request body, then
the DAV:unreserved property of the working resource MUST be "T".
12.10.1 Example - Advanced CHECKOUT
>>REQUEST
CHECKOUT /ws/public/foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://repo.webdav.org/act/fix-bug-23
>>RESPONSE
Clemm, et al. [Page 47]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
HTTP/1.1 201 Created
Location: http://www.webdav.org/ws/public/foo.html
12.11 CHECKIN
Normally, a CHECKIN request will create a new version. If a server
supports mutable versions and if DAV:overwrite is specified, then
instead of creating a new version, CHECKIN will overwrite the value
of the version identified by the DAV:checked-out property of the
working resource.
Additional Marshalling:
Additional Preconditions:
Each version in DAV:predecessor-set of the working resource MUST
have the same DAV:version-history value as the working resource.
Any version in the version history of the working resource whose
DAV:activity-set contains an activity from the DAV:activity-set of
the working resource MUST be in the DAV:predecessor-set or an
ancestor of a version in the DAV:predecessor-set of the working
resource.
The DAV:merge-set and DAV:auto-merge-set of the working resource
MUST be empty.
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. If DAV:checkin-fork is
DAV:discouraged, such a CHECKIN request MUST fail unless DAV:fork-
ok is specified in the CHECKIN request body.
If DAV:overwrite is specified, the request MUST fail unless the
DAV:mutable property of the DAV:checked-out version is "T".
Additional Postconditions:
If the DAV:predecessor-set property of the working resource is non-
empty, the DAV:predecessor-set of the new version is set to that
value instead of the value of the DAV:checked-out property.
The DAV:version-history of the new version is the DAV:version-
history of the working resource.
The DAV:version-set of the version history is updated to include
the new version.
Clemm, et al. [Page 48]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
If the working resource was a member of a workspace, it is replaced
by a version selector whose DAV:target specifies the new version
created by the CHECKIN.
If the working resource was a collection, the bindings of the
working collection are moved to the collection version selector
that replaces it.
If the working resource was a collection, then the new collection
version contains bindings to the version histories of the version
selector members of the working collection.
If DAV:keep-checked-out is not specified, the URL of the working
resource is removed from the DAV:working-resource-set property of
its version history.
The DAV:activity-set of the new version is the DAV:activity-set of
the working resource.
For each activity in the DAV:activity-set property of the new
version, a version URL for the new version is added to the
DAV:version-set property of that activity.
If DAV:hidden is specified, the DAV:target of the version selector
is not changed by the CHECKIN request.
If DAV:overwrite is specified, a new version is not created, but
instead the content and properties of the working resource replace
those of the DAV:checked-out version.
12.12 UNCHECKOUT
Additional Postconditions:
The URL of the working resource is removed from the DAV:working-
resource-set property of its version history.
If the working resource is a member of a workspace, it is replaced
by a version selector whose DAV:version-history is that of the
working resource, and whose DAV:target is the DAV:checked-out
version of the working resource.
.If the request-URL identifies a working collection, then the
private bindings of the working collection are moved to the
collection version selector that replaces it.
12.13 SET-TARGET
Additional Postconditions:
Clemm, et al. [Page 49]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
If the request-URL identifies a baseline selector for a collection,
then the target of each version selector that is a member of that
collection is modified to be the version selected by that baseline.
If the SET-TARGET request modifies the DAV:target of a collection
version selector, then all bindings in that collection version
selector to version selectors are replaced by the bindings
specified by the new target. In particular, bindings are deleted
for version selectors whose version histories are not a member of
the new target version, bindings are renamed for version selectors
whose version histories have been renamed in the new target
version, and bindings are created to version selectors whose
version histories have been added to the new target version. If a
new binding identifies a version selector that was not previously a
member of that workspace, then a new version selector is created
whose DAV:target is the initial version of that version history.
13 ADVANCED VERSIONING METHODS
13.1MKWORKSPACE
A MKWORKSPACE request creates a new workspace resource. A server
may restrict workspace creation to a particular collection, but a
client can determine the location of this collection with a
repository REPORT (see section 14.2).
The MKWORKSPACE request body can be used to initialize the
workspace with version selectors whose targets are the versions of
a specified baseline or the version selector targets of another
specified workspace.
If a MKWORKSPACE request fails, the server state preceding the
request MUST be restored.
Marshalling:
The request body MUST be a DAV:mkworkspace XML element.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
A resource MUST NOT exist at the Request-URL.
If a DAV:parent-workspace is included in the request body, it MUST
identify a workspace.
Clemm, et al. [Page 50]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
If a DAV:baseline is included in the request body, it MUST identify
a baseline.
Return Status Codes:
201 (Created): The new workspace was successfully created.
403 (Forbidden): The server does not allow the creation of a
workspace at the requested location.
Postconditions:
A new workspace exists at the request-URL.
If the request body contains a DAV:parent-workspace element, the
DAV:parent-workspace of the new workspace is set to be the
specified workspace, and the URL of the new workspace is added to
the DAV:child-workspace-set of the specified workspace. For each
version selector that is a member of the parent workspace, a new
version selector with the same DAV:version-history property will be
created in the new workspace. The new version selector will have
the same name relative to the new workspace as the existing version
selector has relative to the parent workspace. Any collections
that are needed in the new workspace to provide the appropriate
name for a version selector will be created.
13.1.1 Example - MKWORKSPACE
>>REQUEST
MKWORKSPACE /ws/public HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
13.2MKACTIVITY
A MKACTIVITY request creates a new activity resource. If a server
restricts the creation of activities to a server-defined
collection, a client can determine the location of this collection
with a repository REPORT (see section 14.2).
Marshalling:
The response MUST include a Cache-Control:no-cache header.
Preconditions:
A resource MUST NOT exist at the request-URL.
Clemm, et al. [Page 51]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Return Status Codes:
201 (Created): The new activity was successfully created.
Postconditions:
A new activity exists at the request-URL.
13.2.1 Example - MKACTIVITY
>>REQUEST
MKACTIVITY /repo/activity/test-23 HTTP/1.1
Host: www.webdav.org
>>RESPONSE
HTTP/1.1 201 Created
13.3BASELINE-CONTROL
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
can be checked out and then checked in to create a new baseline for
that collection.
If a baseline history is specified in the BASELINE-CONTROL request
body, the target of the new baseline selector will be the initial
version of that baseline history. If no baseline history is
specified, a new baseline history is created whose initial version
is an empty baseline (i.e. its DAV:version-set is empty).
Marshalling:
The request body MUST be a DAV:baseline-control XML element.
Preconditions:
The request-URL MUST identify a collection whose DAV:baseline-
control property is empty.
If the DAV:baseline-control request body element is not empty, the
DAV:href MUST identify a baseline history.
If the request-URL identifies a workspace or a member of a
workspace, and if the DAV:baseline-control element identifies a
baseline history, then there MUST NOT be another member of that
workspace whose DAV:baseline-selector property identifies a
baseline selector for that baseline history.
Clemm, et al. [Page 52]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Return Status Codes:
200 (OK): The collection was successfully placed under baseline
control.
Postconditions:
A new baseline selector resource is created and associated with the
baseline history specified in the DAV:baseline-control request body
element. If no baseline history is specified in the request body,
a new baseline history with an empty initial version is created at
a server-defined URL.
The DAV:baseline-selector of the collection identifies the new
baseline selector.
The DAV:target of the new baseline selector identifies the initial
baseline of the baseline history.
13.3.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
http://repo.webdav.org/his/22
>>RESPONSE
HTTP/1.1 201 Created
13.4MERGE
The MERGE method performs a logical merge of a specified version
into a specified version selector or working resource. In general,
a MERGE request specifies a set of versions (the "request
versions") and a collection of version selectors and working
resources (the "merge destination"), and the MERGE method is
responsible for determining which version selector or working
resource in that collection (if any) should be the destination of
each request version.
If the request URL identifies a version, that version is the
request version.
If the request URL identifies a version selector, and a Target-
Selector request header is specified, the version selected by that
Clemm, et al. [Page 53]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Target-Selector is the request version; otherwise the target of
that version selector is the request version. If the request-URL
identifies a collection and a Depth:infinity header is specified,
the target of each version selector in that collection is a request
version.
If the request URL identifies a baseline, each version selected by
that baseline is a request version.
If the request URL identifies an activity, then for each version
history containing a version selected by that activity, the latest
version selected by that activity is a request 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.
For each request version, the server determines the "merge
destination" for that request version. The merge destination is
the member of the destination collection that is a version selector
or working resource whose DAV:version-history is the same as that
of the request version. If a request version has no merge
destination, that request version is ignored by the MERGE.
Marshalling:
The request body MUST be a DAV:merge element.
The request MUST include a Destination header.
The request MAY include a Depth header.
The response body MUST contain a DAV:merge-response element.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
The request-URL MUST NOT identify a working resource. If the
request-URL identifies a collection, the collection MUST NOT have a
member that is a working resource.
The Destination header MUST identify a version selector, a working
resource, or a collection.
If the MERGE request modifies a write-locked version selector or
working resource, the request MUST include the appropriate lock
token.
Clemm, et al. [Page 54]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
The checkouts performed to resolve conflicts MUST NOT violate any
of the pre-conditions of the CHECKOUT operation.
Response Status Codes:
200 (OK): The merge was performed.
2xx (Partial Merge): Only part of the requested merge could be
performed.
Postconditions:
The result of a merge depends on the relationship between the
request version and it's merge destination.
If the merge destination is a working resource, the request version
is added to the DAV:merge-set of the working resource.
If the merge destination is a version selector whose target is a
descendant of the request version, the merge destination is
unaffected by the MERGE.
If the merge destination is a version selector whose target is an
ancestor of the request version, the DAV:target of the merge
destination is modified to select the request version. The merge
destination URL MUST appear in the DAV:update-set.
If the merge destination is a version selector whose target is
neither a descendant nor an ancestor of the request version, the
merge destination is checked out and the DAV:merge-set of the new
working resource is set to contain the request version. The merge
destination URL MUST appear in the DAV:update-set.
If a request version has no merge destination, the version URL of
the request version MUST appear in the DAV:ignored-set.
If DAV:no-auto-merge is specified in the request body, the request
MUST NOT set or modify the DAV:auto-merge-set property of any
working resource, including ones created by the MERGE request.
13.4.1 Example - MERGE
>>REQUEST
MERGE /act/fix-parser-bug HTTP/1.1
Host: repo.webdav.org
Destination: http://www.webdav.org/ws/public
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Clemm, et al. [Page 55]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Content-Length: xxxx
http://www.webdav.org/ws/public/src/parse.c
http://www.webdav.org/ws/public/src/inc/parse.h
http://www.webdav.org/ws/public/doc/parse.html
14 ADVANCED VERSIONING REPORTS
Advanced versioning introduces the following reports (the REPORT
method is defined in section 6.7).
14.1DAV: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
request the properties from the resources identified by those
DAV:href elements.
The elements of a DAV:property-report identify which properties of
a resource are to be reported. If a property element is empty,
then just the value of that property is returned. If a property
element contains a list of properties, then the specified
properties of each resource identified by a DAV:href in the
specified property is returned as well. The property elements in
the nested property lists can in turn contain property lists, so
that multiple levels of DAV:href expansion can be requested.
The response body of a DAV:property-request is a DAV:multistatus
element as returned by a PROPFIND request. If the DAV:property-
report indicates that each DAV:href in a particular property value
is to be expanded, the DAV:href element that normally would be
returned by PROPFIND is replaced by a DAV:response element that
contains those properties.
14.1.1 Example - DAV:property-report
This example describes how to query a version selector to determine
the DAV:creator-display-name and DAV:activity-set of every version
in the version history of that version selector.
Clemm, et al. [Page 56]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.webdav.org/foo.html
http://repo.webdav.org/his/23
http://repo.webdav.org/his/23/rev/1
Fred
http://repo.webdav.org/act/fix-parser-
bug
HTTP/1.1 200 OK
http://repo.webdav.org/his/23/rev/2
Clemm, et al. [Page 57]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
Sally
http://repo.webdav.org/act/add-refresh-
cmd
HTTP/1.1 200 OK
HTTP/1.1 200 OK
HTTP/1.1 200 OK
14.2DAV:repository-report
Often a versioning implementation requires that workspaces and
activities be located in server specified collections. When such a
constraint exists, the DAV:repository-report can be used to
determine the URL's of these collections.
A DAV:repository-report response is a DAV:repository-set element
that contains a DAV:href for each server-defined collection in
which the specified type of resource can be located. Since
different servers can control different parts of the URL namespace,
the value of a DAV:repository response will depend on the request-
URL. A server MAY allow the client to create sub-collections in
the collections specified in the DAV:repository-set. The
collections specified in the DAV:repository-set MAY be located on
different hosts from the request-URL and each other.
14.3DAV:workspace-url-report
The DAV:workspace-url-report identifies the longest prefix of the
request-URL that identifies a workspace (if any).
If no prefix of the request-URL identifies a workspace, a 404
response status is returned.
14.3.1 Example - DAV:workspace-url-report
>>REQUEST
Clemm, et al. [Page 58]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
REPORT /ws/public/myCollection/foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.webdav.org/ws/public
14.4DAV:baselined-collection-report
This report can be applied to a workspace, and lists all
collections whose DAV:baseline-selector property is set.
The response body of a DAV:baselined-collection-report MUST be a
DAV:baselined-collection-set element.
14.4.1 Example - DAV:baselined-collection-report
>>REQUEST
REPORT /ws/public HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.webdav.org/ws/public/src
http://www.webdav.org/ws/public/doc/help
Clemm, et al. [Page 59]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
14.5DAV:merge-preview-report
A merge preview describes the changes that would result if the
versions specified by the request-URL were merged into the
destination workspace. The destination workspace is specified in a
Destination request header.
A DAV:merge-preview-report response contains a DAV:merge-preview-
response element, which contains the list of version selectors and
working resources that would be modified by the merge, and the list
of versions ignored by the merge.
The DAV:conflict element contains the URL of a version selector or
working resource that requires a merge. It also contains a
DAV:common-ancestor for the conflict, and two DAV:contributor
elements for the conflict.
The DAV:common-ancestor element contains a version URL for a
version that is a common ancestor of all the DAV:contributor
elements for a particular conflict. The first DAV:contributor
element contains a version URL for the version selected by the
workspace. The remaining DAV:contributor elements identify the
version selected by the request-URL.
The DAV:update element contains the URL of a version selector whose
target would change as a result of the merge, and contains the
version URL for the new target.
The DAV:ignored-set element contains the version URL's of each
version that would be ignored by the merge.
Response Status Codes:
200 (OK): The merge was performed.
2xx (Partial Merge): Only part of the requested merge could be
performed.
14.5.1 Example - DAV:merge-preview-report
>>REQUEST
Clemm, et al. [Page 60]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
REPORT /act/fix-it HTTP/1.1
Host: repo.webdav.org
Destination: http://www.webdav.org/ws/public
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.webdav.org/ws/public/foo.html
http://repo.webdav.org/his/23/rev/18
http://repo.webdav.org/his/23/rev/42
http://repo.webdav.org/his/23/rev/56
http://www.webdav.org/ws/public/bar.html
http://www.repo/his/42/rev/3
14.6DAV:compare-report
A DAV:compare-report identifies the differences between the
resource identified by the request-URL (base) and the resources
specified in the body of the request (contributors). The comparison
is carried out transitively on any children of the resources
according to the value of the Depth header. If the Depth header is
not specified, the value infinity is assumed. Resources appearing
in a contributor but not in the base are described by DAV:added
elements, resources appearing in the base but not a contributor are
described by DAV:deleted elements, and resources appearing in both
base and contributor but having different states are described by
DAV:changed elements. Resource content comparison is not
specified, though servers MAY provide it.
A DAV:compare-report contains the URL's of the resources to be
compared with the resource identified by the request URL.
Clemm, et al. [Page 61]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
The body of DAV:compare-report response is a DAV:comparison
element, which contains DAV:added, DAV:deleted, and DAV:changed
elements. For example, if a DAV:compare-report is applied to two
baselines, the DAV:compare-report response will contain the
versions that are selected by one baseline but not the other.
A DAV:added element identifies something that appears in a
particular contributor resource but not in the base.
A DAV:deleted element identifies something that appears in the base
resource but not in a particular contributor.
A DAV:changed element identifies information that is in both the
base and the contributor but that has changed in some way. For
example, when two baselines are being compared, a DAV:changed
element will identify a version history if the baselines select
different versions of that version history.
14.6.1 Example - DAV:compare-report
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.foo.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.foo.com/myOtherCollection
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.foo.com/myOtherCollection
http://www.foo.com/myOtherCollection/foo.html
Clemm, et al. [Page 62]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
http://www.foo.com/myCollection/bar.html
14.6.2 Example - DAV:repository-report
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://repo.webdav.org/act
14.7DAV:current-workspace-report
This report can be applied to an activity, and lists the URL of
each workspace whose DAV:current-activity-set contains the
specified activity.
14.7.1 Example - DAV:current-workspace-report
>>REQUEST
REPORT /act/fix-bug-23 HTTP/1.1
Host: repo.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Clemm, et al. [Page 63]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.webdav.org/ws/public
14.8DAV:version-selector-url-report
The request URL of this report MUST be a version URL, and the
result is a URL of a version selector whose target has the same
DAV:version-history value as that version. The request MAY specify
the URL of a workspace, in which case the version selector MUST be
a member of that workspace. If an appropriate version selector is
not visible in the specified workspace, a "404 (Not Found)"
response status is returned.
14.8.1 Example - DAV:version-selector-url-report
>>REQUEST
REPORT /his/23/rev/173 HTTP/1.1
Host: repo.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.webdav.org/ws/public
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.webdav.org/ws/public/mycollection/test.html
15 INTERNATIONALIZATION CONSIDERATIONS
To be supplied.
Clemm, et al. [Page 64]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
16 SECURITY CONSIDERATIONS
For security reasons, a LABEL request MAY report only a subset of
the labels that select this version.
17 SCALABILITY
To be supplied.
18 AUTHENTICATION
Authentication mechanisms defined in WebDAV will also apply to
WebDAV Versioning.
19 IANA CONSIDERATIONS
This document uses the namespace defined by [RFC2518] for XML
elements. All other IANA considerations mentioned in [RFC2518] are
also applicable to WebDAV Versioning.
20 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.
Clemm, et al. [Page 65]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
21 ACKNOWLEDGEMENTS
This protocol is the collaborative product of the Delta-V design
team: Jim Amsden (IBM, DeltaV Chair), Geoffrey Clemm (Rational),
Bruce Cragun (Novell), Jim Doubek (Macromedia), David Durand
(INSO), Tim Ellison (OTI), Henry Harbury (Merant), Chris Kaler
(Microsoft), Jeff McAffer (OTI), Bradley Sergeant, 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.
22 INDEX
To be supplied.
23 REFERENCES
[RFC2026] S.Bradner, "The Internet Standards Process", Harvard,
1996, .
[RFC2119] S.Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", Harvard, 1997,
.
[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", RFC 2616, U.C.Irvine, Compaq,Xerox,Microsoft, MIT/LCS,
1999, .
[Binding] J.Slein, E.Whitehead, J.Davis, G.Clemm, C.Fay,
J.Crawford, T.Chihaya, "WebDAV Bindings", Xerox, U.C.Irvine,
CourseNet, Rational, FileNet, DataChannel, 1999,
[Goals] J.Amsden, C.Kaler, J.Stracke, "Goals for Web Versioning",
IBM, Microsoft, Netscape, 1999,
Clemm, et al. [Page 66]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
24 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
25 APPENDICES
26 OVERWRITE HEADER
27 OPEN ISSUES AND PENDING CHANGES
The following list identifies open issues and pending changes
against this document:
. Add a "mandatory" attribute that says all these elements "MUST"
be recognized or the request MUST fail.
. Move the Response-Status information into the Precondition
clauses (i.e. associate a status with each precondition
indicating the status returned when that precondition is
violated). Do a consistency pass making the use of status
returns uniform.
. Add goals/motivation paragraph to the introduction (like
WebDAV/Mime/HTTP intros)
. Define marshalling of labels in XML and more on marshalling in
headers (esp. white space)
. Define labels as being case-preserving
. Add comment text for every example
Clemm, et al. [Page 67]
INTERNET-DRAFT WebDAV Versioning August 9, 2000
. Replace "server state restored" with something more
specific/constrained
. Extend the Overwrite header to take an "update" value. This
means that the Destination should be updated rather than being
deleted and a new resource created.
. Indicate that a server can place versioning metadata on either
the same server as the version selector, or on a different
server, so a client should be prepared for either.
. Mention that: if that label in a Target-Selector identifies no
version of that version selector, a 4xx (No Version Selected)
response status MUST be returned.
. Add table that indicates what headers are supported by which
methods.
Clemm, et al. [Page 68]