INTERNET-DRAFT Geoffrey Clemm, Rational Software
draft-ietf-deltav-versioning-05 Jim Amsden, IBM
Chris Kaler, Microsoft
Jim Whitehead, U.C. Irvine
Expires December 19, 2000 June 19, 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,
- Activity and workspace management,
- URL namespace versioning.
Clemm, et al. [Page 1]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Table of Contents
1 INTRODUCTION...........................................5
1.1 Relationship to DAV...................................6
1.2 Terms.................................................6
1.3 Notational Conventions................................7
2 WEBDAV VERSIONING SEMANTICS............................8
2.1 Creating and Modifying a Versioned Resource...........8
2.2 Changing the Target of a Versioned Resource...........8
2.3 Labeling a Revision...................................9
3 VERSIONING PROPERTIES BY RESOURCE TYPE.................9
3.1 Common Property Values................................9
3.1.1 boolean Syntax....................................9
3.1.2 label Syntax......................................9
3.1.3 date-time Syntax..................................9
3.1.4 href XML Element..................................9
3.2 Resource Properties..................................10
3.2.1 DAV:creator-displayname..........................10
3.2.2 DAV:comment......................................10
3.3 Versioned Resource Properties........................10
3.3.1 DAV:default-target (protected)...................10
3.3.2 DAV:auto-version.................................10
3.4 Revision Properties..................................10
3.4.1 DAV:revision (protected).........................11
3.4.2 DAV:predecessor-set (protected)..................11
3.4.3 DAV:checkin-date (protected).....................11
3.5 Working Resource Properties..........................11
3.5.1 DAV:checked-out (protected)......................11
4 VERSIONING HEADERS....................................11
4.1 Target-Selector......................................11
5 VERSIONING AND EXISTING METHODS.......................12
5.1 New Status Codes.....................................12
5.2 OPTIONS..............................................12
5.2.1 Example - OPTIONS................................12
5.3 GET..................................................13
5.4 PUT..................................................13
5.5 PROPFIND.............................................13
5.6 PROPPATCH............................................13
5.7 DELETE...............................................13
5.8 COPY.................................................13
5.9 MOVE.................................................14
5.10 LOCK...............................................14
6 VERSIONING METHODS....................................14
6.1 VERSION..............................................14
6.1.1 Example - VERSION................................15
6.2 CHECKOUT.............................................15
6.2.1 Example - CHECKOUT...............................16
6.3 CHECKIN..............................................16
Clemm, et al. [Page 2]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
6.3.1 Example - CHECKIN................................17
6.4 UNCHECKOUT...........................................17
6.4.1 Example - UNCHECKOUT.............................18
6.5 SET-TARGET...........................................18
6.5.1 Example - SET-TARGET.............................19
6.6 LABEL................................................19
6.6.1 Example - Replacing a label......................20
6.6.2 Example - Reporting labels.......................20
6.7 REPORT...............................................21
6.7.1 Example - REPORT.................................21
7 VERSIONING REPORTS....................................22
7.1 DAV:successor-report.................................22
7.1.1 Example - DAV:successor-report...................22
7.2 DAV:checkout-report..................................22
7.2.1 Example - DAV:checkout-report....................23
7.3 DAV:latest-checkin-report............................23
7.3.1 Example - DAV:latest-checkin-report..............23
7.4 DAV:revision-tree-report.............................24
7.4.1 Example - DAV:revison-tree-report................24
8 ADVANCED VERSIONING...................................25
8.1 Advanced Versioning Terms............................25
9 ADVANCED VERSIONING SEMANTICS.........................27
9.1 Workspaces...........................................27
9.2 Baselines............................................28
9.3 Activities...........................................28
9.4 Parallel Development and Merging.....................29
9.5 Versioned Collections................................29
9.6 Mutable Revisions....................................30
10 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE......30
10.1 Versioned Resource Properties......................30
10.1.1 DAV:history (protected)..........................30
10.2 Revision Properties................................31
10.2.1 DAV:history (protected)..........................31
10.2.2 DAV:activity.....................................31
10.2.3 DAV:checkout-branch..............................31
10.2.4 DAV:checkin-branch...............................31
10.2.5 DAV:mutable......................................31
10.3 Working Resource Properties........................32
10.3.1 DAV:history (protected)..........................32
10.3.2 DAV:merge-set....................................32
10.3.3 DAV:unreserved...................................32
10.3.4 DAV:predecessor-set, DAV:activity, DAV:checkout-branch,
DAV:checkin-branch, DAV:mutable.........................32
10.4 History Resource Properties........................32
10.4.1 DAV:revision-set (protected).....................32
10.4.2 DAV:initial-revision (protected).................32
10.4.3 DAV:working-resource-set (protected).............33
10.4.4 DAV:versioned-bindings (protected)...............33
10.5 Workspace Properties...............................33
10.5.1 DAV:current-activity.............................33
Clemm, et al. [Page 3]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
10.5.2 DAV:parent-workspace (protected).................33
10.5.3 DAV:child-workspace-set (protected)..............33
10.5.4 DAV:versioned-baseline (protected)...............34
10.6 Baseline Properties................................34
10.6.1 DAV:revision-set (protected).....................34
10.7 Activity Properties................................34
10.7.1 DAV:revision-set (protected).....................34
10.7.2 DAV:subactivity-set..............................34
11 ADVANCED VERSIONING HEADERS..........................35
11.1 Workspace..........................................35
12 ADVANCED VERSIONING AND EXISTING METHODS.............35
12.1 New Status Codes...................................35
12.2 OPTIONS............................................36
12.2.1 Example - OPTIONS................................36
12.3 GET................................................36
12.4 PUT................................................36
12.5 DELETE.............................................36
12.6 COPY...............................................37
12.7 MOVE...............................................37
12.8 VERSION............................................37
12.8.1 Example - VERSION................................38
12.9 CHECKOUT...........................................38
12.9.1 Example - Advanced CHECKOUT......................39
12.10 CHECKIN............................................40
12.11 UNCHECKOUT.........................................41
12.12 SET-TARGET.........................................41
13 ADVANCED VERSIONING METHODS..........................42
13.1 MKWORKSPACE........................................42
13.1.1 Example - MKWORKSPACE............................43
13.2 MERGE..............................................43
13.2.1 Example - MERGE..................................45
13.3 UNVERSION..........................................45
13.3.1 Example - UNVERSION..............................46
14 ADVANCED VERSIONING REPORTS..........................46
14.1 DAV:property-report................................46
14.1.1 Example - DAV:property-report....................47
14.2 DAV:workspace-url-report...........................48
14.2.1 Example - DAV:workspace-url-report...............48
14.3 DAV:versioned-resource-url-report..................49
14.3.1 Example - DAV:versioned-resource-url-report......49
14.4 DAV:merge-preview-report...........................49
14.4.1 Example - DAV:merge-preview-report...............50
14.5 DAV:compare-report.................................51
14.5.1 Example - DAV:compare-report.....................51
14.6 DAV:repository-report..............................52
14.6.1 Example - DAV:repository-report..................52
14.7 DAV:current-workspace-report.......................53
14.7.1 Example - DAV:current-workspace-report...........53
15 INTERNATIONALIZATION CONSIDERATIONS..................54
Clemm, et al. [Page 4]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
16 SECURITY CONSIDERATIONS..............................54
17 SCALABILITY..........................................54
18 AUTHENTICATION.......................................54
19 IANA CONSIDERATIONS..................................54
20 INTELLECTUAL PROPERTY................................54
21 ACKNOWLEDGEMENTS.....................................55
22 INDEX................................................55
23 REFERENCES...........................................55
24 AUTHORS' ADDRESSES...................................55
25 APPENDICES...........................................56
26 OVERWRITE HEADER.....................................56
27 OPEN ISSUES AND PENDING CHANGES......................56
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 revisions 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 versioned resource may support only
a subset of the advanced versioning capabilities. The advanced
versioning capabilities provided by a particular versioned 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.
Clemm, et al. [Page 5]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
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 versioned collections relies on the binding model
defined by the WebDAV binding extensions [Binding].
1.2 Terms
This draft uses the terms defined in HTTP [RFC2068] 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.
Versioned Resource
A "versioned resource" is a resource that has been put under
version control. A versioned resource MUST be "checked out" in
order to modify it. A "versioned resource URL" is a URL chosen by
the client to identify a versioned resource.
Working Resource
A "working resource" is the result of checking out a versioned
resource. A "working resource URL" is a URL chosen by the server
to identify a particular working resource of a versioned resource.
Revision
A "revision" is a resource created by "checking in" a working
resource. The content and properties of a revision are a copy of
the current content and properties of the working resource.
A "revision URL" is a URL chosen by the server to identify a
particular revision of a versioned resource.
Default Target
Unless a Target-Selector header is specified, the content and
properties displayed by a versioned resource are those of a
particular revision of the versioned resource. This revision is
called the "default target" of the versioned resource.
Revision Label
A "revision label" is a string chosen by a client to identify a
particular revision of a versioned resource.
Initial Revision
An "initial revision" is the first revision of a versioned
resource.
Predecessor, Successor, Ancestor, Descendent
Clemm, et al. [Page 6]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
A "predecessor" of a revision is a previous revision that was
checked out or merged to create the revision. When a revision is
related to another revision by one or more predecessor relations,
it is called an "ancestor" of that revision.
The inverse of the predecessor and ancestor relations are the
"successor" and "descendent" 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 descendent of X.
The following diagram illustrates several of the previous
definitions.
History of Foo.html
+----+
Initial Revision ---> | V1 |
+----+
| ^
| |
+----+ |
Label ------> "beta1" | V2 | | Ancestor
+----+ |
/ \ |
/ \ |
+----+ +----+
| V3 | | V4 |
+----+ +----+
^ | | |
Predecessor | | | |
| +----+ +----+ |
| V5 | | V6 | | Descendent
+----+ +----+ |
| \ / |
Successor | \ / v
v +----+
| V7 |
+----+
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 7]
INTERNET-DRAFT WebDAV Versioning June 15, 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 Versioned Resource
In order to track the history of the content and properties of a
versionable resource, it can be put under version control. In
order to modify a versioned resource, it must first be checked out.
When a versioned resource is checked out, a working resource for
that versioned resource is created. The state of the working
resource can then be modified by setting its content or properties
any number of times. When the working resource is in a state that
should be retained, it is checked in to create a new revision in
the versioned resource history. The revision that was checked out
is remembered as the predecessor of the new revision. Unless the
server supports mutable revisions, the content and properties of a
revision cannot be modified, but instead, changes appear as
descendents of that revision.
The following diagram illustrates the checkout/checkin process.
===CHECKOUT==> ===CHECKIN==>
Foo.html | Foo.html | Foo.html
History | History | History
| |
+----+ | +----+ | +----+
| V1 | | | V1 | | | V1 |
+----+ | +----+ | +----+
| | | | |
| | | | |
+----+ | +----+ | +----+
| V2 | | | V2 | | | V2 |
+----+ | +----+ | +----+
| | | |
| | | |
| +----+ | +----+
| | WR | | | V3 |
| +----+ | +----+
2.2 Changing the Target of a Versioned Resource
Another way to modify the state of a versioned resource is to use a
SET-TARGET request to select another revision to be the default
target of that versioned resource. The SET-TARGET request will
Clemm, et al. [Page 8]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
cause the versioned resource to display the content and properties
of the specified revision.
2.3 Labeling a Revision
At any time, a revision can be given a client assigned label in
order to provide a meaningful name for that revision. A given
revision label can be assigned to at most one revision of a given
versioned resource, but may be reassigned to another revision at
any time. Note that although a given label cannot be applied to
two revisions from the same versioned resource, the same label can
be given to two revisions from different versioned resources.
For certain methods, a Target-Selector request header can be used
to make a versioned resource display the content and properties of
the revision selected by the Target-Selector label, instead of
those of the default target of that versioned resource.
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
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.4href XML Element
The href XML element is defined in section 12.3 of [RFC2518].
Clemm, et al. [Page 9]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
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 revision can be used to indicate who created that
revision.
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
revision can be used to indicate why that revision was created.
3.3 Versioned Resource Properties
WebDAV versioning introduces the following properties for a
versioned resource.
3.3.1DAV:default-target (protected)
This property contains the revision URL of the revision that is the
default target of this versioned resource when no Target-Selector
header is specified.
This property can be modified by the SET-TARGET method.
3.3.2DAV:auto-version
When the DAV:auto-version property of a versioned resource is set,
a request that attempts to modify that versioned resource (such as
PUT/PROPPATCH) is automatically preceded by a CHECKOUT and
automatically followed by a CHECKIN. This allows a versioning-
unaware client to add revisions to the history of a versioned
resource.
PCDATA value: boolean
3.4 Revision Properties
WebDAV versioning introduces the following properties for a
revision.
Clemm, et al. [Page 10]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
3.4.1DAV:revision (protected)
This property contains the revision URL for this revision.
3.4.2DAV:predecessor-set (protected)
This property contains a revision URL for each predecessor of this
revision. Except for the initial revision, which has no
predecessors, there is either the single predecessor that was
checked out to create the revision, or there are the multiple
predecessors that were merged to create the revision.
3.4.3DAV:checkin-date (protected)
This property contains the date when the revision selected by the
versioned resource 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.5 Working Resource Properties
WebDAV versioning introduces the following properties for a working
resource.
3.5.1DAV:checked-out (protected)
This property contains the revision URL of the revision 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" ":" *LWS label
An example of a Target-Selector header is:
Target-Selector: released
When a method supports the Target-Selector header, if the request-
URL identifies a versioned resource and a label is specified in a
Target-Selector request header, the request MUST act as if the
state of the versioned resource was a copy of the revision
identified by that label. If that label identifies no revision of
Clemm, et al. [Page 11]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
that versioned resource, a 4xx (No Revision Selected) response
status MUST be returned.
A Target-Selector header has no affect on a request-URL that does
not identify a versioned resource. In particular, it has no affect
on a revision URL or a working resource 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 request that includes a Target-Selector header, if the
request method supports a Target-Selector header and if the
request-URL identifies a versioned resource, the request MUST act
as if the state of the versioned resource was a copy of the
revision selected by the Target-Selector header.
For any method that updates a resource (e.g. PUT, PROPPATCH), when
that method is applied to a versioned resource, the method MUST
fail unless the versioned resource has a DAV:auto-version property.
If the versioned resource has a DAV:auto-version property, the
versioned resource 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 add a
revision to the history of a versioned resource. 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 Revision Selected): The label specified in a Target-
Selector header selects no revision of this versioned resource.
4xx (Cannot modify content or property of a revision)
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
HTTP/1.1 200 OK
Clemm, et al. [Page 12]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
DAV: 1, 2, core-versioning
Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, VERSION
5.3 GET
Additional Marshalling:
A Target-Selector request header MAY be specified.
5.4 PUT
Additional Preconditions:
If the request URL identifies a versioned resource, the PUT MUST
fail unless DAV:auto-version is set for that versioned resource.
If the request URL identifies a revision, the PUT MUST fail.
5.5 PROPFIND
Additional Marshalling:
A Target-Selector request header MAY be specified.
5.6 PROPPATCH
Additional Preconditions:
If the request URL identifies a versioned resource, an attempt to
modify a dead property MUST fail unless DAV:auto-version is set for
that versioned resource.
If the request-URL identifies a revision, the PROPPATCH MUST fail.
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 revision 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.
Clemm, et al. [Page 13]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Additional Postconditions:
If the request-URL identifies a versioned resource or a revision,
it is server defined whether the new resource created at the
Destination is a versioned or versionable resource.
5.9 MOVE
Additional Preconditions:
If the request-URL is a revision 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
A VERSION request can be applied to a versionable resource to put
it under version control. The initial version of the versioned
resource captures the current state of the versionable resource,
and the initial DAV:default-target of the versioned resource is the
initial revision.
A VERSION response MUST NOT be cached. If a VERSION request fails,
the server state preceding the request MUST be restored.
Preconditions:
The request-URL MUST identify a versionable resource or a versioned
resource.
Return Status Codes:
200 (OK): The resource is under version control.
405 (Method Not Allowed): The request-URL does not identify a
versionable resource.
Postconditions:
If the request-URL identified a versioned resource at the time of
the request, the VERSION request MUST NOT change the state of that
versioned resource.
If the request-URL identified a versionable resource at the time of
the request, a new versioned resource is created at the request-
URL, and a copy of the versionable resource is made the initial
revision of the new versioned resource. The DAV:revision of the
initial revision is a revision URL that identifies this revision,
the DAV:predecessor-set is empty, and the DAV:checkin-date is the
Clemm, et al. [Page 14]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
current date on the server. The DAV:default-target of the new
versioned resource is the initial revision.
6.1.1Example - VERSION
>>REQUEST
VERSION /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
6.2 CHECKOUT
A CHECKOUT request can be applied to a versioned resource to create
a new working resource. The content and properties of the working
resource are a copy of a revision selected by the CHECKOUT request.
If a revision is specified in the CHECKOUT request body, that is
the selected revision; otherwise, if a revision is selected by a
Target-Selector request header, that is the selected revision;
otherwise, the default target of the versioned resource is the
selected revision.
A CHECKOUT response MUST NOT be cached. If a CHECKOUT request
fails, the server state preceding the request MUST be restored.
Marshalling:
If a request body is included, it MUST be a DAV:checkout XML
element.
A Target-Selector request header MAY be specified.
A Location response header MUST be returned.
Preconditions:
The request-URL MUST identify a versioned resource.
If a revision is specified in the CHECKOUT request body, it MUST be
a revision of the versioned resource identified by the request-URL.
If a label is specified in a Target-Selector header, it MUST select
a revision of the versioned resource identified by the request-URL.
If the versioned resource is locked, the lock token MUST be
specified in the CHECKOUT request.
Response Status Codes:
201 (Created): The server created a new working resource.
Clemm, et al. [Page 15]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
405 (Method Not Allowed): The request-URL did not identify a
versioned resource.
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 revision. The content and other properties of the
working resource are the same as the content and properties of the
selected revision, except that it has no DAV:revision,
DAV:predecessor-set, or DAV:checkin-date property.
6.2.1Example - CHECKOUT
>>REQUEST
CHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>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 revision that is a copy of the working resource.
A CHECKIN response MUST NOT be cached. 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.
If DAV:keep-checked-out is specified, the versioned resource is
immediately checked out again.
The request MAY include a Target-Selector header.
The response MUST include a Location header.
Preconditions:
The request-URL MUST identify a working resource.
If the versioned resource is write-locked, then the appropriate
lock token MUST be included in the request.
Response Status Codes:
201 (Created): The revision was successfully created.
Clemm, et al. [Page 16]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
405 (Method Not Allowed): The request-URL did not identify a
versioned resource.
409 (Conflict): A precondition was violated.
Postconditions:
A new revision of the versioned resource is created.
The DAV:revision of the new revision is set to a server-defined
URL.
The DAV:predecessor-set of the new revision is set to the
DAV:checked-out property of the working resource.
The DAV:checkin-date of the new revision is set to the current date
on the server.
The content and dead properties of the working resource are copied
into the new revision.
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 revision URL of
the new revision.
The DAV:default-target of the versioned resource is set to contain
the revision URL of the new revision.
The revision URL for the new revision 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.
An UNCHECKOUT response MUST NOT be cached. If an UNCHECKOUT
request fails, the server state preceding the request MUST be
restored.
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.
Clemm, et al. [Page 17]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Response Status Codes:
200 (OK): The checkout was successfully cancelled.
405 (Method Not Allowed): The URL did not identify a working
resource.
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 versioned resource to
change the default target of that versioned resource.
A SET-TARGET response MUST NOT be cached.
Marshalling:
The SET-TARGET request body MUST be a DAV:set-target XML element.
A Depth header MAY be specified for a SET-TARGET request.
Preconditions:
The request-URL MUST identify a versioned resource.
The DAV:set-target value MUST specify either a label that selects a
revision of the request versioned resource or a revision URL that
identifies a revision of the versioned resource.
If the request-URL is write-locked, the SET-TARGET request MUST
include the appropriate lock token.
Response Status Codes:
200 (OK): The versioned resource 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
versioned resource.
Postconditions:
Clemm, et al. [Page 18]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
The DAV:default-target of the versioned resource MUST be set to the
specified revision.
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 revision to modify or list the
labels on that revision. If a LABEL request is applied to a
versioned resource, the operation is applied to the default target
of that versioned resource unless a Target-Selector header is
specified.
A LABEL response MUST NOT be cached.
Marshalling:
The request body MUST be a DAV:label element.
The request MAY include a Target-Selector header.
If the request body contains DAV:report, the response body MUST be
a DAV:label-name-set element.
PCDATA value: label-name
Preconditions:
The request-URL MUST identify a revision or a versioned resource.
If DAV:add is specified, the specified label MUST NOT currently
select a revision of that versioned resource.
Clemm, et al. [Page 19]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
If DAV:remove is specified, the specified label MUST select that
revision of the versioned resource.
Response Status Codes:
200 (OK): The label add, replace, remove, or report was successful.
400 (Bad Request): The body of the request was not valid.
405 (Method Not Allowed): The request-URL did not identify a
revision or a versioned resource.
Postconditions:
If DAV:add or DAV:replace is specified, the specified label selects
the revision.
If DAV:remove is specified, the specified label no longer selects
any revision of the versioned resource.
If DAV:report is specified, the labels that select the specified
revision are listed in a DAV:label-name-set element in the response
body.
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
6.6.2Example - Reporting labels
>>REQUEST
LABEL /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
Clemm, et al. [Page 20]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
stable
release-2.0
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 21]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
7 VERSIONING REPORTS
Versioning introduces the following reports (the REPORT method is
defined in section 6.6.2).
7.1 DAV:successor-report
This report can be applied to a revision or a versioned resource,
and lists the revision URL of each revision whose DAV:predecessor-
set contains the selected revision.
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 revision or a versioned resource,
and lists all working resources whose DAV:checked-out property
identifies the selected revision.
The request MAY include a Target-Selector header.
Clemm, et al. [Page 22]
INTERNET-DRAFT WebDAV Versioning June 15, 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 versioned resource, and returns the
revision URL of the revision of that versioned resource with the
latest DAV:checkin-time. If the versioned resource revisions do not
have a DAV:checkin-time property, no revision will be identified.
If multiple revisions contain the latest DAV:checkin-time, all
those revisions will be identified.
The response body of a DAV:latest-checkin-report MUST be a
DAV:revision-set 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 23]
INTERNET-DRAFT WebDAV Versioning June 15, 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:revision-tree-report
The DAV:revision-tree-report describes all the revisions of a
versioned resource in the form of a nested tree of revisions.
The response body of a DAV:revision-tree-report MUST be a
DAV:revision-tree element.
A DAV:revision tree element contains a revision URL followed by the
DAV:creator-displayname, DAV:comment, DAV:predecessor-set, and
DAV:checkin-date properties of that revision, the DAV:label-name-
set resulting from a LABEL report for that revision, the
DAV:working-resource-set resulting from a DAV:checkout-report for
that revision, and a DAV:revision tree for each successor of that
revision.
A server MAY omit all elements other than DAV:revision for a
revision that has previously appeared in the DAV:revision-tree
element. This can provide significant space savings when a
revision has multiple predecessors.
7.4.1Example - DAV:revison-tree-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
Clemm, et al. [Page 24]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
http://repo.webdav.org/his/23/rev/1
Fred
get it started
http://repo.webdav.org/his/23/rev/2
Fred
Fix the spelling
http://repo.webdav.org/his/23/rev/1
http://repo.webdav.org/his/23/rev/2.1.1
Sally
Translate into French
http://repo.webdav.org/his/23/rev/1
8 ADVANCED VERSIONING
8.1 Advanced Versioning Terms
History
A "history" is a resource that provides access to the metadata
associated with a versioned resource, such as the list of revisions
and working resources for that versioned resource. A "history URL"
is a URL chosen by the server to identify a history resource.
Workspace
A "workspace " is a collection that contains a set of related
versionable resources, versioned resources, and working resources.
Baseline
A baseline is a resource associated with a workspace that captures
the default revision of each versioned resource that is a member of
that workspace.
The following diagram illustrates a baseline B1.1 of the workspace
/WS that selects revision V1 of /WS/A.html, revision V3 of
/WS/X/B.html, and revision V5 of /WS/X/C.html.
Clemm, et al. [Page 25]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
/WS/A.html /WS/X/B.html /WS/X/C.html
History History History
+----+
| V2 |
+----+
|
|
+-------------------|-------------------------------+
| | |
| +----+ +----+ +----+ Baseline |
| | V1 | | V3 | | V5 | B1.1 |
| +----+ +----+ +----+ |
| | | |
+-------------------|------------|------------------+
| |
| |
+----+ +----+
| V4 | | V6 |
+----+ +----+
Merging
"Merging" is a mechanism for updating a workspace with a specified
set of revisions. For each revision to be merged, the versioned
resource in the workspace whose history contains that revision is
identified. If the specified revision is a descendent of the
default target of the identified versioned resource, the merge
changes the default target of the versioned resource to be the
specified revision. If the specified revision is an ancestor of
the default target of the identified versioned resource, the merge
leaves that versioned resource unchanged. If the specified
revision is neither a descendent nor an ancestor of the default
target of the identified versioned resource, the merge checks out
the versioned resource, and the client is then responsible for
updating the resulting working resource so that its state
corresponds to the logical merge of the specified revision with the
checked out revision.
Activity
An "activity" is a non-versionable resource that selects a set of
revisions that are on a single "line of descent", where a line of
descent is a sequence of revisions connected by successor
relationships. If an activity selects revisions from multiple
history resources, the revisions selected in each history resource
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. Revision V5 is the
latest revision of Foo.html selected by activity Act-2, and
revision V8 is the latest revision of Bar.html selected by activity
Act-2.
Clemm, et al. [Page 26]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Foo.html History Bar.html History
+----+ +----+
Act-1| V1 | Act-1| V6 |
+----+ +----+
| |
| |
+----+ +----+
Act-1| V2 | Act-2| V7 |
+----+ +----+
/ \ |
/ \ |
+----+ +----+ +----+
Act-1| V3 | Act-2| V4 | Act-2| V8 |
+----+ +----+ +----+
| |
| |
+----+ +----+
Act-2| V5 | Act-3| V9 |
+----+ +----+
Branch
When a second successor is added to a revision of a versioned
resource, this creates a "branch" in the history of the versioned
resource.
Versioned Collection
A "versioned collection" is a versioned resource that tracks
properties and bindings of a collection.
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, versioned resources, and working resources. When a
versioned resource 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 versioned resource that selects the new revision as
its default target.
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.
Clemm, et al. [Page 27]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Alternatively, a workspace can be initialized by the state of an
existing workspace. In this case, a versioned resource is created
in the new workspace corresponding to each versioned resource in
the existing workspace, where corresponding versioned resources in
different workspaces will share the same history resource.
In order to ensure unambiguous merging and baselining semantics, a
workspace may contain at most one versioned resources for a given
history resource (although a server may support multiple bindings
in a workspace to the same versioned resource). In order to expose
multiple views of a set of a set of related versioned resources in
the URL namespace, multiple workspaces must be used. In order to
make a change made to a versioned resource in one workspace visible
in another workspace, that versioned resource must be checked in,
and then the corresponding versioned resource in the other
workspace can be updated to select the new revision.
9.2 Baselines
A workspace that contains a large number of versioned resources 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 versioned
resource revisions, 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
A common problem is that although a versioned resource may need to
have separate lines of development in separate projects, no
branching is to be permitted within a project. An "activity"
resource provides the mechanism for addressing this problem. When
a versioned resource 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 versioned resource
revisions associated with an activity are on a single line of
descent in the history of that versioned resource. If a project
identifies an activity that is to be associated with all revisions
created by that project, then all changes made in that project will
be on a single line of descent.
Another use for activities is to perform several different logical
changes in a single workspace, and then selectively merge a subset
of those logical changes to other workspaces. Each activity can be
used to represents a single logical change, although many resources
might need to be modified to effect that single logical change.
When a versioned resource is checked out, the author specifies
which activity should be associated with a new revision that will
be created when that versioned resource is checked in. It is then
possible to select a subset of the logical changes for merging into
Clemm, et al. [Page 28]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
another workspace, by specifying the appropriate activities in a
MERGE request.
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 revisions as
the default targets of the corresponding versioned resources in the
author's workspace, since this would hide any changes made to those
versioned resources in the author's workspace. Instead, the
revisions created in another workspace should be "merged" into the
author's workspace.
The revision history of a versioned resource provides the
information needed to determine what should be the result of the
merge. In particular, the merge should select whichever revision
is later in the line of descent from the initial revision. In case
the revisions to be merged are on different lines of descent
(neither revision is an ancestor of the other), neither revision
should be selected, but instead, a new revision should be created
that contains the logical merge of the content and properties of
those revisions. The MERGE request can be used to check out each
versioned resource with such a conflict, and set the DAV:merge-set
property of each new working resource to identify the revisions to
be merged. The author is responsible for modifying the content of
a working resource so that it represents the logical merge of those
revisions, and then adding the revisions 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 Versioned Collections
The state of a collection consists of a set of properties and a set
of named bindings to the internal members of that collection. A
collection in a workspace can be put under version control so that
the properties and bindings can be tracked by the revisions of the
versioned collection.
Normally, only some of the bindings in a versioned collection
should be stored in the history of that collection. For example,
it is often useful to temporarily store a dynamically derived
resource (such as a particular presentation of a compound document)
in the same collection as one of the source resources used to
produce it, but the binding to that derived resource should not be
stored in the collection history since it needs to be recomputed on
demand. Another example would be a lock null resource created to
reserve a name in a collection. A lock null member of a collection
should be a temporary resource that is removed when its timeout
Clemm, et al. [Page 29]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
expires or when it is explicitly unlocked, and should not be stored
persistently in a revision of that collection.
A binding that is stored in the history of a versioned collection
is called a "public" binding; a binding that is not stored in the
history is called a "private" binding. A simple strategy for
defining what bindings are public is to define bindings to
versioned resources to be public and to define all other bindings
as private. This provides an intuitive model (you put a binding to
a particular internal member under version control by versioning
that member) and a simple implementation (a binding to a versioned
resource can be stored as a binding name and a history URL for that
versioned resource).
When a SET-TARGET selects a new revision for a versioned
collection, the bindings from the new revision replace the bindings
from the previously selected revision. If one of the bindings in
the new revision has the same name as an existing private binding
in that versioned collection, that versioned collection will have
two bindings (one private, one public) with the same name. In this
case, the private binding takes precedence over the public binding,
and the private binding is said to "eclipse" the public binding.
When the private binding is removed (e.g. by a DELETE or a MOVE),
the public binding will be exposed.
9.6 Mutable Revisions
Normally, a revision cannot be changed and provides a reliable
environment for state recovery, change tracking, stable workspaces,
and merging. If a server supports mutable revisions, the client may
request that a checkin should overwrite the revision that was
checked out, instead of creating a new revision. This can be an
advantage when a simple history is more important than the benefits
provided by an immutable revision history, but does introduce a
significant performance penalty in distributed environments,
because the state of a mutable revision 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.1Versioned Resource Properties
WebDAV advanced versioning introduces the following properties for
a versioned resource.
10.1.1 DAV:history (protected)
This property contains a history URL for the history resource for
this versioned resource.
Clemm, et al. [Page 30]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
10.2Revision Properties
WebDAV advanced versioning introduces the following properties for
a revision:
10.2.1 DAV:history (protected)
This property contains a history URL for the history resource
associated with this revision.
10.2.2 DAV:activity
This property contains a URL for the activity that indicates the
line of descent for this revision.
10.2.3 DAV:checkout-branch
This property controls the behavior of CHECKOUT when a revision
already is checked out or has a successor. If the DAV:checkout-
branch of a revision is DAV:forbidden, a CHECKOUT request MUST fail
if it would result in that revision appearing in the
DAV:predecessor-set or DAV:checked-out property of more than one
revision or working resource. If DAV:checkout-branch is
DAV:discouraged, such a CHECKOUT request MUST fail unless
DAV:branch-ok is specified in the CHECKOUT request body.
10.2.4 DAV:checkin-branch
This property controls the behavior of CHECKIN when a revision
already has a successor. If the DAV:checkin-branch of a revision
is DAV:forbidden, a CHECKIN request MUST fail if it would result in
that revision appearing in the DAV:predecessor-set of more than one
revision. If DAV:checkin-branch is DAV:discouraged, such a
CHECKIN request MUST fail unless DAV:branch-ok is specified in the
CHECKIN request body.
10.2.5 DAV:mutable
This property indicates whether the revision can be updated by a
CHECKIN with DAV:overwrite.
Clemm, et al. [Page 31]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
PCDATA value: boolean
10.3Working Resource Properties
WebDAV advanced versioning introduces the following properties for
a working resource:
10.3.1 DAV:history (protected)
This property contains a history URL for the history resource
associated with this working resource.
10.3.2 DAV:merge-set
The DAV:merge-set of a working resource contains a revision URL for
each revision that is to be merged into this working resource.
10.3.3 DAV:unreserved
This property indicates whether other working resources associated
with the history resource of this working resource can have the
same DAV:activity property as this working resource.
PCDATA value: boolean
10.3.4 DAV:predecessor-set, DAV:activity, DAV:checkout-branch,
DAV:checkin-branch, DAV:mutable
These properties determine the values of the corresponding
properties of the revision that results from checking in this
working resource.
10.4History Resource Properties
The DAV:resourcetype of a history resource MUST be DAV:history.
WebDAV advanced versioning introduces the following properties for
a history resource:
10.4.1 DAV:revision-set (protected)
This property contains a revision URL for each revision of this
history resource.
10.4.2 DAV:initial-revision (protected)
This property contains a revision URL for the initial revision of
this history resource.
Clemm, et al. [Page 32]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
10.4.3 DAV:working-resource-set (protected)
This property contains a URL for each working resource whose
DAV:history property identifies this history resource.
10.4.4 DAV:versioned-bindings (protected)
This property MUST appear on the history resource for a versioned
collection, and indicates whether bindings to versioned resources
are being tracked by that history resource. If DAV:versioned-
bindings is "F", only properties of the versioned collection are
captured in a versioned collection revision. If DAV:versioned-
bindings is "T", both properties and bindings to versioned
resources are captured in a versioned collection revision. In
particular, each versioned resource binding in the versioned
collection is captured as a history resource binding in the
collection revision.
PCDATA value: boolean
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
This property identifies the activity that is currently 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 will be used. This allows an activity-
unaware client to update a workspace in which activity tracking is
required.
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.
Clemm, et al. [Page 33]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
10.5.4 DAV:versioned-baseline (protected)
If baselines are supported for a workspace, the workspace MUST have
a DAV:versioned-baseline property. This property contains the URL
of a versioned baseline that is used to track baselines of that
workspace. When the versioned baseline of a workspace is checked
out, the resulting working baseline tracks the default target of
each versioned resources that is a member of the workspace. When
the working baseline is checked in, its state is captured by a new
baseline of the versioned baseline.
10.6Baseline Properties
The DAV:resourcetype of a baseline MUST be DAV:baseline. WebDAV
advanced versioning introduces the following properties for a
baseline.
10.6.1 DAV:revision-set (protected)
This property contains a revision URL for each revision selected by
the baseline. At most one revision of a given versioned resource
can be selected by a baseline's DAV:revision-set property.
10.7Activity Properties
The DAV:resourcetype of an activity MUST be DAV:activity. WebDAV
advanced versioning introduces the following properties for an
activity:
10.7.1 DAV:revision-set (protected)
This property contains a revision URL for each revision whose
DAV:activity property identifies this activity. Multiple revisions
of a single history resource can be selected by an activity's
DAV:revision-set property, but all revisions of a given history
resource must be on a single line of descent from the initial
revision of that history resource.
10.7.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:revision-set is extended by the DAV:revision-
set of each activity specified in the DAV:subactivity-set. In
particular, the revisions in this extended set MUST be on a single
line of descent, and when an activity selects a revision for
merging into a workspace, the latest revision in this extended set
is the one that will be merged.
Clemm, et al. [Page 34]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
11 ADVANCED VERSIONING HEADERS
11.1Workspace
The following defines the BNF for the Workspace header:
Workspace := "Workspace" ":" *LWS URL
A workspace header provides a convenient mechanism for making
"workspace relative" requests. The URL specified in the Workspace
header is concatenated with the request-URL to form the effective
request-URL, and with each request header URL to form the effective
request header URL. 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
A server MUST return a Vary header containing "Workspace" in a
response to a cacheable request (e.g. GET, PROPFIND) that includes
a Workspace header.
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 versioned collection
and when the binding is to a versioned resource, the method MUST
fail unless the versioned collection has a DAV:auto-version
property. If the versioned collection has a DAV:auto-version
property, the versioned collection 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 revision to the versioned collection
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:branch-ok, revision already
checked out)
4xx (Cannot CHECKOUT, revision already checked out)
Clemm, et al. [Page 35]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
4xx (Cannot CHECKIN without DAV:branch-ok, revision already has a
successor)
4xx (Cannot CHECKIN, revision already has a successor)
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:
"workspace", "baseline", "merge", "activity", "versioned-
collection", and "mutable-revision".
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 history resource, an activity, or a
baseline, the result is undefined.
12.4PUT
Additional Preconditions:
If the request URL identifies a history resource, an activity, or a
baseline, the result is undefined.
12.5DELETE
Additional Preconditions:
If the request-URL identifies a versioned resource, the DELETE MUST
fail when the collection containing the versioned resource is a
versioned collection, unless DAV:auto-version is set for that
versioned collection.
Additional Postconditions:
If the request-URL identifies a history resource, the result is
undefined.
Clemm, et al. [Page 36]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
12.6COPY
Additional Preconditions:
If the request-URL identifies a history resource, the request MUST
fail. In order to create another history resource with a similar
history, the appropriate sequence of VERSION, CHECKOUT, PUT,
PROPPATCH, and CHECKIN requests must be made.
12.7MOVE
Additional Preconditions:
If the request-URL identifies a versioned resource, the request
MUST fail when the collection containing the versioned resource is
a versioned collection, unless DAV:auto-version is set for that
versioned collection.
If the request-URL identifies a versioned resource, the request
MUST fail when the collection containing the destination is a
versioned collection, unless DAV:auto-version is set for that
versioned collection.
If the request-URL identifies a history resource, an activity, or a
baseline, the request MUST fail.
12.8VERSION
If a history resource is specified in the request body, the
request-URL MUST identify a null resource, and a new versioned
resource associated with the specified history resource is created
at the request-URL. If no history resource is specified, a new
history resource is allocated for the new versioned resource at a
server-defined location.
Additional Marshalling:
If a request body is included, it MUST be a DAV:version XML
element.
Additional Preconditions:
If the DAV:version request body element is not empty, the DAV:href
MUST identify a history resource.
If the DAV:version request body identifies a history resource, and
if the request-URL is a member of a workspace, then there MUST NOT
be another member of that workspace whose DAV:history property
specifies that history resource.
If the collection containing the request-URL is a versioned
collection, the request MUST fail unless DAV:auto-version is set
for that versioned collection.
Additional Return Status Codes:
201 (Created): The server created a new versioned resource.
Clemm, et al. [Page 37]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Additional Postconditions:
If no history resource is specified in the request body, a new
history resource is created at a server-defined URL and a copy of
the versionable resource is made the initial revision of that
history resource. If the versioned resource is a member of a
workspace, the DAV:activity of the initial revision is the
DAV:current-activity of that workspace.
The DAV:history of the new versioned resource identifies the
specified history resource.
The DAV:default-target of the new versioned resource identifies the
initial revision of the history resource.
12.8.1 Example - VERSION
>>REQUEST
VERSION /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://repo.webdav.org/his/12
>>RESPONSE
HTTP/1.1 201 Created
12.9CHECKOUT
When activities are supported, a CHECKOUT request MAY specify a
request activity in the request body. If the versioned resource is
a member of a workspace, and no activity is specified in the
request body, the DAV:current-activity of the workspace is the
request activity.
Additional Marshalling:
Additional Preconditions:
If there is a request activity, the selected revision MUST be a
descendent of all other revisions of that versioned resource that
have that activity as their DAV:activity.
Clemm, et al. [Page 38]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Unless DAV:unreserved is specified, all other working resources of
that history resource whose DAV:activity identifies the request
activity MUST have a DAV:unreserved property whose value is "T".
If the DAV:checkout-branch property of the revision being checked
out is DAV:forbidden, the request MUST fail if a revision contains
that revision in its DAV:predecessor-set or if a working resource
contains that revision in its DAV:checkout property. If the value
is DAV:discouraged, such a request MUST fail unless DAV:branch-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 history resource.
If the versioned resource was a member of a workspace, the working
resource URL returned in the Location response header MUST be the
URL that identified the versioned resource.
If the versioned resource was a versioned baseline, the working
resource URL returned in the Location response header MUST be the
request-URL.
If the versioned resource was a collection, the new working
collection MUST contain bindings to all members of that versioned
collection.
The DAV:predecessor-set property of the new working resource is
initialized to be the same revision as the DAV:checked-out
property.
The DAV:activity of the new working resource is set as follows: if
DAV:new is specified as the DAV:activity in the request body, then
a new activity created by the server is used; otherwise, if an
activity is specified in the request body, then that activity is
used; otherwise, if the versioned resource is a member of a
workspace and the DAV:current-activity of the workspace is set,
then that activity is used; otherwise, the DAV:activity of the
checked out revision 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.9.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
Clemm, et al. [Page 39]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
>>RESPONSE
HTTP/1.1 201 Created
Location: http://www.webdav.org/ws/public/foo.html
12.10 CHECKIN
Normally, a CHECKIN request will create a new revision. If a
server supports mutable revisions and if DAV:overwrite is
specified, then instead of creating a new revision, CHECKIN will
overwrite the value of the revision identified by the DAV:checked-
out property of the working resource.
Additional Marshalling:
Additional Preconditions:
Each revision in DAV:predecessor-set of the working resource MUST
have the same DAV:history value as the working resource.
Any revision of that versioned resource that has the same
DAV:activity value MUST be an ancestor of the working resource.
The DAV:merge-set of the working resource MUST be empty.
A CHECKIN request MUST fail if it would cause a revision whose
DAV:checkin-branch is DAV:forbidden to appear in the
DAV:predecessor-set of more than one revision. If DAV:checkin-
branch is DAV:discouraged, such a CHECKIN request MUST fail unless
DAV:branch-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 revision is "T".
Additional Postconditions:
If the DAV:predecessor-set property of the working resource is non-
empty, the DAV:predecessor-set of the new revision is set to that
value instead of the value of the DAV:checked-out property.
The DAV:history of the new revision is the DAV:history of the
working resource.
The DAV:revision-set of the history resource is updated to include
the new revision.
If the working resource was a member of a workspace, it is replaced
by a versioned resource whose DAV:default-target specifies the new
revision created by the CHECKIN.
Clemm, et al. [Page 40]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
If the working resource was a collection, the bindings of the
working collection are moved to the versioned collection that
replaces it.
If the working resource was a collection, and if DAV:versioned-
bindings is set for the history resource associated with that
working collection, and if DAV:keep-checked-out is not specified,
then the new collection revision contains bindings to the history
resources of the versioned resource 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 history resource.
The DAV:activity of the new revision is set as follows: if DAV:new
is specified as the DAV:activity in the request body, then a new
activity created by the server is used; otherwise, if an activity
is specified in the request body, then that activity is used;
otherwise, if the working resource has a DAV:activity property,
that activity is used; otherwise, if the working resource is a
member of a workspace and the DAV:current-activity of the workspace
is set, then that activity is used; otherwise, the DAV:activity of
the checked out revision is used.
If an activity is specified in the DAV:activity property of the new
revision, a revision URL for the new revision is added to the
DAV:revision-set property of that activity.
If DAV:hidden is specified, the DAV:default-target of the versioned
resource is not changed by the CHECKIN request.
If DAV:overwrite is specified, a new revision is not created, but
instead the content and properties of the working resource replace
those of the DAV:checked-out revision.
12.11 UNCHECKOUT
Additional Postconditions:
The URL of the working resource is removed from the DAV:working-
resource-set property of its history resource.
If the working resource is a member of a workspace, it is replaced
by a versioned resource whose DAV:history is that of the working
resource, and whose DAV:default-target is the DAV:checked-out
revision of the working resource.
.If the request-URL identifies a working collection, then the
private bindings of the working collection are moved to the
versioned collection that replaces it.
12.12 SET-TARGET
A SET-TARGET request can be applied to a workspace to cause every
revision in a specified baseline to be selected by the
corresponding versioned resource in that workspace.
Clemm, et al. [Page 41]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Additional Marshalling:
Additional Preconditions:
If a DAV:baseline element is specified in the request body, the
request-URL MUST identify a workspace.
Additional Postconditions:
If the request-URL identifies a workspace and the request body
specifies a baseline, then for each versioned resource in that
workspace that is associated with the history resource of a
revision selected by that baseline, the DAV:default target of that
versioned resource is set to be the revision selected by the
baseline.
If the SET-TARGET request modifies the DAV:default-target of a
versioned collection whose history resource has a DAV:versioned-
bindings value of "T", then all bindings in that versioned
collection to versioned resources are replaced by the bindings
specified by the new default target. In particular, bindings are
deleted for versioned resources whose history resources are not a
member of the new target revision, bindings are renamed for
versioned resources whose history resources have been renamed in
the new target revision, and bindings are created to versioned
resources whose history resources have been added to the new target
revision. If a new binding identifies a versioned resource that
was not previously a member of that workspace, then a new versioned
resource is created whose DAV:default-target is the initial
revision of that history resource.
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.6).
The MKWORKSPACE request body can be used to initialize the
workspace with the versioned resources from an existing.
A MKWORKSPACE response MUST NOT be cached. If a MKWORKSPACE
request fails, the server state preceding the request MUST be
restored.
Marshalling:
If a request body is included, it MUST be a DAV:mkworkspace XML
element.
Preconditions:
Clemm, et al. [Page 42]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
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.
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
versioned resource that is a member of the parent workspace, a new
versioned resource with the same DAV:history property will be
created in the new workspace. The new versioned resource will have
the same name relative to the new workspace as the existing
versioned resource has relative to the parent workspace. Any
collections that are needed in the new workspace to provide the
appropriate name for a versioned resource 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.2MERGE
A MERGE request performs the logical merge of one or more revisions
(the "request revisions") into a specified workspace (the
"destination workspace").
If the request URL identifies a revision, that revision is the
request revision.
If the request URL identifies a versioned resource, and a Target-
Selector request header is specified, the revision selected by that
Target-Selector is the request revision; otherwise the default
target of that versioned resource is the request revision. If a
Depth header is specified, all selected revisions are merged.
If the request URL identifies a working resource, an error is
reported and no merge is performed from that working resource.
Clemm, et al. [Page 43]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
If the request URL identifies a baseline, all revisions selected by
that baseline are merged into the destination workspace.
If the request URL identifies an activity, then for each history
resource containing a revision selected by the activity, the latest
revision selected by that activity is merged into the destination
workspace. Note that the revisions selected by an activity are the
union of the DAV:revision-set of that activity with the revisions
selected by the activities identified by its DAV:subactivity-set.
For each request revision, the server determines the "merge target"
for that request revision. The merge target is the member of the
destination workspace that is a versioned resource or working
resource whose DAV:history is the same as that of the request
revision. If a request revision has no corresponding versioned
resource or working resource in the destination workspace, that
request revision is ignored by the MERGE.
The result of a merge depends on the relationship between the
request revision and it's merge target.
- If the merge target is a working resource, the request revision
is added to the DAV:merge-set of the working resource.
- If the merge target is a versioned resource whose default target
is a descendent of the request revision, the merge target is
unaffected by the MERGE.
- If the merge target is a versioned resource whose default target
is an ancestor of the request revision, the DAV:default-target of
the merge target is modified to select the request revision.
- If the merge target is a versioned resource whose default target
is neither a descendent nor an ancestor of the request revision,
the merge target is checked out and the DAV:merge-set of the new
working resource is set to contain the request revision.
A MERGE response MUST NOT be cached.
Marshalling:
The request MUST include a Destination request header.
The response body MUST contain a DAV:update-set element.
Preconditions:
The Destination header MUST identify a workspace.
If the MERGE request modifies a write-locked versioned resource or
working resource, the request MUST include the appropriate lock
token.
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.
Clemm, et al. [Page 44]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Postconditions:
The specified revisions have been merged into the destination
workspace.
The versioned resources and working resources that have been
modified by the MERGE are identified in the DAV:update-set.
13.2.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"
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
13.3UNVERSION
An UNVERSION request can be applied to a versioned resource to take
it out of version control. The associated history resource is left
unchanged.
An UNVERSION response MUST NOT be cached. If an UNVERSION request
fails, the server state preceding the request MUST be restored.
Preconditions:
The request-URL MUST identify a versioned resource.
If the parent collection is a versioned collection, it MUST have
DAV:auto-version set.
Return Status Codes:
200 (OK): The resource is no longer under version control.
405 (Method Not Allowed): The request-URL does not identify a
versioned resource.
Clemm, et al. [Page 45]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
Postconditions:
The resource MUST no longer have a DAV:default-target, DAV:history,
DAV:revision, DAV:predecessor-set, DAV:checkin-date, DAV:auto-
version, or DAV:activity property.
The revisions and history resource that were associated with the
versioned resource MUST NOT be modified by the UNVERSION request.
If the parent collection is a versioned collection with DAV:auto-
version set, a new revision of that versioned collection is created
that no longer has a binding to the history resource that was
associated with the versioned resource.
13.3.1 Example - UNVERSION
>>REQUEST
UNVERSION /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
14 ADVANCED VERSIONING REPORTS
Advanced versioning introduces the following reports (the REPORT
method is defined in section 6.6.2).
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.
Clemm, et al. [Page 46]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
14.1.1 Example - DAV:property-report
This example describes how to query a versioned resource to
determine the DAV:creator-display-name and DAV:activity of every
revision of that versioned resource.
>>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
Clemm, et al. [Page 47]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
http://repo.webdav.org/his/23/rev/2
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: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.2.1 Example - DAV:workspace-url-report
>>REQUEST
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
Clemm, et al. [Page 48]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
14.3DAV:versioned-resource-url-report
The request URL of this report MUST be a revision URL, and the
result is a URL of a versioned resource whose default target has
the same DAV:history value as that revision. The request MAY
specify the URL of a workspace, in which case the versioned
resource MUST be a member of that workspace. If an appropriate
versioned resource is not visible in the specified workspace, a
"404 (Not Found)" response status is returned.
14.3.1 Example - DAV:versioned-resource-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
14.4DAV:merge-preview-report
A merge preview describes the changes that would result if the
revisions 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:update-preview-
set element, which contains the list of versioned resources and
working resources that would be modified by the merge.
Clemm, et al. [Page 49]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
The DAV:conflict element contains the URL of a versioned resource
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 revision URL for a
revision that is a common ancestor of all the DAV:contributor
elements for a particular conflict. The first DAV:contributor
element contains a revision URL for the revision selected by the
workspace. The remaining DAV:contributor elements identify the
revision selected by the request-URL.
The DAV:update element contains the URL of a versioned resource
whose default target would change as a result of the merge, and
contains the revision URL for the new default target.
Response Status Codes:
200 (OK): The merge was performed.
2xx (Partial Merge): Only part of the requested merge could be
performed.
14.4.1 Example - DAV:merge-preview-report
>>REQUEST
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
Clemm, et al. [Page 50]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
http://www.webdav.org/ws/public/bar.html
http://www.repo/his/42/rev/3
14.5DAV: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.
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
revisions 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 versioned resource if the baselines select
different revisions of that versioned resource.
14.5.1 Example - DAV:compare-report
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.foo.com
Clemm, et al. [Page 51]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
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
http://www.foo.com/myCollection/bar.html
14.6DAV: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.
14.6.1 Example - DAV:repository-report
>>REQUEST
REPORT /myCollection HTTP/1.1
Clemm, et al. [Page 52]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
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 selects 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
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
http://www.webdav.org/ws/public
Clemm, et al. [Page 53]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
15 INTERNATIONALIZATION CONSIDERATIONS
To be supplied.
16 SECURITY CONSIDERATIONS
For security reasons, a PROPFIND request MAY report only a subset
of the labels that select this revision.
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 54]
INTERNET-DRAFT WebDAV Versioning June 15, 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), David Durand (INSO), Tim Ellison (OTI),
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, .
[RFC2068] R.Fielding, J.Gettys, J.C.Mogul, H.Frystyk, and
T.Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068,
U.C. Irvine, DEC, MIT/LCS, 1997,
.
[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/LCS, 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
.
[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,
24 AUTHORS' ADDRESSES
Geoffrey Clemm
Rational Software
20 Maguire Road, Lexington, MA 02421
Email: geoffrey.clemm@rational.com
Clemm, et al. [Page 55]
INTERNET-DRAFT WebDAV Versioning June 15, 2000
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
. Replace "server state restored" with something more
specific/constrained
Clemm, et al. [Page 56]