INTERNET-DRAFT Geoffrey Clemm, Rational Software
draft-ietf-deltav-versioning-09 Jim Amsden, IBM
Chris Kaler, Microsoft
Jim Whitehead, U.C.Irvine
Expires March 30, 2001 September 30, 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 that are
capable of interoperating with a variety of versioning repository
managers, to facilitate widespread deployment of applications capable of
utilizing the WebDAV Versioning services. WebDAV Versioning includes:
- core versioning with automatic versioning for versioning-unaware
clients,
- workspace, activity and baseline management,
- URL namespace versioning.
Clemm, et al. [Page 1]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
Table of Contents
1 INTRODUCTION...........................................5
1.1 Rationale.............................................6
1.2 Relationship to DAV...................................7
1.3 Terms.................................................7
1.4 Notational Conventions................................9
2 WEBDAV VERSIONING SEMANTICS...........................10
2.1 Creating and Modifying a Version-Controlled Resource.10
2.2 Changing the Target of a Version Selector............11
2.3 Labeling a Version...................................11
3 NEW WEBDAV XML ELEMENT ATTRIBUTES.....................12
3.1 DAV:if-unsupported...................................12
3.1.1 Example - DAV:if-unsupported.....................12
4 NEW WEBDAV PROPERTIES.................................12
4.1 DAV:comment..........................................12
4.1.1 Example - DAV:comment............................13
4.2 DAV:creator-displayname..............................13
4.2.1 Example - DAV:creator-displayname................13
4.3 DAV:supported-method-set.............................13
4.3.1 Example - DAV:supported-method-set...............13
4.4 DAV:supported-live-property-set......................13
4.4.1 Example - DAV:supported-live-property-set........13
4.5 DAV:supported-report-set.............................13
4.5.1 Example - DAV:supported-report-set...............14
5 VERSIONING PROPERTIES BY RESOURCE TYPE................14
5.1 Common Property Values...............................14
5.1.1 boolean Syntax...................................14
5.1.2 label-string Syntax..............................14
5.1.3 date-time Syntax.................................14
5.1.4 absoluteURI Syntax...............................14
5.1.5 DAV:href XML Element.............................14
5.2 Version Properties...................................15
5.2.1 DAV:resourcetype (protected).....................15
5.2.2 DAV:predecessor-set (protected)..................15
5.2.3 DAV:successor-set (protected)....................15
5.2.4 DAV:checkout-set (protected).....................15
5.2.5 DAV:checkin-date (protected).....................15
5.2.6 DAV:version-name (protected).....................15
5.2.7 DAV:label-name-set (protected)...................16
5.3 Version Selector Properties..........................16
5.3.1 DAV:resourcetype.................................16
5.3.2 DAV:target (protected)...........................16
5.3.3 DAV:checked-out (protected)......................16
5.3.4 DAV:auto-version.................................16
5.4 Working Resource Properties..........................17
6 WEBDAV HEADERS........................................17
6.1 Overwrite............................................17
Clemm, et al. [Page 2]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
7 VERSIONING HEADERS....................................17
7.1 Target-Selector......................................17
8 VERSIONING AND EXISTING METHODS.......................18
8.1 Response Bodies for 4XX Status Responses.............18
8.1.1 Example - GET request with DAV:must-select-version response 18
8.2 OPTIONS..............................................19
8.2.1 Example - OPTIONS................................19
8.3 GET..................................................19
8.4 PUT..................................................20
8.5 PROPFIND.............................................20
8.6 PROPPATCH............................................20
8.7 DELETE...............................................21
8.8 COPY.................................................21
8.9 MOVE.................................................21
9 NEW WEBDAV METHODS....................................22
9.1 REPORT...............................................22
10 VERSIONING METHODS...................................22
10.1 VERSION-CONTROL....................................22
10.1.1 Example - VERSION-CONTROL (creating a new version history) 24
10.1.2 Example - VERSION-CONTROL (using an existing version) 24
10.2 CHECKOUT...........................................25
10.2.1 Example - CHECKOUT of a version selector.........26
10.2.2 Example - CHECKOUT of a version..................26
10.3 CHECKIN............................................27
10.3.1 Example - CHECKIN................................28
10.4 UNCHECKOUT.........................................28
10.4.1 Example - UNCHECKOUT.............................29
10.5 SET-TARGET.........................................29
10.5.1 Example - SET-TARGET.............................30
10.6 LABEL..............................................31
10.6.1 Example - Setting a label........................32
11 VERSIONING REPORTS...................................32
11.1 DAV:version-tree-report............................32
11.1.1 Example - DAV:version-tree-report................33
12 ADVANCED VERSIONING..................................34
12.1 Advanced Versioning Terms..........................34
13 ADVANCED VERSIONING SEMANTICS........................36
13.1 Workspaces.........................................36
13.2 Baselines..........................................37
13.3 Activities, Change Sets, and Branches..............37
13.4 Parallel Development and Merging...................38
13.5 Version-Controlled Collections.....................38
13.6 Automatic Version Control..........................41
13.7 Mutable Versions...................................42
14 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE......42
14.1 Version Properties.................................42
14.1.1 DAV:version-history (protected)..................42
Clemm, et al. [Page 3]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
14.1.2 DAV:activity-set.................................42
14.1.3 DAV:checkout-fork................................42
14.1.4 DAV:checkin-fork.................................43
14.1.5 DAV:mutable......................................43
14.2 Version History Properties.........................43
14.2.1 DAV:version-set (protected)......................43
14.2.2 DAV:initial-version (protected)..................43
14.2.3 DAV:latest-version (protected)...................44
14.3 Version Selector Properties........................44
14.3.1 DAV:workspace....................................44
14.3.2 DAV:merge-set....................................44
14.3.3 DAV:auto-merge-set...............................44
14.3.4 DAV:unreserved...................................44
14.3.5 DAV:predecessor-set..............................45
14.3.6 DAV:activity-set.................................45
14.3.7 DAV:checkout-fork................................45
14.3.8 DAV:checkin-fork.................................45
14.3.9 DAV:mutable......................................45
14.4 Workspace Properties...............................45
14.4.1 DAV:current-activity-set.........................45
14.4.2 DAV:baselined-collection-set.....................46
14.5 Collection Properties..............................46
14.5.1 DAV:baseline-selector (protected)................46
14.6 Baseline Properties................................46
14.6.1 DAV:version-set (protected)......................46
14.7 Activity Properties................................47
14.7.1 DAV:version-set (protected)......................47
14.7.2 DAV:subactivity-set..............................47
14.7.3 DAV:current-workspace-set........................47
15 ADVANCED VERSIONING HEADERS..........................47
15.1 Workspace..........................................47
16 ADVANCED VERSIONING AND EXISTING METHODS.............48
16.1 GET................................................48
16.2 PUT................................................49
16.3 DELETE.............................................49
16.4 MKCOL..............................................49
16.5 COPY...............................................49
16.6 MOVE...............................................50
16.7 VERSION-CONTROL....................................50
16.8 CHECKOUT...........................................51
16.8.1 Example - Advanced CHECKOUT......................52
16.9 CHECKIN............................................52
16.10 SET-TARGET.........................................54
17 ADVANCED VERSIONING METHODS..........................54
17.1 MKWORKSPACE........................................54
17.1.1 Example - MKWORKSPACE............................55
17.2 MKACTIVITY.........................................56
17.2.1 Example - MKACTIVITY.............................56
17.3 BASELINE-CONTROL...................................56
17.3.1 Example - BASELINE-CONTROL.......................57
17.4 MERGE..............................................58
Clemm, et al. [Page 4]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
17.4.1 Example - MERGE..................................60
18 ADVANCED VERSIONING REPORTS..........................61
18.1 DAV:property-report................................61
18.1.1 Example - DAV:property-report....................61
18.2 DAV:repository-report..............................63
18.2.1 Example - DAV:repository-report..................63
18.3 DAV:merge-preview-report...........................64
18.3.1 Example - DAV:merge-preview-report...............64
18.4 DAV:compare-report.................................65
18.4.1 Example - DAV:compare-report.....................66
18.5 DAV:version-selector-url-report....................67
18.5.1 Example - DAV:version-selector-url-report........67
19 INTERNATIONALIZATION CONSIDERATIONS..................68
20 SECURITY CONSIDERATIONS..............................68
21 AUTHENTICATION.......................................69
22 IANA CONSIDERATIONS..................................69
23 INTELLECTUAL PROPERTY................................69
24 ACKNOWLEDGEMENTS.....................................69
25 REFERENCES...........................................70
26 AUTHORS' ADDRESSES...................................70
1 INTRODUCTION
This document defines WebDAV Versioning extensions, an application
of HTTP/1.1 for handling resource versioning in a WebDAV
environment. WebDAV Versioning defines two levels of versioning
functionality: core versioning and advanced versioning.
Core versioning provides versioning of largely independent
resources. It allows authors to concurrently create, label, and
access distinct versions of a resource, and provides automatic
versioning for versioning-unaware clients. All core versioning
functionality MUST be provided by a resource that supports
versioning.
Advanced versioning provides more sophisticated capabilities such
as logical change tracking, workspace management, and URL namespace
versioning. A particular resource may support only a subset of the
advanced versioning capabilities. The advanced versioning
capabilities provided by a particular resource can be discovered
with an OPTIONS request.
This document will first define the terminology, semantics,
properties, methods, and headers for core versioning, and then
Clemm, et al. [Page 5]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
define the additional terminology, semantics, properties, and
methods for advanced versioning.
1.1 Rationale
Versioning, parallel development, and configuration management are
important features for remote authoring of Web content. Version
management is concerned with tracking and accessing the history of
important states of a single Web resource, such as a standalone Web
page. Parallel development provides additional resource
availability in multi-user, distributed environments and lets
authors make changes on the same resource at the same time, and
merge those changes at some later date. Configuration management
addresses the problems of tracking and accessing multiple
interrelated resources over time as sets of resources, not simply
individual resources. Traditionally, artifacts of software
development, including code, design, test cases, requirements, and
help files, have been a focus of configuration management. Web
sites, comprised of multiple inter-linked resources (HTML,
graphics, sound, CGI, and others), are another class of complex
information artifacts that benefit from the application of
configuration management.
The benefits of versioning in the context of the worldwide web
include:
- It provides infrastructure for efficient and controlled
management of large evolving web sites. Modern configuration
management systems are built on some form of repository that can
track the version history of individual resources, and provide the
higher-level tools to manage those saved versions. Basic
versioning capabilities are required to support such systems.
- It allows parallel development and update of single resources.
Since versioning systems register change by creating new objects,
they enable simultaneous write access by allowing the creation of
multiple versions. Many also provide merge support to ease the
reverse operation.
- It provides a framework for coordinating changes to resources.
While specifics vary, most systems provide some method of
controlling or tracking access to enable collaborative resource
development.
- It represents the fact that a resource has an explicit history
and a persistent identity across the various states it has had
during the course of that history. It allows browsing through past
and alternative versions of a resource. Frequently the
modification and authorship history of a resource is critical
information in itself.
- It provides stable names that can support externally stored links
for annotation and link-server support. Both annotation and link
Clemm, et al. [Page 6]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
servers frequently need to store stable references to portions of
resources that are not under their direct control. By providing
stable states of resources, version control systems allow not only
stable pointers into those resources, but also well defined methods
to determine the relationships of those states of a resource.
1.2 Relationship to DAV
To maximize interoperability and the use of existing protocol
functionality, versioning support is designed as extensions to the
WebDAV protocol [RFC2518]. The versioning extensions are designed
to be orthogonal to most aspects of the HTTP and WebDAV protocols,
except for specific interactions identified in sections 8 and 16.
1.3 Terms
This draft uses the terms defined in HTTP [RFC2616] and WebDAV
[RFC2518]. In addition, the following terms are defined:
Versionable Resource
A "versionable resource" is a resource that can be put under
version control.
Version
A "version" is a (usually immutable) resource that contains the
content and dead properties of a particular state of a resource
under version control. The server allocates a distinct new URL for
each new version.
Version History
A "version history" is a resource that contains all the versions of
a particular resource under version control. The server allocates
a distinct new URL for each new version history.
Initial Version
An "initial version" is the first version of a version history.
Version Selector
When an existing resource is put under version control, it becomes
a "version selector" resource. A new version history resource is
allocated, whose initial version contains the content and dead
properties of the existing resource. A version selector must be
"checked out" to modify its content or dead properties, and then
subsequently can be "checked in" to create a new version in its
version history.
Target
Clemm, et al. [Page 7]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
The version whose content and dead properties are displayed by a
checked-in version selector is called the "target" of that version
selector.
Working Resource
A "working resource" is a resource created by the server when a
version (instead of a version selector) is checked out. Unlike a
checked-out version selector, a working resource is deleted when it
is checked in. The server allocates a distinct new URL for each
new working resource.
Version Label
A "version label" is a string chosen by a client to identify a
particular version of a version history.
Version Name
A "version name" is a string chosen by the server to identify a
particular version of a version history.
Predecessor, Successor, Ancestor, Descendant
A "predecessor" of a version is another version that was checked
out or merged to create the version. When a version is related to
another version by one or more predecessor relations, it is called
an "ancestor" of that version.
The inverse of the predecessor and ancestor relations are the
"successor" and "descendant" relations. Therefore, if X is a
predecessor of Y, then Y is a successor of X, and if X is an
ancestor of Y, then Y is a descendant of X.
Clemm, et al. [Page 8]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
The following diagram illustrates several of the previous
definitions.
History of foo.html
+---+
Initial Version ----> | | V1
+---+
| ^
| |
+---+ |
Label ------> "beta1" | | V2 | Ancestor
+---+ |
/ \ |
/ \ |
+---+ +---+
| | V3 | | V4
^ +---+ +---+
| | | |
Predecessor | | | |
| +---+ +---+ |
| | V5 | | V6 | Descendant
| +---+ +---+ |
Successor | \ / |
| \ / v
v +---+
| | V7
+---+
Fork, Merge
When a second successor is added to a version, this creates a
"fork" in the version history. In the preceding diagram, there is
a fork at version V2. When a version is created with multiple
predecessors, this creates a "merge" in the version history. In
the preceding diagram, there is a merge at version V7.
1.4 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 9]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
A phrase of the form "the method XXX is applied to a yyy" means
"the method XXX is applied to a URL that identifies a resource of
type yyy".
2 WEBDAV VERSIONING SEMANTICS
2.1 Creating and Modifying a Version-Controlled Resource
In order to track the history of the content and dead properties of
a resource, an author can put the resource under version control.
This creates a new version history resource, creates an initial
version in that version history that contains the current content
and dead properties of the versionable resource, and then replaces
the versionable resource with a version selector resource whose
target is this initial version.
===VERSION-CONTROL==>
| +----+ Version
| foo.html | | History
foo.html | Version +----+
| Selector |
| |
+----+ | +----+ Target +----+
| S1 | | | S1 | --------> | S1 | Version
+----+ | +----+ +----+
In order to modify the content or dead properties of a checked-in
version selector, an author must first check it out (except for the
SET-TARGET method, see 10.5). The author can then modify the
checked-out resource by setting its content or properties any
number of times. When the author determines the checked-out
resource is in a state that should be retained, the author checks
it in to create a new version in the version history. The version
that was checked out is remembered as the predecessor of the new
version. Unless the server supports mutable versions, an author
cannot modify the content or dead properties of a version, but
instead must create descendants of that version.
Clemm, et al. [Page 10]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
The following diagram illustrates the effect of the
checkout/checkin process on a version selector and its version
history.
===CHECKOUT==> ===PUT==> ===CHECKIN==>
foo.html Version Selector
+----+ | +----+ | +----+ | +----+
| S2 | | | S2 | | | S3 | | | S3 |
+----+ | +----+ | +----+ | +----+
Target=V2 |Checked-Out=V2|Checked-Out=V2| Target=V3
foo.html History
+----+ | +----+ | +----+ | +----+
| S1 | V1 | | S1 | V1 | | S1 | V1 | | S1 | V1
+----+ | +----+ | +----+ | +----+
| | | | | | |
| | | | | | |
+----+ | +----+ | +----+ | +----+
| S2 | V2 | | S2 | V2 | | S2 | V2 | | S2 | V2
+----+ | +----+ | +----+ | +----+
| | | |
| | | |
| | | +----+
| | | | S3 | V3
| | | +----+
2.2 Changing the Target of a Version Selector
It is possible to modify the state of a checked-in version selector
by using a SET-TARGET request to select another version from the
version history of the current target of the version selector. The
specified version becomes the new target of the version selector,
and the content and dead properties of the version selector are set
to be those of the specified version.
2.3 Labeling a Version
At any time, a version can be given a client-assigned label in
order to provide a meaningful name for that version. A given
version label can be assigned to at most one version of a given
version history, but may be reassigned to another version at any
time. Note that although a given label cannot be applied to more
than one version from the same version history, the same label can
be applied to versions from different version histories.
Clemm, et al. [Page 11]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
For certain methods, if the request-URL identifies a version
selector, a label can be specified in a Target-Selector request
header to cause the method to be applied to the version selected by
that label from the version history of that version selector.
3 NEW WEBDAV XML ELEMENT ATTRIBUTES
This section defines new WebDAV XML element attributes that are of
generic interest (i.e. are not versioning specific).
3.1 DAV:if-unsupported
This attribute indicates how a XML element in a request body should
be handled when the server does not recognize its type. The
possible values are "ignore" (the default) and "error". If the
server does not recognize the type of an XML element, it should
ignore that element if it has an if-unsupported="ignore" attribute,
and it should return 400 (Bad Request) status if it has an if-
unsupported="error" attribute. The "if-unsupported" attribute of
an element is inherited by every child of that element, unless that
child has an explicit "if-unsupported" attribute.
3.1.1Example - DAV:if-unsupported
<D:checkout xmlns:D="DAV:" D:if-unsupported="error">
</D:keep-checked-out>
</D:branch-ok D:if-unsupported="ignore">
</D:checkout>
In this example, a server can ignore the DAV:branch-ok element, but
must fail the request if it does not recognize the DAV:keep-
checked-out element.
4 NEW WEBDAV PROPERTIES
This section defines new WebDAV properties that are of generic
interest (i.e. are not versioning specific).
4.1 DAV:comment
This property is used to track a brief comment about a resource
that is suitable for presentation to a user. The DAV:comment of a
version can be used to indicate why that version was created.
<!ELEMENT comment (#PCDATA)>
PCDATA value: string
Clemm, et al. [Page 12]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
4.1.1Example - DAV:comment
<DAV:comment>This version is much faster.</DAV:comment>
4.2 DAV:creator-displayname
This property contains a description of the creator of the resource
that is suitable for presentation to a user. The DAV:creator-
displayname of a version can be used to indicate who created that
version.
<!ELEMENT creator-displayname (#PCDATA)>
PCDATA value: string
4.2.1Example - DAV:creator-displayname
<DAV:creator-displayname>Alan Turing</DAV:creator-displayname>
4.3 DAV:supported-method-set
This property identifies the methods supported by this resource.
<!ELEMENT supported-method-set (ANY*)>
4.3.1Example - DAV:supported-method-set
<DAV:supported-method-set>
<GET/> <PUT/> <POST/> <DELETE/>
<PROPFIND/> <PROPPATCH/> <COPY/> <MOVE/>
<VERSION-CONTROL/>
</DAV:supported-method-set>
4.4 DAV:supported-live-property-set
This property identifies the live properties supported by this
resource.
<!ELEMENT supported-live-property-set (ANY*)>
4.4.1Example - DAV:supported-live-property-set
<D:supported-live-property-set xmlns:D="DAV:">
<D:creationdate/> <D:displayname/>
<D:getcontentlength/> <D:getcontenttype/>
<D:getetag/> <D:getlastmodified/> <D:resourcetype/>
<D:target/> <D:checked-out/> <D:auto-version/>
</D:supported-live-property-set>
4.5 DAV:supported-report-set
This property identifies the reports (see section 9.1) supported by
this resource.
<!ELEMENT supported-report-set (ANY*)>
Clemm, et al. [Page 13]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
4.5.1Example - DAV:supported-report-set
<D:supported-report-set xmlns:D="DAV:">
<D:version-tree-report/> <D:property-report/>
</D:supported-report-set>
5 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
undefined.
5.1 Common Property Values
5.1.1boolean Syntax
Some properties take a Boolean value.
boolean = "F" | "T"
5.1.2label-string 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.
5.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].
5.1.4absoluteURI Syntax
Some headers and properties take an absolute URI value. The syntax
of absoluteURI is defined in section 3 of [RFC2396].
5.1.5DAV:href XML Element
The DAV:href XML element is defined in section 12.3 of [RFC2518].
Clemm, et al. [Page 14]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
5.2 Version Properties
WebDAV versioning introduces the following properties for a
version.
5.2.1DAV:resourcetype (protected)
This property MUST contain the same DAV:resourcetype as the
resource that was checked in. The presence of a DAV:version-name
property can be used to determine whether a resource is a version.
5.2.2DAV:predecessor-set (protected)
This property contains a URL for each predecessor of this version.
Except for the initial version, which has no predecessors, either
there is the single predecessor that was checked out to create the
version, or there are the multiple predecessors that were merged to
create the version. The order of the DAV:href elements in
DAV:predecessor-set MUST be maintained by the server.
<!ELEMENT predecessor-set (href*)>
5.2.3DAV:successor-set (protected)
This property contains a URL for each version whose
DAV:predecessor-set contains this version.
<!ELEMENT successor-set (href*)>
5.2.4DAV:checkout-set (protected)
This property contains a URL for each working resource and version
selector whose DAV:checked-out property identifies this version.
<!ELEMENT checkout-set (href*)>
5.2.5DAV:checkin-date (protected)
This property contains the date on the server when the version was
checked in. This property MUST NOT be created by a server that
cannot provide a reasonable approximation of the current time.
<!ELEMENT checkin-date (#PCDATA)>
PCDATA value: date-time
5.2.6DAV:version-name (protected)
This property contains a server-defined string that is different
for each version in a given version history. This string is
intended to be displayed to a user, unlike the version URL, which
is normally only used by a client and not displayed to a user.
Clemm, et al. [Page 15]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
<!ELEMENT version-name (#PCDATA)>
5.2.7DAV:label-name-set (protected)
This property contains the labels that currently select this
version.
<!ELEMENT label-name-set (label-name*)>
<!ELEMENT label-name (#PCDATA)>
PCDATA value: label-string
5.3 Version Selector Properties
WebDAV versioning introduces the following properties for a version
selector.
5.3.1DAV:resourcetype
This property contains the same DAV:resourcetype as the resource
that was put under version control. The presence of a DAV:target
or DAV:checked-out property can be used to determine whether a
resource is a checked in or checked out version selector.
5.3.2DAV:target (protected)
This property contains the version URL of the version that is the
target of this version selector, and only appears on a checked-in
version selector.
<!ELEMENT target (href)>
This property can be modified by the SET-TARGET method.
5.3.3DAV:checked-out (protected)
This property contains the value of the DAV:target property at the
time the version selector was checked out, and only appears on a
checked-out version selector.
<!ELEMENT checked-out (href)>
5.3.4DAV:auto-version
When the DAV:auto-version property of a version selector is set, a
request that attempts to modify that version selector (such as
PUT/PROPPATCH) is automatically preceded by a CHECKOUT and
automatically followed by a CHECKIN. This allows a versioning-
unaware client to modify a version selector.
<!ELEMENT auto-version (#PCDATA)>
Clemm, et al. [Page 16]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
PCDATA value: boolean
5.4 Working Resource Properties
A working resource has all the properties of a checked-out version
selector.
6 WEBDAV HEADERS
This section defines extensions to existing WebDAV headers.
6.1 Overwrite
In RFC-2518, the Overwrite header is defined to take the value "T"
(which deletes any resource currently located at the Destination of
a MOVE or COPY) and "F" (which aborts the request if a resource is
currently located at the Destination of a MOVE or COPY).
Unfortunately, this does not allow you to update an existing
resource. The difference between updating a resource and replacing
a resource with a new resource is especially important when
resource history is being maintained.
To address this problem, this extension of the Overwrite header
adds a third value, "update".
Overwrite := "Overwrite" ":" ("T" | "F" | "update")
When Overwrite:update is specified, a MOVE or COPY into a
Destination collection adds or replaces members of that collection,
but does not delete members of that collection. If the Destination
is a non-collection, then a MOVE will replace the Destination
resource (just as with Overwrite:T), while a COPY will update the
body and properties of the Destination (just as with
PUT/PROPPATCH).
7 VERSIONING HEADERS
7.1 Target-Selector
For certain methods (e.g. GET, PROPFIND), if the request-URL
identifies a version selector, a label can be specified in a
Target-Selector request header to cause the method to be applied to
the version selected by that label from the version history of that
version selector.
The following defines the BNF for the Target-Selector header:
Target-Selector := "Target-Selector" ":" label-string
An example of a Target-Selector header is:
Clemm, et al. [Page 17]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
Target-Selector: released
A Target-Selector header has no effect on a request-URL that does
not identify a version selector. In particular, it has no effect
on a URL that identifies a version or a version history.
A server MUST return an HTTP-1.1 Vary header containing Target-
Selector in a successful response to a cacheable request (e.g. GET,
PROPFIND) that includes a Target-Selector header.
8 VERSIONING AND EXISTING METHODS
This section defines the impact of core versioning functionality on
existing methods.
For any method that updates the content or dead properties of a
resource, when that method is applied to a checked-in version
selector, the method MUST fail unless the version selector has a
DAV:auto-version property. If the version selector has a DAV:auto-
version property, the version selector is checked out, the update
is applied to the checked-out version selector, and the version
selector is checked in. This functionality allows a versioning
unaware client to effectively modify a checked-in version selector.
If any part of the checkout/update/checkin sequence fails, the
status from the failed part of the request MUST be returned, and
the server state preceding the request sequence MUST be restored.
A server MAY automatically place a newly created resource under
version control. Whenever this occurs, the new version selector
MUST be in the state that would result from applying the VERSION-
CONTROL method to the new resource.
8.1 Response Bodies for 4XX Status Responses
According to section 10.4 of [RFC2616]: "The 4xx class of status
code is intended for cases in which the client seems to have erred.
Except when responding to a HEAD request, the server SHOULD include
an entity containing an explanation of the error situation, and
whether it is a temporary or permanent condition."
In order to allow better client handling of 4xx responses, this
document associates an XML element type with each method
precondition defined in this document. When a particular
precondition is violated by a request, the appropriate XML element
MUST be returned in the response body. This element MAY be the
top-level element of the response body, or it MAY be nested within
other elements in the response body.
8.1.1Example - GET request with DAV:must-select-version response
>>REQUEST
Clemm, et al. [Page 18]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
GET /foo.html HTTP/1.1
Host: www.webdav.org
Target-Selector: stable
>>RESPONSE
HTTP/1.1 409 Conflict
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<DAV:must-select-version/>
In this example, the request to GET the content of the version
labeled "stable" of "/foo.html" fails because no version of
/foo.html is labeled as "stable".
8.2 OPTIONS
When a resource supports versioning, the DAV response header for an
OPTIONS request MUST contain "versioning".
8.2.1Example - OPTIONS
>>REQUEST
OPTIONS /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
DAV: 1, 2, versioning
Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, VERSION-CONTROL
In this example, the OPTIONS response indicates that the server
supports versioning and that /foo.html can be put under version
control with the VERSION-CONTROL method.
8.3 GET
Additional Marshalling:
A Target-Selector request header MAY be included.
Additional Preconditions:
<DAV:must-select-version/>: If a Target-Selector request header is
included and the request-URL identifies a version selector, the
Clemm, et al. [Page 19]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
specified label MUST select a version in the version history of the
version selector.
Additional Postconditions:
If the request-URL identifies a version selector and a Target-
Selector request header is included, the response will contain the
content of the specified version rather than that of the version
selector.
8.4 PUT
Additional Preconditions:
<DAV:cannot-modify-version-selector-content/>: If the request-URL
identifies a checked-in version selector, the PUT MUST fail unless
DAV:auto-version is set for that version selector. If DAV:auto-
version is set, all preconditions of the automatic CHECKOUT,
CHECKIN, and SET-TARGET apply.
<DAV:cannot-modify-version-content/>: If the request-URL identifies
a version, the PUT MUST fail.
Additional Postconditions:
If the PUT creates a new resource, the new resource MAY be
automatically put under version control.
8.5 PROPFIND
Additional Marshalling:
A Target-Selector request header MAY be included.
Additional Preconditions:
<DAV:must-select-version/>: If a Target-Selector request header is
included and the request-URL identifies a version selector, the
specified label MUST select a version in the version history of the
version selector.
Additional Postconditions:
If the request-URL identifies a version selector and a Target-
Selector request header is included, the response will contain the
properties of the specified version rather than that of the version
selector.
8.6 PROPPATCH
Additional Preconditions:
Clemm, et al. [Page 20]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
<DAV:cannot-modify-version-selector-property/>: If the request-URL
identifies a checked-out version selector, an attempt to modify a
dead property MUST fail unless DAV:auto-version is set for that
version selector. If DAV:auto-version is set, all preconditions of
the automatic CHECKOUT and CHECKIN apply.
<DAV:cannot-modify-version-property/>: If the request-URL
identifies a version, an attempt to modify a dead property MUST
fail.
<DAV:cannot-modify-protected-property/>: An attempt to use
PROPPATCH to modify a property (either core or advanced) defined by
this document as being protected MUST fail.
<DAV:cannot-modify-unsupported-property/>: An attempt to modify a
property defined by this document (either core or advanced) whose
semantics are not enforced by the server MUST fail. This helps
ensure that a client will be notified when it is trying to use a
property whose semantics are not supported by the server.
8.7 DELETE
Additional Postconditions:
If the request-URL identifies a version, the result is undefined.
8.8 COPY
Additional Marshalling:
A Target-Selector request header MAY be included.
Additional Preconditions:
<DAV:must-select-version/>: If a Target-Selector request header is
included and the request-URL identifies a version selector, the
specified label MUST select a version in the version history of the
version selector.
Additional Postconditions:
The result of copying a version selector, a version, or a working
resource is a new versionable resource at the destination of the
COPY. The new resource MAY automatically be put under version
control, but the resulting version selector MUST be associated with
a new version history created for that new version selector.
8.9 MOVE
Additional Preconditions:
Clemm, et al. [Page 21]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
<DAV:cannot-rename-resource/>: If the request-URL is a version URL
or a working resource URL, the request MUST fail.
Additional Postconditions:
When a version selector is moved, its DAV:target or DAV:checked-out
property MUST NOT be modified.
9 NEW WEBDAV METHODS
This section defines new WebDAV methods that are of generic
interest (i.e. are not versioning specific).
9.1 REPORT
A REPORT request is an extensible mechanism for obtaining
information about a resource. Unlike a resource property, which
has a single value, the value of a report can depend on additional
information specified in the REPORT request body and in the REPORT
request headers.
Marshalling:
The request body of a REPORT request specifies which report is
being requested, as well as any additional information that will be
used to customize the report.
A Depth header MAY be included in a REPORT request. If it does
include a Depth header, the response MUST be a 207 Multi-Status.
The response body of a REPORT request contains the requested
report.
Postconditions:
The REPORT method MUST NOT change the content or dead properties of
any resource managed by the server.
10 VERSIONING METHODS
This section defines new WebDAV methods that provide core
versioning functionality
10.1VERSION-CONTROL
A VERSION-CONTROL request can be used to create a version
controlled resource at the request-URL.
If the request-URL identifies a versionable resource, a new version
history resource is created, an initial version is created whose
Clemm, et al. [Page 22]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
content and dead properties are that of the versionable resource,
and the versionable resource is replaced by a version selector
resource whose target is the initial version of the new version
history.
If the request body identifies a version, the request-URL MUST
identify a null resource, and a new version selector whose target
is the specified version is created at the request-URL.
If a VERSION-CONTROL request fails, the server state preceding the
request MUST be restored.
Marshalling:
If a request body is included, it MUST be a DAV:version-control XML
element.
<!ELEMENT version-control (version?)>
<!ELEMENT version (href)>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
<DAV:must-be-versionable/>: The request-URL MUST identify a
versionable resource, a null resource, or a version selector.
<DAV:must-be-version/>: The DAV:href of the DAV:version element
MUST identify a version.
<DAV:cannot-add-to-existing-history/>: If the request-URL
identifies a versionable resource or a version selector, the
DAV:version-control request body element MUST NOT contain a
DAV:version element.
<DAV:initial-version-required/>: If the request-URL identifies a
null resource, the DAV:version-control request body element must
contain a version URL.
Postconditions:
If the request-URL identified a version selector at the time of the
request, the VERSION-CONTROL request MUST NOT change the state of
that version selector.
If the request-URL identified a versionable resource at the time of
the request, a new version history is created, a copy of the
versionable resource is made the initial version of the new version
selector, and the versionable resource is replaced by a new version
selector resource whose DAV:target identifies the initial version
of the new version history. The DAV:predecessor-set of the initial
version is empty, and the DAV:checkin-date is the current date on
the server. Note that an implementation can chose to locate the
version history and version resources anywhere that it wishes. In
Clemm, et al. [Page 23]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
particular, it could locate them on the same host and server as the
version selector, on a different virtual host maintained by the
same server, on the same host maintained by a different server, or
on a different host maintained by a different server.
If the request-URL identified a null resource, a new version
selector resource is created at the request-URL whose target is the
version specified in the request body.
10.1.1 Example - VERSION-CONTROL (creating a new version history)
>>REQUEST
VERSION-CONTROL /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, /foo.html is put under version control. A new
version history is created for it, and an initial version is
created that is a copy of the content and properties of /foo.html.
The resource /foo.html is replaced by a version selector whose
target is this initial version.
10.1.2 Example - VERSION-CONTROL (using an existing version)
>>REQUEST
VERSION-CONTROL /bar.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-control xmlns:D="DAV:">
<D:version>
<D:href>http://repo.webdav.org/his/12/ver/V3</D:href>
</D:version>
</D:version-control>
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, the null resource /bar.html is put under version
control, and the target of the new version selector is the version
identified by http://repo.webdav.org/his/12/ver/V3.
Clemm, et al. [Page 24]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
10.2CHECKOUT
A CHECKOUT request can be applied to a checked-in version selector
to allow modifications to the content and dead properties of that
version selector.
A CHECKOUT request can also be applied to a version to create a new
working resource. The content and properties of the working
resource are a copy of the version that was checked out.
A versioning server MUST support either version selector CHECKOUT
or version CHECKOUT, and MAY support both.
If a CHECKOUT request fails, the server state preceding the request
MUST be restored.
Marshalling:
The request MAY include a Target-Selector header.
If a request body is included, it MUST be a DAV:checkout XML
element.
<!ELEMENT checkout (target?)>
<!ELEMENT target EMPTY>
The response MUST include a Location header.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
<DAV:must-be-version-or-version-selector/>: The request-URL MUST
identify a version or a version selector.
<DAV:must-not-be-checked-out/>: If a version selector is being
checked out, it MUST NOT have a DAV:checked-out property value.
<DAV:checkout-requires-lock-token/>: If a version selector is being
checked out and the version selector is locked, the lock token MUST
be specified in the CHECKOUT request.
<DAV:must-be-version-selector/>: If a Target-Selector request
header is included, the request-URL MUST identify a version
selector.
<DAV:must-select-version/>: If a Target-Selector request header is
included and the request-URL identifies a version selector, the
specified label MUST select a version in the version history of the
version selector.
Postconditions:
Clemm, et al. [Page 25]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
If a version selector was checked out, the version selector MUST
have a DAV:checked-out property that contains the value of the
DAV:target property preceding the checkout. The version selector
MUST NOT have a DAV:target property value. The Location response
header MUST identify the version selector.
If a version was checked out, the Location response header MUST
contain the URL of a new working resource. The DAV:checked-out
property of the new working resource MUST identify the version that
was checked out. The content and dead properties of the working
resource MUST be the same as the content and dead properties of the
DAV:checked-out version.
If DAV:target is specified in the request body, the CHECKOUT is
applied to the version identified by the DAV:target of the version
selector, and not the version selector itself. A new working
resource is created and the version selector remains checked-in.
If a Target-Selector request header is included, the CHECKOUT is
applied to the version selected by the specified label, and not to
the version selector itself. A new working resource is created and
the version selector remains checked in.
10.2.1 Example - CHECKOUT of a version selector
>>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/foo.html
Cache-Control: no-cache
In this example, the version selector /foo.html is checked out.
10.2.2 Example - CHECKOUT of a version
>>REQUEST
CHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:checkout xmlns:D="DAV:">
<D:target/>
</D:checkout>
Clemm, et al. [Page 26]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
>>RESPONSE
HTTP/1.1 201 Created
Location: http://www.webdav.org/repo/wr-157.html
Cache-Control: no-cache
In this example, the current target of the version selector
/foo.html is checked out, and the new working resource is located
at http://www.webdav.org/repo/wr-157.html.
10.3CHECKIN
A CHECKIN request can be applied to a working resource or a
checked-out version selector to produce a new version whose content
and dead properties are those of that working resource or version
selector.
If a CHECKIN request fails, the server state preceding the request
MUST be restored.
Marshalling:
If a request body is included, it MUST be a DAV:checkin XML
element.
<!ELEMENT checkin (keep-checked-out?) >
<!ELEMENT keep-checked-out EMPTY>
The response MUST include a Location header.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
<DAV:must-be-working-resource-or-version-selector/>: The request-
URL MUST identify a working resource or checked-out version
selector.
<DAV:checkin-requires-lock-token/>: If the working resource or
version selector is write-locked, then the appropriate lock token
MUST be included in the request.
Postconditions:
A new version is created in the version history of the DAV:checked-
out version.
The content and dead properties of the new version are those of the
working resource or version selector.
Clemm, et al. [Page 27]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
The DAV:version-name of the new version is set to a server-defined
value distinct from all other DAV:version-name values of other
versions in the version history of that version.
The DAV:predecessor-set of the new version is set to the
DAV:checked-out property of the working resource or version
selector.
The DAV:checkin-date of the new version is set to the current date
on the server.
If DAV:keep-checked-out is specified, the DAV:checked-out property
of the working resource or version selector is updated to identify
the new version. Otherwise, if the request-URL identifies a
version selector, the DAV:checked-out property is removed and a
DAV:target property containing the new version is added.
Otherwise, the working resource is deleted.
A URL for the new version is returned in a Location response
header.
10.3.1 Example - CHECKIN
>>REQUEST
CHECKIN /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/his/23/ver/32
Cache-Control: no-cache
In this example, version selector /foo.html is checked in, and a
new version is created at http://repo.webdav.org/his/23/ver/32.
10.4UNCHECKOUT
An UNCHECKOUT request can be applied to a checked-out version
selector to cancel the CHECKOUT.
If an UNCHECKOUT request fails, the server state preceding the
request MUST be restored.
Marshalling:
The response MUST include a Cache-Control:no-cache header.
Preconditions:
Clemm, et al. [Page 28]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
<DAV:must-be-checked-out-version-selector/>: The request-URL MUST
identify a checked-out version selector.
<DAV:uncheckout-requires-lock-token/>: If the version selector is
write-locked, the UNCHECKOUT request MUST include the appropriate
lock token.
Postconditions:
The DAV:target of the version selector is its DAV:checked-out value
prior to the UNCHECKOUT.
The DAV:checked-out property of the version selector is removed.
The content and dead properties of the version selector are those
of its DAV:target version.
10.4.1 Example - UNCHECKOUT
>>REQUEST
UNCHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, the content and dead properties of the version
selector identified by http://www.webdav.org/foo.html are restored
to their values preceding the most recent CHECKOUT of that version
selector.
10.5SET-TARGET
A SET-TARGET request can be applied to a checked-in version
selector to change the DAV:target of that version selector.
A SET-TARGET can be applied to a collection with a Depth header
even if the collection is not a version selector, in order to
attempt the SET-TARGET on all its version selector members. In
this case, a DAV:label-name element is normally specified in the
request body, since otherwise the SET-TARGET would succeed on at
most one member of the collection.
Marshalling:
The SET-TARGET request body MUST be a DAV:set-target XML element.
<!ELEMENT set-target (label-name | version)>
Clemm, et al. [Page 29]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
<!ELEMENT label-name (#PCDATA)>
<!ELEMENT version (href)>
The request MAY include a Depth header. If it does include a Depth
header, the response MUST be a 207 Multi-Status.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
<DAV:must-be-checked-in-version-selector/>: The request-URL MUST
identify a checked-in version selector.
<DAV:must-select-version/>: If a version is specified in the SET-
TARGET request body, it MUST be a version in the version history of
the version selector.
<DAV:must-select-version/>: If a label is specified in the SET-
TARGET request body, it MUST select a version in the version
history of the version selector.
<DAV:set-target-requires-lock-token/>: If the version selector is
write-locked, the SET-TARGET request MUST include the appropriate
lock token.
Postconditions:
The DAV:target of the version selector MUST be set to the specified
version.
If a Depth header is specified, the SET-TARGET request is applied
separately to the collection and to each of the members of the
collection that satisfy the depth constraint.
10.5.1 Example - SET-TARGET
>>REQUEST
SET-TARGET /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:set-target xmlns:D="DAV:">
<D:label-name>stable</D:label-name>
</D:set-target>
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
Clemm, et al. [Page 30]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
In this example, the version selected by the "stable" label is made
the target of the version selector, /foo.html. Note that
subsequently moving the "stable" label to another version will not
modify the target of /foo.html.
10.6LABEL
A LABEL request can be applied to a version to modify the labels on
that version. Labels are case sensitive, so a server MUST NOT
perform any case folding when storing, retrieving, or comparing
labels.
If a LABEL request is applied to a version selector, the operation
is applied to the target of that version selector.
Marshalling:
The request body MUST be a DAV:label element.
<!ELEMENT label (add|set|remove)>
<!ELEMENT add (label-name)>
<!ELEMENT set (label-name)>
<!ELEMENT remove (label-name)>
<!ELEMENT label-name (#PCDATA)>
PCDATA value: label-string
The request MAY include a Target-Selector header.
The request MAY include a Depth header. If it does include a Depth
header, the response MUST be a 207 Multi-Status.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
<DAV:must-be-version-or-version-selector/>: The request-URL MUST
identify a version or a version selector.
<DAV:must-select-version/>: If a Target-Selector request header is
included and the request-URL identifies a version selector, the
specified label MUST select a version in the version history of the
version selector.
<DAV:must-be-new-label/>: If DAV:add is specified, the specified
label MUST NOT currently select a version of the version history of
that version selector.
<DAV:label-must-exist/>: If DAV:remove is specified, the specified
label MUST select that version.
Postconditions:
Clemm, et al. [Page 31]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
If DAV:add or DAV:set is specified, the specified label selects the
version.
If DAV:remove is specified, the specified label no longer selects
any version of the version history of the version selector.
10.6.1 Example - Setting a label
>>REQUEST
LABEL /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:label xmlns:D="DAV:"> <D:set>
<D:label-name>released</D:label-name>
</D:set> </D:label>
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, the label "released" is applied to the target
version of /foo.html.
11 VERSIONING REPORTS
Versioning introduces the following reports (the REPORT method is
defined in section 9.1).
11.1DAV:version-tree-report
The DAV:version-tree-report describes all the versions of the
version history of a version in the form of a nested tree of
versions. If the report is applied to a checked-in version
selector, it is redirected to the DAV:target of the version
selector.
<!ELEMENT version-tree-report (ANY*)>
The elements of a DAV:property-report identify which properties of
a resource are to be reported. The response body of a DAV:version-
tree-report MUST be a DAV:version-tree element.
<!ELEMENT version-tree (href, prop, version-tree*)>
<!ELEMENT prop (see [RFC2518], section 12.11)>
Clemm, et al. [Page 32]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
A DAV:version-tree element contains a version URL followed by
requested properties and a DAV:version-tree for each successor of
that version.
A server MAY omit the DAV:prop and the successor DAV:version-tree
elements for a version that has already appeared in the
DAV:version-tree report. This can provide significant space
savings when versions have multiple predecessors.
11.1.1 Example - DAV:version-tree-report
The version history drawn below would produce the following version
tree report.
foo.html History
+---+
| | V1
+---+
/ \
/ \
+---+ +---+
| | V2 | | V2.1.1
+---+ +---+
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-tree-report xmlns:D="DAV:">
<D:version-name/>
<D:creator-displayname/>
<D:predecessor-set>
</D:version-tree-report xmlns:D="DAV:">
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-tree xmlns:D="DAV:"/>
<D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
<D:prop>
<D:version-name>V1</D:version-name>
<D:creator-displayname>Fred</D:creator-displayname>
Clemm, et al. [Page 33]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
</D:prop>
<D:version-tree>
<D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
<D:prop>
<D:version-name>V2</D:version-name>
<D:creator-displayname>Fred</D:creator-displayname>
<D:predecessor-set>
<D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
</D:predecessor-set>
</D:prop>
</D:version-tree>
<D:version-tree>
<D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
<D:prop>
<D:version-name>V2.1.1</D:version-name>
<D:creator-displayname>Sally</D:creator-displayname>
<D:predecessor-set>
<D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
</D:predecessor-set>
</D:prop>
</D:version-tree>
</D:version-tree>
12 ADVANCED VERSIONING
12.1Advanced Versioning Terms
Workspace
A "workspace " is a collection that contains a set of related
versionable resources and version selectors.
Clemm, et al. [Page 34]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
Baseline
A baseline is a resource associated with a collection that captures
the target of each version selector that is a member of that
collection (as well as the target of the collection, if it is a
version selector).
In the following diagram, /x/a.html, /x/y/b.html, and /x/y/c.html
are members of /x, and the baseline B1.1 of /x selects versions V1,
V3, and V5.
/x/a.html /x/y/b.html /x/y/c.html
History History History
+---+
| | V2
+---+
|
|
+------------------|-------------------------------+
| | |
| +---+ +---+ +---+ Baseline |
| | | V1 | | V3 | | V5 B1.1 |
| +---+ +---+ +---+ |
| | | |
+------------------|------------|------------------+
| |
| |
+---+ +---+
| | V4 | | V6
+---+ +---+
Clemm, et al. [Page 35]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
Activity
An "activity" is a non-versionable resource that selects a set of
versions that are on a single "line of descent", where a line of
descent is a sequence of versions connected by successor
relationships. If an activity selects versions from multiple
version histories, the versions selected in each version history
must be on a single line of descent. An activity will often
correspond to some unit of work or conceptual change.
The following diagram illustrates activities. Version V5 is the
latest version of foo.html selected by activity Act-2, and version
V8 is the latest version of bar.html selected by activity Act-2.
foo.html History bar.html History
+---+ +---+
Act-1| |V1 Act-1| |V6
+---+ +---+
| |
| |
+---+ +---+
Act-1| |V2 Act-2| |V7
+---+ +---+
/ \ |
/ \ |
+---+ +---+ +---+
Act-1| | Act-2| |V4 Act-2| |V8
+---+ +---+ +---+
| |
| |
+---+ +---+
Act-2| |V5 Act-3| |V9
+---+ +---+
13 ADVANCED VERSIONING SEMANTICS
13.1Workspaces
A workspace is a collection whose members are a set of related
version selectors and unversioned resources. In order to ensure
unambiguous merging and baselining semantics, a workspace may
contain at most one version selector for a given version history
(although a server may support multiple bindings in a workspace to
the same version selector). In order to expose multiple views of a
set of related version selectors in the URL namespace, multiple
workspaces may be used. In order to make a change made to a
version selector in one workspace visible in another workspace,
that version selector must be checked in, and then the
Clemm, et al. [Page 36]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
corresponding version selector in the other workspace can be
updated to display the content and dead properties of the new
version.
Initially, an empty workspace can be created. Versionable
resources can then be added to the workspace with standard WebDAV
requests such as PUT and MKCOL. As resources are identified whose
history should be tracked, they can be put under version control.
Alternatively, a workspace can be initialized by the state of an
existing workspace. In this case, a version selector is created in
the new workspace corresponding to each version selector in the
existing workspace, where corresponding version selectors in
different workspaces will share the same version history.
13.2Baselines
A collection that contains a large number of version selectors can
consume a large amount of space on a server. This can make it
prohibitively expensive to remember the state of an existing
collection by creating a copy of that collection. A "baseline"
resource provides a mechanism to efficiently capture the state of a
collection. In order to allow efficient baseline implementation,
the state of a baseline is limited to be a set of versions, and the
operations on a baseline are limited to the creation of a baseline
from a collection, and restoring or merging the baseline back into
a collection.
13.3Activities, Change Sets, and Branches
It is often desirable to perform several different logical changes
in a single workspace, and then selectively merge a subset of those
logical changes to other workspaces. An "activity" can be used to
represents a single logical change, where an activity tracks all
the resources that were modified to effect that single logical
change. When a version selector is checked out, the author
specifies which activity should be associated with a new version
that will be created when that version selector is checked in. It
is then possible to select a subset of the logical changes for
merging into another workspace, by specifying the appropriate
activities in a MERGE request.
Another common problem is that although a resource under version
control may need to have multiple lines of descent, all work done
by members of a given team must be on a single line of descent (to
avoid merging between team members). An activity resource provides
the mechanism for addressing this problem. When a version selector
is checked out, a client can request that an existing activity be
used or that a new activity be created. Activity semantics then
ensures that all versions in a given version history that are
associated with an activity are on a single line of descent. If
all members of a team share a common activity (or sub-activities of
Clemm, et al. [Page 37]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
a common activity), then all changes made by members of that team
will be on a single line of descent.
Activities appear under a variety of names in existing versioning
systems. When an activity is used to capture a logical change, it
is commonly called a "change set". When an activity is used to
capture a line of descent, it is commonly called a "branch".
13.4Parallel Development and Merging
When an author wants to accept the changes made in another
workspace, it is important to not just select those versions as the
targets of the corresponding version selectors in the author's
workspace, since this would hide any changes made to those version
selectors in the author's workspace. Instead, the versions created
in another workspace should be "merged" into the author's
workspace.
The version history of a version selector provides the information
needed to determine what should be the result of the merge. In
particular, the merge should select whichever version is later in
the line of descent from the initial version. In case the versions
to be merged are on different lines of descent (neither version is
an ancestor of the other), neither version should be selected, but
instead, a new version should be created that contains the logical
merge of the content and dead properties of those versions. The
MERGE request can be used to check out each version selector with
such a conflict, and set the DAV:merge-set property of each
checked-out resource to identify the version to be merged. The
author is responsible for modifying the content and dead properties
of the checked-out resource so that it represents the logical merge
of that version, and then adding that version to the
DAV:predecessor-set of the checked-out resource.
If the server is capable of automatically performing the MERGE, it
MAY update the content, dead properties, and DAV:predecessor-set of
the checked-out resource itself. An automatic merge is indicated
by the absence of a DAV:merge-set. Before checking in the
automatically merged resource, the author is responsible for
verifying that the automatic merge is correct.
13.5Version-Controlled Collections
In order to capture the state of a tree of resources rooted at a
particular collection, it is necessary to capture not only the
state of each leaf resource of the tree, but also the state of each
collection in the tree (including the root collection). In
particular, in order for a baseline to represent the state of a
tree of resources as a set of versions, the set of versions would
have to include a version of each collection in the tree.
Clemm, et al. [Page 38]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
Like a non-collection, when a collection is put under version
control, the collection is replaced by a version selector, and a
history resource is created to contain versions for that version
selector. A collection version selector is virtually
indistinguishable from a non-versioned collection, other than
having to check it out to modify it. In contrast, a collection
version is significantly different from both a collection version
selector and a non-versioned collection.
One difference between a collection version selector and a
collection version is that while a collection version selector
contains bindings to both version controlled and versionable
resources, the only bindings captured by a collection version are
those to version controlled members. This is done both to preserve
standard versioning semantics (a version of a collection should not
be modifiable), but also to provide for significant implementation
optimizations (version history URL's can be used to capture the
state of the collection bindings). A collection version selector
MAY contain bindings to unversioned resources, but these bindings
are not captured in the collection version history, and can be
changed without checking out the collection version selector. This
feature is essential for the support of lock null resources, since
a lock null resource is a temporary member of a collection that
should only exist for the duration of the lock, and should not be
captured in the version history of that collection.
A SET-TARGET or MERGE request can add a binding to collection
version selector that has the same name as an existing binding to a
non-versioned member. In this case, the existing binding takes
precedence and is said to "eclipse" the new binding to a versioned
member. If the existing binding is removed (e.g. by a DELETE or
MOVE), the binding to the versioned member is exposed.
Another difference between a collection version selector and a
collection version is that while a collection version selector
contains bindings to other version selectors, a collection version
does not contain bindings to other versions, but rather contains
bindings to version histories. If, instead, a collection version
contained bindings to other versions, creating a new version of a
resource would require creating a new version of all the
collections that contain that resource, which would cause
activities in a workspace to become entangled. For example,
suppose a "feature-12" activity created a new version of
/x/y/a.html. If a collection version contained bindings to
versions of its members, a new version of /x/y would have to be
created to contain the new version of /x/y/a.html, and a new
version of /x would have to be created to contain the new version
of /x/y. Now suppose a "bugfix-47" activity created a new version
of /x/z/b.html. Again, a new version of /x/z and a new version of
/x would have to be created to contain the new version of
/x/y/b.html. But now it is impossible to merge just "bugfix-47"
into another workspace without "feature-12", because the version of
/x that contains the desired version of /x/z/b.html also contains
version of /x/y/a.html created for "feature-12". But if a
Clemm, et al. [Page 39]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
collection version instead contains bindings to version histories,
changing the version selected by a member of that collection would
not require a new version of the collection (the new version is
still in the same version history so no new collection version is
required), and therefore "feature-12" and "bugfix-47" would not
become entangled.
Clemm, et al. [Page 40]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
In the following example, there are three version histories, named
VH14, VH19, and VH24. The versions of VH14 are collections, and
version V2 of VH14 has two bindings, one named "a" to VH19, and the
other named "b" to VH24. The collection /x is a version selector
for VH14 whose target is V2. The bindings of V2 have induced
corresponding bindings in /x. In particular, /x/a is a version
selector for VH19 (whose target currently is V4), and /x/b is a
version selector for VH24 (whose target currently is V8).
VH19
+---------+
| +---+ |
| | |V4 |
| +---+ |
| | |
| | |
| +---+ |
| | |V5 |
VH14 | +---+ |
+---------+ | | |
| +---+ | | | |
a +---+ | | |V1 | | +---+ |
---->| | Target=V4 | +---+ | a | | |V6 |
/ +---+ | | ------>| +---+ |
/ | | / | +---------+
+---+ | +---+ |
/x | | Target=V2 | | |V2 |
+---+ | +---+ | VH24
\ | | \ | b +---------+
\ b +---+ | | ------>| +---+ |
---->| | Target=V8 | +---+ | | | |V7 |
+---+ | | |V3 | | +---+ |
| +---+ | | | |
+---------+ | | |
| +---+ |
| | |V8 |
| +---+ |
| | |
| | |
| +---+ |
| | |V9 |
| +---+ |
+---------+
13.6Automatic Version Control
Normally, a resource is placed under version control with an
explicit VERSION-CONTROL request. A server MAY automatically place
every new versionable resource under version control. In this
case, the resulting state on the server MUST be the same as if the
Clemm, et al. [Page 41]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
client had explicitly applied a VERSION-CONTROL request to the
versionable resource.
13.7Mutable Versions
Normally, a version cannot be changed and provides a reliable
environment for state recovery, change tracking, stable workspaces,
and merging. If a server supports mutable versions, the client may
request that a checkin should overwrite the version that was
checked out, instead of creating a new version. This can be an
advantage when a simple history is more important than the benefits
provided by an immutable version history, but does introduce a
significant performance penalty in distributed environments,
because the state of a mutable version cannot be reliably cached.
14 ADVANCED VERSIONING PROPERTIES BY RESOURCE TYPE
This section defines the new resource types and properties
introduced by WebDAV advanced versioning.
14.1Version Properties
WebDAV advanced versioning introduces the following properties for
a version:
14.1.1 DAV:version-history (protected)
This property contains a URL for the version history associated
with this version.
<!ELEMENT version-history (href)>
14.1.2 DAV:activity-set
This property contains the URL's for the activities that indicate
on what lines of descent this version appears. A server MAY
restrict the DAV:activity-set to contain a single activity.
<!ELEMENT activity-set (href+)>
14.1.3 DAV:checkout-fork
This property controls the behavior of CHECKOUT when a version
already is checked out or has a successor. If the DAV:checkout-
fork of a version is DAV:forbidden, a CHECKOUT request MUST fail if
it would result in that version appearing in the DAV:predecessor-
set or DAV:checked-out property of more than one version or
checked-out resource. If DAV:checkout-fork is DAV:discouraged,
such a CHECKOUT request MUST fail unless DAV:fork-ok is specified
in the CHECKOUT request body.
Clemm, et al. [Page 42]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
<!ELEMENT checkout-fork (ok|discouraged|forbidden)>
<!ELEMENT ok EMPTY>
<!ELEMENT discouraged EMPTY>
<!ELEMENT forbidden EMPTY>
14.1.4 DAV:checkin-fork
This property controls the behavior of CHECKIN when a version
already has a successor. If the DAV:checkin-fork of a version is
DAV:forbidden, a CHECKIN request MUST fail if it would result in
that version appearing in the DAV:predecessor-set of more than one
version. If DAV:checkin-fork is DAV:discouraged, such a CHECKIN
request MUST fail unless DAV:fork-ok is specified in the CHECKIN
request body.
<!ELEMENT checkin-fork (ok|discouraged|forbidden)>
<!ELEMENT ok EMPTY>
<!ELEMENT discouraged EMPTY>
<!ELEMENT forbidden EMPTY>
14.1.5 DAV:mutable
This property indicates whether the version can be updated by a
CHECKIN with DAV:overwrite.
<!ELEMENT mutable #PCDATA>
PCDATA value: boolean
14.2Version History Properties
The DAV:resourcetype of a version history MUST be DAV:version-
history.
WebDAV advanced versioning introduces the following properties for
a version history:
14.2.1 DAV:version-set (protected)
This property contains a URL for each version of this version
history.
<!ELEMENT version-set (href+)>
14.2.2 DAV:initial-version (protected)
This property contains a URL for the initial version of this
version history.
<!ELEMENT initial-version (href)>
Clemm, et al. [Page 43]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
14.2.3 DAV:latest-version (protected)
This property contains a URL for the version with the latest
DAV:checkin-date in this version history. If the version history
does not maintain DAV:checkin-date properties, no version will be
identified. If multiple versions contain the latest DAV:checkin-
date, the server arbitrarily picks one to identify as the latest.
<!ELEMENT latest-version (href)>
14.3Version Selector Properties
WebDAV advanced versioning introduces the following properties for
a version selector.
14.3.1 DAV:workspace
If the version selector is a member of a workspace, this property
contains a URL that identifies this workspace.
<!ELEMENT workspace (href)>
14.3.2 DAV:merge-set
This property of a checked-out version selector contains a version
URL for each version that is to be merged into this version
selector.
<!ELEMENT merge-set (href*)>
14.3.3 DAV:auto-merge-set
This property of a checked-out version selector contains a version
URL for each version that the server has merged into this version
selector. The client should confirm that the merge has been
performed correctly before moving a version URL from the DAV:auto-
merge-set to the DAV:predecessor-set of a checked-out version
selector.
<!ELEMENT auto-merge-set (href*)>
14.3.4 DAV:unreserved
This property of a checked-out version selector indicates whether
the DAV:activity-set of another checked-out resource associated
with the version history of this version selector can have an
activity that is in the DAV:activity-set property of this checked-
out version selector.
If multiple checked-out resources for a given version history are
checked out unreserved into a single activity, only the first
CHECKIN will succeed. Before the other checked-out resources can
be checked in, the author will have to merge the latest version of
Clemm, et al. [Page 44]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
that activity into the checked-out resource and then modify the
DAV:predecessor-set of that checked-out resource.
<!ELEMENT unreserved (#PCDATA)>
PCDATA value: boolean
14.3.5 DAV:predecessor-set
This property of a checked-out version selector determines the
DAV:predecessor-set property of the version that results from
checking in this version selector. The order of the DAV:href
elements in DAV:predecessor-set MUST be maintained by the server.
14.3.6 DAV:activity-set
This property of a checked-out version selector determines the
DAV:activity-set property of the version that results from checking
in this version selector.
14.3.7 DAV:checkout-fork
This property of a checked-out version selector determines the
DAV:checkout-fork property of the version that results from
checking in this version selector.
14.3.8 DAV:checkin-fork
This property of a checked-out version selector determines the
DAV:checkin-fork property of the version that results from checking
in this version selector.
14.3.9 DAV:mutable
This property of a checked-out version selector determines the
DAV:mutable property of the version that results from checking in
this version selector.
14.4Workspace Properties
The DAV:resourcetype of a workspace MUST be DAV:collection. WebDAV
advanced versioning introduces the following properties for a
workspace:
14.4.1 DAV:current-activity-set
This property identifies the activities that currently are being
performed in this workspace. When a member of this workspace is
checked out, if no activity is specified in the checkout request,
Clemm, et al. [Page 45]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
the DAV:current-activity-set will be used. This allows an
activity-unaware client to update a workspace in which activity
tracking is required. The DAV:current-activity-set MAY be
restricted to contain at most one activity.
<!ELEMENT current-activity-set (href*)>
14.4.2 DAV:baselined-collection-set
This property identifies each member of the workspace that is a
baselined collection (i.e. a collection whose DAV:baseline-selector
property is set).
<!ELEMENT baselined-collection-set (href*)>
14.5Collection Properties
WebDAV advanced versioning introduces the following properties for
a collection:
14.5.1 DAV:baseline-selector (protected)
This property contains the URL of a baseline selector that is used
to track baselines of this collection. A server MAY automatically
assign a DAV:baseline-selector property to a collection when it is
created, or a client can use the BASELINE-CONTROL method to request
that a baseline selector be created for a specified collection.
When the baseline selector of a collection is checked out, it
tracks the target of each version selector that is a member of the
collection (as well as the target of the collection itself, if it
is a version selector). When the baseline selector is checked in,
its state is captured by a new baseline in the baseline history.
<!ELEMENT baseline-selector (href)>
14.6Baseline Properties
The DAV:resourcetype of a baseline MUST be DAV:baseline. WebDAV
advanced versioning introduces the following properties for a
baseline.
14.6.1 DAV:version-set (protected)
This property contains a version URL for each version selected by
the baseline. At most one version of a given version history can
be selected by a baseline's DAV:version-set property.
<!ELEMENT version-set (href*)>
Clemm, et al. [Page 46]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
14.7Activity Properties
The DAV:resourcetype of an activity MUST be DAV:activity. WebDAV
advanced versioning introduces the following properties for an
activity:
14.7.1 DAV:version-set (protected)
This property contains a version URL for each version whose
DAV:activity-set property contains this activity. Multiple
versions of a single version history can be selected by an
activity's DAV:version-set property, but all DAV:version-set
versions from a given version history must be on a single line of
descent from the initial version of that version history.
<!ELEMENT version-set (href*)>
14.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:version-set is extended by the DAV:version-
set of each activity specified in the DAV:subactivity-set. In
particular, the versions in this extended set MUST be on a single
line of descent, and when an activity selects a version for merging
into a workspace, the latest version in this extended set is the
one that will be merged.
<!ELEMENT subactivity-set (href*)>
14.7.3 DAV:current-workspace-set
This property contains a URL for each workspace whose DAV:current-
activity-set contains this activity.
<!ELEMENT current-workspace-set (href*)>
15 ADVANCED VERSIONING HEADERS
15.1Workspace
The following defines the BNF for the Workspace header:
Workspace := "Workspace" ":" URL
A Workspace header provides a convenient mechanism for making
"workspace relative" requests. When a Workspace header is included
in a request, the internal members of that workspace are treated by
that request as if they were internal members of "/". For example,
the following two requests are equivalent:
Clemm, et al. [Page 47]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
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
When a Workspace header is included in a request to create a new
internal members of "/", a new internal member is added to the
workspace instead of "/". For example, the following two requests
are equivalent:
MKCOL /src HTTP/1.1
Host: www.webdav.org
Workspace: /workspace/mywksp
MKCOL /workspace/mywksp/src HTTP/1.1
Host: www.webdav.org
A response to a cacheable request (e.g. GET, PROPFIND) that
includes a Workspace header MUST include an HTTP-1.1 Vary header
containing "Workspace".
16 ADVANCED VERSIONING AND EXISTING METHODS
This section defines the impact of advanced versioning
functionality on existing WebDAV and core versioning methods.
For any request that includes a Workspace header, the request-URL
and the Destination request header URL must be treated as if they
were prefixed with the workspace URL specified in the Workspace
header.
For any method that modifies the bindings of a collection (e.g.
DELETE, MOVE, COPY), when that collection is a collection version
selector and when the binding is to a version selector, the method
MUST fail unless the collection version selector has a DAV:auto-
version property. If the collection version selector has a
DAV:auto-version property, the collection version selector is
checked out, the update is applied to the checked-out collection
version selector, and the checked-out collection version selector
is checked in. This functionality allows a versioning unaware
client to add a version to the collection version history. If any
part of the checkout-update-checkin sequence fails, the server
state preceding the request MUST be restored.
16.1GET
Additional Postconditions:
Clemm, et al. [Page 48]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
If the request-URL identifies a version history, an activity, or a
baseline, the result is undefined.
16.2PUT
Additional Preconditions:
If a PUT creates a new resource and if the server automatically
puts a newly created resource under version control, all
preconditions for VERSION-CONTROL apply to the PUT.
Additional Postconditions:
If the request-URL identifies a version history, an activity, or a
baseline, the result is undefined.
16.3DELETE
Additional Preconditions:
<DAV:cannot-modify-parent-version-selector/>: If the request-URL
identifies a version selector, the DELETE MUST fail when the
collection containing the version selector is a checked-in
collection version selector, unless DAV:auto-version is set for
that collection version selector.
Additional Postconditions:
If the request-URL identifies a version history, the result is
undefined.
16.4MKCOL
Additional Preconditions:
If a server automatically puts a newly created collection under
version control, all preconditions for VERSION-CONTROL apply to the
MKCOL.
If a server automatically puts a newly created collection under
baseline control, all preconditions for BASELINE-CONTROL apply to
the MKCOL.
16.5COPY
Additional Preconditions:
If a server automatically puts a newly created resource under
version control, all preconditions for VERSION-CONTROL apply to the
COPY.
Clemm, et al. [Page 49]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
If a server automatically puts a newly created collection under
baseline control, all preconditions for BASELINE-CONTROL apply to
the COPY.
<DAV:cannot-copy-history/>: If the request-URL identifies a version
history, the request MUST fail. In order to create another version
history with a similar history, the appropriate sequence of
VERSION-CONTROL, CHECKOUT, PUT, PROPPATCH, and CHECKIN requests
must be made.
16.6MOVE
Additional Preconditions:
<DAV:cannot-modify-parent-version-selector/>: If the request-URL
identifies a version selector, the request MUST fail when the
collection containing the version selector is a checked-in
collection version selector, unless DAV:auto-version is set for
that collection version selector.
<DAV:cannot-modify-destination-parent-version-selector/>: If the
request-URL identifies a version selector, the request MUST fail
when the collection containing the destination is a checked-in
collection version selector, unless DAV:auto-version is set for
that collection version selector.
<DAV:cannot-rename-resource/>: If the request-URL identifies a
version history, an activity, or a baseline, the request MUST fail.
16.7VERSION-CONTROL
Additional Preconditions:
<DAV:one-version-selector-per-history-per-workspace/>: If the
DAV:version-control request body identifies a version, and if the
request-URL is a member of a workspace, then there MUST NOT be
another member of that workspace whose DAV:version-history property
specifies the version history that contains that version.
<DAV:cannot-modify-parent-version-selector/>: If the collection
containing the request-URL is a checked-in collection version
selector, the request MUST fail unless DAV:auto-version is set for
that collection version selector.
Additional Postconditions:
If a new version history is created and if the version selector is
a member of a workspace, the DAV:activity-set of the initial
version of the new version history is the DAV:current-activity-set
of that workspace.
Clemm, et al. [Page 50]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
16.8CHECKOUT
When activities are supported, a CHECKOUT request MAY specify a
request activity set in the request body. If the version selector
is a member of a workspace, and no activity is specified in the
request body, the DAV:current-activity-set of the workspace is the
request activity set.
Additional Marshalling:
<!ELEMENT checkout (target?, activity-set?, unreserved?, fork-ok?)>
<!ELEMENT target EMPTY>
<!ELEMENT activity-set (href+ | new)>
<!ELEMENT new EMPTY>
<!ELEMENT unreserved EMPTY>
<!ELEMENT fork-ok EMPTY>
Additional Preconditions:
<DAV:one-checkout-per-activity-per-history/>: If there is a request
activity set, unless DAV:unreserved is specified, another checkout
from a version of that version history MUST NOT select an activity
in that activity set.
<DAV:linear-activity/>: If there is a request activity set, unless
DAV:unreserved is specified, the selected version MUST be a
descendant of all other versions of that version history that
select that activity.
<DAV:no-unreserved-checkout-for-reserved-activity/>: If
DAV:unreserved is specified, all other checked-out resources of
versions in that version history whose DAV:activity-set contains
one of the request activities MUST have a DAV:unreserved property
whose value is "T".
<DAV:checkout-of-version-with-descendant-is-forbidden/>: If the
DAV:checkout-fork property of the version being checked out is
DAV:forbidden, the request MUST fail if a version contains that
version in its DAV:predecessor-set.
<DAV:checkout-of-version-with-descendant-is-discouraged/>: If the
DAV:checkout-fork property of the version being checked out is
DAV:discouraged, the request MUST fail if a version contains that
version in its DAV:predecessor-set unless DAV:fork-ok is specified
in the request.
<DAV:checkout-of-checked-out-version-is-forbidden/>: If the
DAV:checkout-fork property of the version being checked out is
DAV:forbidden, the request MUST fail if a checked-out resource
contains that version in its DAV:checked-out property.
<DAV:checkout-of-checked-out-version-is-discouraged/>: If the
DAV:checkout-fork property of the version being checked out is
DAV:discouraged, the request MUST fail if a checked-out resource
Clemm, et al. [Page 51]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
contains that version in its DAV:checked-out property unless
DAV:fork-ok is specified in the request.
Additional Postconditions:
The DAV:predecessor-set property of the checked-out resource is
initialized to be the DAV:checked-out version.
The DAV:activity-set of the checked-out resource is set as follows:
if DAV:new is specified as the DAV:activity-set in the request
body, then a new activity created by the server is used; otherwise,
if activities are specified in the request body, then those
activities are used; otherwise, if the version selector is a member
of a workspace and the DAV:current-activity-set of the workspace is
set, then those activities are used; otherwise, the DAV:activity-
set of the DAV:checked-out version is used.
If DAV:unreserved was specified in the CHECKOUT request body, then
the DAV:unreserved property of the checked-out resource MUST be
"T".
16.8.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
<?xml version="1.0" encoding="utf-8" ?>
<D:checkout xmlns:D="DAV:">
<D:activity-set>
<D:href>http://repo.webdav.org/act/fix-bug-23</D:href>
</D:activity-set>
</D:checkout>
>>RESPONSE
HTTP/1.1 201 Created
Location: http://www.webdav.org/ws/public/foo.html
In this example, the CHECKOUT is being performed in the
http://repo.webdav.org/act/fix-bug-23 activity.
16.9CHECKIN
Normally, a CHECKIN request will create a new version. If a server
supports mutable versions and if DAV:overwrite is specified, then
instead of creating a new version, CHECKIN will overwrite the value
of the version identified by the DAV:checked-out property of the
checked-out resource.
Clemm, et al. [Page 52]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
Additional Marshalling:
<!ELEMENT checkin (keep-checked-out?, fork-ok?, overwrite?) >
<!ELEMENT keep-checked-out EMPTY>
<!ELEMENT fork-ok EMPTY>
<!ELEMENT overwrite EMPTY>
Additional Preconditions:
<DAV:linear-activity/>: Any version which is in the version history
of the checked-out resource and whose DAV:activity-set contains an
activity from the DAV:activity-set of the checked-out resource MUST
be in the DAV:predecessor-set or an ancestor of a version in the
DAV:predecessor-set of the checked-out resource.
<DAV:merge-must-be-complete/>: The DAV:merge-set and DAV:auto-
merge-set of the checked-out resource MUST be empty.
<DAV:checkin-fork-forbidden/>: A CHECKIN request MUST fail if it
would cause a version whose DAV:checkin-fork is DAV:forbidden to
appear in the DAV:predecessor-set of more than one version.
<DAV:checkin-fork-discouraged/>: A CHECKIN request MUST fail if it
would cause a version whose DAV:checkin-fork is DAV:discouraged to
appear in the DAV:predecessor-set of more than one version, unless
DAV:fork-ok is specified in the CHECKIN request body.
<DAV:only-overwrite-mutable-version/>: If DAV:overwrite is
specified, the request MUST fail unless the DAV:mutable property of
the DAV:checked-out version is "T".
<DAV:predecessor-in-checked-out-version-history/>: The versions
specified in the DAV:predecessor-set of the checked-out resource
MUST be in the same version history as the DAV:checked-out version.
Additional Postconditions:
If the DAV:predecessor-set property of the checked-out resource is
non-empty, the DAV:predecessor-set of the new version is set to
that value instead of the value of the DAV:checked-out property.
The DAV:version-history of the new version is the DAV:version-
history of the DAV:checked-out version.
The DAV:version-set of the version history is updated to include
the new version.
If the checked-out resource was a collection, then the new
collection version contains bindings to the version histories of
the version selector members of the checked-out collection.
The DAV:activity-set of the new version is the DAV:activity-set of
the checked-out resource.
Clemm, et al. [Page 53]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
For each activity in the DAV:activity-set property of the new
version, a version URL for the new version is added to the
DAV:version-set property of that activity.
If DAV:overwrite is specified, a new version is not created, but
instead the content and dead properties of the checked-out resource
replace those of the DAV:checked-out version.
16.10 SET-TARGET
Additional Postconditions:
If the request-URL identifies a baseline selector for a collection,
then the target of each version selector that is a member of that
collection (as well as the target of the collection itself, if the
collection is a version selector) is modified to be the version
selected by that baseline. If no version from the version history
of a version selector is selected by that baseline, that version
selector is deleted.
If the SET-TARGET request modifies the DAV:target of a collection
version selector, then all bindings in that collection version
selector to version selectors are replaced by the bindings
specified by the new target. In particular, bindings are deleted
for version selectors whose version histories are not a member of
the new target version, bindings are renamed for version selectors
whose version histories have been renamed in the new target
version, and bindings are created to version selectors whose
version histories have been added by the new target version. When
a new version selector binding is created, if the version selector
is the member of a workspace and the workspace contains a version
selector for that version history, the binding MUST be a binding to
the existing version selector; otherwise, a new version selector is
created. If no appropriate target version is implied by the
context of the SET-TARGET request, then the target of the new
version selector MUST be set to be the initial version of the
version history.
17 ADVANCED VERSIONING METHODS
17.1MKWORKSPACE
A MKWORKSPACE request creates a new workspace resource. A server
may restrict workspace creation to particular collections, but a
client can determine the location of these collections with a
repository REPORT (see section 18.2).
The MKWORKSPACE request body can be used to initialize the
workspace with version selectors whose targets are the version
selector targets of another specified workspace.
Clemm, et al. [Page 54]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
If a MKWORKSPACE request fails, the server state preceding the
request MUST be restored.
Marshalling:
The request body MUST be a DAV:mkworkspace XML element.
<!ELEMENT mkworkspace (parent-workspace?)>
<!ELEMENT parent-workspace (href)>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
<DAV:resource-must-be-null/>: A resource MUST NOT exist at the
Request-URL.
<DAV:parent-must-be-workspace/>: If a DAV:parent-workspace is
included in the request body, it MUST identify a workspace.
Postconditions:
A new workspace exists at the request-URL.
If the request body contains a DAV:parent-workspace element, for
each version selector that is a member of the parent workspace, a
new version selector with the same DAV:version-history property
will be created in the new workspace. The new version selector
will have the same name relative to the new workspace as the
existing version selector has relative to the parent workspace.
Any collections that are needed in the new workspace to provide the
appropriate name for a version selector will be created.
17.1.1 Example - MKWORKSPACE
>>REQUEST
MKWORKSPACE /ws/public HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, a new workspace is created at
http://www.webdav.org/ws/public.
Clemm, et al. [Page 55]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
17.2MKACTIVITY
A MKACTIVITY request creates a new activity resource. A server may
restrict activity creation to particular collections, but a client
can determine the location of these collections with a repository
REPORT (see section 18.2).
Marshalling:
The response MUST include a Cache-Control:no-cache header.
Preconditions:
<DAV:resource-must-be-null/>: A resource MUST NOT exist at the
request-URL.
Postconditions:
A new activity exists at the request-URL.
17.2.1 Example - MKACTIVITY
>>REQUEST
MKACTIVITY /act/test-23 HTTP/1.1
Host: repo.webdav.org
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, a new activity is created at
http://repo.webdav.org/act/test-23.
17.3BASELINE-CONTROL
A collection can be placed under baseline control with a BASELINE-
CONTROL request. When a collection is placed under baseline
control, the DAV:baseline-selector property of the collection is
set to identify a new baseline selector. This baseline selector
can be checked out and then checked in to create a new baseline for
that collection.
If a baseline history is specified in the BASELINE-CONTROL request
body, the target of the new baseline selector will be the initial
version of that baseline history. If no baseline history is
specified, a new baseline history is created whose initial version
is an empty baseline (i.e. its DAV:version-set is empty).
Marshalling:
Clemm, et al. [Page 56]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
The request body MUST be a DAV:baseline-control XML element.
<!ELEMENT baseline-control (baseline?)>
<!ELEMENT baseline (href)>
Preconditions:
<DAV:must-be-collection/>: The request-URL MUST identify a
collection.
<DAV:baseline-control-must-be-empty/>: The DAV:baseline-control
property of the resource identified by the request-URL MUST be
empty.
<DAV:must-be-baseline/>: The DAV:href of the DAV:baseline element
MUST identify a baseline.
<DAV:one-baseline-selector-per-history-per-workspace/>: If the
request-URL identifies a workspace or a member of a workspace, and
if the DAV:baseline-control element identifies a baseline history,
then there MUST NOT be another member of that workspace whose
DAV:baseline-selector property identifies a baseline selector for
that baseline history.
Postconditions:
A new baseline selector resource is created and associated with the
baseline history specified in the DAV:baseline-control request body
element. If no baseline history is specified in the request body,
a new baseline history with an empty initial version is created at
a server-defined URL.
The DAV:baseline-selector of the collection identifies the new
baseline selector.
The DAV:target of the new baseline selector identifies the initial
baseline of the baseline history.
17.3.1 Example - BASELINE-CONTROL
>>REQUEST
BASELINE-CONTROL /src HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:baseline-control xmlns:D="DAV:">
<D:href>http://repo.webdav.org/his/22</D:href>
</D:baseline-control>
>>RESPONSE
Clemm, et al. [Page 57]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
HTTP/1.1 201 Created
In this example, the collection identified by
http://www.webdav.org/src is placed under baseline control.
17.4MERGE
The MERGE method performs a logical merge of a specified version
into a specified version selector. In general, a MERGE request
specifies a set of versions (the "request versions") and a
collection of version selectors (the "merge destination"), and the
MERGE method is responsible for determining which version selector
in that collection (if any) should be the destination of each
request version.
If the request-URL identifies a version, that version is the
request version.
If the request-URL identifies a version selector, and a Target-
Selector request header is specified, the version selected by that
Target-Selector is the request version; otherwise, the target of
that version selector is the request version. If the request-URL
identifies a collection and a Depth:infinity header is specified,
the target of each version selector in that collection is a request
version.
If the request-URL identifies a baseline, each version selected by
that baseline is a request version.
If the request-URL identifies an activity, then for each version
history containing a version selected by that activity, the latest
version selected by that activity is a request version. Note that
the versions selected by an activity are the versions in its
DAV:version-set unioned with the versions selected by the
activities in its DAV:subactivity-set.
For each request version, the server determines the "merge
destination" for that request version. The merge destination is
the member of the destination collection that is a version selector
whose DAV:target or DAV:checked-out version is in the same version
history as the request version. If a request version has no merge
destination, that request version is reported by the MERGE as
having been ignored.
Marshalling:
The request body MUST be a DAV:merge element.
<!ELEMENT merge (no-auto-merge? prop?)>
<!ELEMENT no-auto-merge EMPTY>
<!ELEMENT prop (see [RFC2518], section 12.11)>
Clemm, et al. [Page 58]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
The request MUST include a Destination header.
The request MAY include a Target-Selector header.
The request MAY include a Depth header.
The response body MUST contain a DAV:merge-response element.
<!ELEMENT merge-response (update-set?, ignored-set?)>
<!ELEMENT update-set (href+|response+)>
<!ELEMENT ignored-set (href+)>
<!ELEMENT response (see [RFC2518], section 12.9.1)>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
<DAV:cannot-merge-checked-out-resource/>: The request-URL MUST NOT
identify a checked-out resource. If the request-URL identifies a
collection, the collection MUST NOT have a member that is a
checked-out resource.
<DAV:merge-destination-must-be-valid />: The Destination header
MUST identify a version selector, a working resource, or a
collection.
<DAV:must-select-version/>: If a Target-Selector request header is
included and the request-URL identifies a version selector, the
specified label MUST select a version in the version history of the
version selector.
<DAV:merge-requires-lock-token> If the MERGE request modifies a
write-locked version selector, 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.
Postconditions:
The result of a merge depends on the relationship between the
request version and it's merge destination.
If the merge destination is a checked-out resource, the request
version is added to the DAV:merge-set of the checked-out resource.
If the merge destination is a version selector whose target is a
descendant of the request version, the merge destination is
unaffected by the MERGE.
If the merge destination is a version selector whose target is an
ancestor of the request version, the DAV:target of the merge
destination is modified to select the request version. The merge
destination URL MUST appear in the DAV:update-set.
Clemm, et al. [Page 59]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
If the merge destination is a version selector whose target is
neither a descendant nor an ancestor of the request version, the
merge destination is checked out and the DAV:merge-set of the
checked-out resource is set to contain the request version. The
merge destination URL MUST appear in the DAV:update-set.
If a request version has no merge destination, the version URL of
the request version MUST appear in the DAV:ignored-set.
If DAV:no-auto-merge is specified in the request body, the request
MUST NOT set or modify the DAV:auto-merge-set property of any
checked-out resource, including ones created by the MERGE request.
If DAV:prop is specified in the request body, the DAV:update-set
MUST contain DAV:response elements, and the properties specified in
the DAV:prop element MUST be reported in the DAV:response elements
in the DAV:update-set.
17.4.1 Example - MERGE
>>REQUEST
MERGE /act/fix-parser-bug HTTP/1.1
Host: repo.webdav.org
Destination: http://www.webdav.org/ws/public
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Cache-Control: no-cache
<?xml version="1.0" encoding="utf-8" ?>
<D:update-set xmlns:D="DAV:">
<D:href>
http://www.webdav.org/ws/public/src/parse.c
</D:href>
<D:href>
http://www.webdav.org/ws/public/src/inc/parse.h
</D:href>
<D:href>
http://www.webdav.org/ws/public/doc/parse.html
</D:href>
</D:update-set>
In this example, the versions selected by the activity,
http://repo.webdav.org/act/fix-parser-bug are merged into the
collection at http://www.webdav.org/ws/public.
Clemm, et al. [Page 60]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
18 ADVANCED VERSIONING REPORTS
Advanced versioning introduces the following reports (the REPORT
method is defined in section 9.1).
18.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.
<!ELEMENT property-report (ANY*)>
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.
18.1.1 Example - DAV:property-report
This example describes how to query a version selector to determine
the DAV:creator-display-name and DAV:activity-set of every version
in the version history of that version selector.
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:property-report xmlns:D="DAV:">
<D:version-history>
<D:version-set>
<D:creator-displayname/>
<D:activity-set/>
</D:version-set>
</D:version-history>
</D:property-report>
Clemm, et al. [Page 61]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/foo.html</D:href>
<D:propstat>
<D:prop>
<D:version-history>
<D:response>
<D:href>http://repo.webdav.org/his/23</D:href>
<D:propstat>
<D:prop>
<D:version-set>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/1<D:href>
<D:propstat>
<D:prop>
<D:creator-displayname>Fred</D:creator-
displayname>
<D:activity-set>
http://repo.webdav.org/act/fix-parser-
bug
</D:activity-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/2<D:href>
<D:propstat>
<D:prop>
<D:creator-displayname>Sally</D:creator-
displayname>
<D:activity-set> <D:href>
http://repo.webdav.org/act/add-refresh-
cmd
</D:href> </D:activity-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:version-set> </D:prop>
</D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:version-history> </D:prop>
</D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:multistatus>
Clemm, et al. [Page 62]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
In this example, the DAV:creator-displayname and DAV:activity-set
properties of the versions in the DAV:version-set of the
DAV:version-history of http://www.webdav.org/foo.html are reported.
18.2DAV:repository-report
Often a versioning implementation requires that workspaces and
activities be located in server specified collections. When such a
constraint exists, the DAV:repository-report can be used to
determine the URL's of these collections.
<!ELEMENT repository-report (workspace|activity)>
<!ELEMENT workspace EMPTY>
<!ELEMENT activity EMPTY>
A DAV:repository-report response is a DAV:repository-set element
that contains a DAV:href for each server-defined collection in
which the specified type of resource can be located. Since
different servers can control different parts of the URL namespace,
the value of a DAV:repository response will depend on the request-
URL. A server MAY allow the client to create sub-collections in
the collections specified in the DAV:repository-set. The
collections specified in the DAV:repository-set MAY be located on
different hosts from the request-URL and each other.
<!ELEMENT repository-set (href*)>
18.2.1 Example - DAV:repository-report
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:repository-report xmlns:D="DAV:">
<D:activity/>
</D:repository-report>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:repository-set xmlns:D="DAV:">
<D:href>http://repo.webdav.org/activity</D:href>
<D:href>http://www.webdav.org/repo/act</D:href>
</D:repository-set>
Clemm, et al. [Page 63]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
In this example, the collections that may contain activities for
http://www.webdav.org/foo.html are identified.
18.3DAV:merge-preview-report
A merge preview describes the changes that would result if the
versions specified by the request-URL were merged into the
destination resource (commonly, a collection). The destination
MUST be specified in a Destination request header.
<!ELEMENT merge-preview-report EMPTY>
A DAV:merge-preview-report response contains a DAV:merge-preview-
response element, which contains the list of version selectors that
would be modified by the merge, and the list of versions ignored by
the merge.
<!ELEMENT merge-preview-response (update-preview-set, ignored-set)>
<!ELEMENT update-preview-set (conflict|update)*)>
<!ELEMENT conflict (href, common-ancestor, contributor,
contributor)>
<!ELEMENT common-ancestor (href)>
<!ELEMENT contributor(href)>
<!ELEMENT update (href, href)>
<!ELEMENT ignored-set (href*)>
The DAV:conflict element contains the URL of a version selector
that requires a merge. It also contains a DAV:common-ancestor for
the conflict, and two DAV:contributor elements for the conflict.
The DAV:common-ancestor element contains a version URL for a
version that is a common ancestor of all the DAV:contributor
elements for a particular conflict. The first DAV:contributor
element contains a version URL for the version selected by the
workspace. The remaining DAV:contributor elements identify the
version selected by the request-URL.
The DAV:update element contains the URL of a version selector whose
target would change as a result of the merge, and contains the
version URL for the new target.
The DAV:ignored-set element contains the version URL's of each
version that would be ignored by the merge.
18.3.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"
Clemm, et al. [Page 64]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge-preview-report xmlns:D="DAV:"/>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:update-preview-set xmlns:D="DAV:">
<D:conflict>
<D:href>http://www.webdav.org/ws/public/foo.html</D:href>
<D:common-ancestor>
<D:href>http://repo.webdav.org/his/23/ver/18</D:href>
</D:common-ancestor>
<D:contributor>
<D:href>http://repo.webdav.org/his/23/ver/42</D:href>
</D:contributor>
<D:contributor>
<D:href>http://repo.webdav.org/his/23/ver/56</D:href>
</D:contributor>
</D:conflict>
<D:update>
<D:href>http://www.webdav.org/ws/public/bar.html</D:href>
<D:href>http://www.repo/his/42/ver/3</D:href>
</D:update>
</D:update-preview-set>
In this example, the resources that would be affected by a merge of
the activity, http://repo.webdav.org/act/fix-it, into the
workspace, http://www.webdav.org/ws, are identified.
18.4DAV:compare-report
A DAV:compare-report identifies the differences between the
resource identified by the request-URL (base) and the resources
specified in the body of the request (contributors). The
comparison is carried out transitively on any children of the
resources according to the value of the Depth header. If the Depth
header is not specified, the value infinity is assumed. Resources
appearing in a contributor but not in the base are described by
DAV:added elements, resources appearing in the base but not a
contributor are described by DAV:deleted elements, and resources
appearing in both base and contributor but having different states
are described by DAV:changed elements. Resource content comparison
is not specified, though servers MAY provide it.
A DAV:compare-report contains the URL's of the resources to be
compared with the resource identified by the request-URL.
Clemm, et al. [Page 65]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
<!ELEMENT compare-report (href+)>
The body of DAV:compare-report response is a DAV:comparison
element, which contains DAV:added, DAV:deleted, and DAV:changed
elements. For example, if a DAV:compare-report is applied to two
baselines, the DAV:compare-report response will contain the
versions that are selected by one baseline but not the other.
<!ELEMENT comparison (added, deleted, changed)*>
<!ELEMENT added (ANY)>
<!ELEMENT deleted (ANY)>
<!ELEMENT changed (ANY)>
A DAV:added element identifies something that appears in a
particular contributor resource but not in the base.
A DAV:deleted element identifies something that appears in the base
resource but not in a particular contributor.
A DAV:changed element identifies information that is in both the
base and the contributor but that has changed in some way. For
example, when two baselines are being compared, a DAV:changed
element will identify a version history if the baselines select
different versions of that version history.
18.4.1 Example - DAV:compare-report
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.foo.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:compare-report xmlns:D="DAV:">
<D:href>http://www.foo.com/myOtherCollection</D:href>
</D:compare-report>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:comparison xmlns:D="DAV:">
<D:added>
<D:href>http://www.foo.com/myOtherCollection</D:href>
</D:added>
<D:added>
<D:href>http://www.foo.com/myOtherCollection/foo.html</D:href>
Clemm, et al. [Page 66]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
</D:added>
<D:deleted>
<D:href>http://www.foo.com/myCollection/bar.html</D:href>
</D:deleted>
</D:comparison>
In this example, the differences between
http://www.foo.com/myCollection and
http://www.foo.com/myOtherCollection are identified.
18.5DAV:version-selector-url-report
The request-URL of this report MUST be a version URL, and the body
of the request MUST identify a workspace.
<!ELEMENT version-selector-url-report (href)>
The result body contains the URL of a version selector that is a
member of the specified workspace, and whose target has the same
DAV:version-history value as the version identified by the request-
URL. If no such version selector is a member of the specified
workspace, a 404 (Not Found) response MUST be returned.
18.5.1 Example - DAV:version-selector-url-report
>>REQUEST
REPORT /his/23/ver/173 HTTP/1.1
Host: repo.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-selector-url-report xmlns:D="DAV:">
<D:href>http://www.webdav.org/ws/public</D:href>
</D:version-selector-url-report>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:href xmlns:D="DAV:">
http://www.webdav.org/ws/public/mycollection/test.html
</D:href>
In this example, the version selector in the workspace,
http://www.webdav.org/ws/public, whose target is a version in the
Clemm, et al. [Page 67]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
version history, http://repo.webdav.org/his/23/ver/173, is
identified.
19 INTERNATIONALIZATION CONSIDERATIONS
This specification has been designed to be compliant with the IETF
Policy on Character Sets and Languages [RFC2277]. Specifically,
where human-readable strings exist in the protocol, either their
charset is explicitly stated, or XML [REC-XML] mechanisms are used
to specify the charset used. Additionally, these human-readable
strings all have the ability to express the natural language of the
string.
Most of the human-readable strings in this protocol appear in
properties, such as DAV:creator-displayname. As defined by the
WebDAV Distributed Authoring Protocol [RFC2518], properties have
their values marshaled as XML. XML has explicit provisions for
character set tagging and encoding, and requires that XML
processors read XML elements encoded, at minimum, using the UTF-8
[RFC2279] encoding of the ISO 10646 multilingual plane. The
charset parameter of the Content-Type header, together with the XML
"encoding" attribute, provide charset identification information
for MIME and XML processors. Proper use of the charset header with
XML is described in [RFC2376]. XML also provides a language
tagging capability for specifying the language of the contents of a
particular XML element. XML uses either IANA registered language
tags (see [RFC1766]) or ISO 639 language tags [ISO639] in the
"xml:lang" attribute of an XML element to identify the language of
its content and attributes.
DeltaV applications, since they build upon WebDAV, are subject to
the internationalization requirements specified in [RFC2518] in
Section 16, Internationalization Considerations. In brief, these
requirements mandate the use of XML character set tagging,
character set encoding, and language tagging capabilities.
Additionally, they strongly recommend reading [RFC2376] for
instruction on the use of MIME media types for XML transport and
the use of the charset header.
Within this specification, a label is a human-readable string that
is marshaled in the Target-Selector header and as XML in request
entity bodies. When used in the Target-Selector header, the value
of the label is encoded using UTF-8.
20 SECURITY CONSIDERATIONS
Security considerations from [RFC2518] are also applicable to
WebDAV Versioning.
Clemm, et al. [Page 68]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
21 AUTHENTICATION
Authentication mechanisms defined in WebDAV will also apply to
WebDAV Versioning.
22 IANA CONSIDERATIONS
This document uses the namespace defined by [RFC2518] for XML
elements. All other IANA considerations from [RFC2518] are also
applicable to WebDAV Versioning.
23 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.
24 ACKNOWLEDGEMENTS
This protocol is the collaborative product of the DeltaV design
team: Jim Amsden (IBM, DeltaV Chair), Boris Bokowski (OTI),
Geoffrey Clemm (Rational), Bruce Cragun (Novell), Jim Doubek
(Macromedia), David Durand (INSO), Tim Ellison (OTI), Henry Harbury
(Merant), Chris Kaler (Microsoft), Jeff McAffer (OTI), Bradley
Sergeant, and Jim Whitehead (UC Irvine). We would like to
acknowledge the foundation laid for us by the authors of the WebDAV
and HTTP protocols upon which this protocol is layered, and the
invaluable feedback from the WebDAV and DeltaV working groups.
Clemm, et al. [Page 69]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
25 REFERENCES
[ISO-639] ISO, "Code for the representation of names of languages",
ISO 639:1988, 1998.
[RFC1766] H.T.Alvestrand, "Tags for the Identification of
Languages", Uninett, 1995.
[RFC2026] S.Bradner, "The Internet Standards Process", Harvard,
1996.
[RFC2119] S.Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", Harvard, 1997.
[RFC2277] H.T.Alvestrand, "IETF Policy on Character Sets and
Languages", BCP 18, Uninett, 1998.
[RFC2279] F.Yergeau, "UTF-9, a transformation format of Unicode and
ISO 10646", Alis Technologies, 1998.
[RFC2376] E.Whitehead, M.Murata, "XML Media Types", U.C.Irvine,
Fuji-Xerox, 1998.
[RFC2396] T.Berners-Lee, R.Fielding, L.Masinter, "Uniform Resource
Identifiers (URI): Generic Syntax", MIT, U.C.Irvine, Xerox, 1998.
[RFC2518] Y.Goland, E.Whitehead, A.Faizi, S.R.Carter, D.Jensen,
"HTTP Extensions for Distributed Authoring - WEBDAV", Microsoft,
U.C.Irvine, Netscape, Novell, 1999.
[RFC2616] R.Fielding, J.Gettys, J.C.Mogul, H.Frystyk, L.Masinter,
P.Leach, and T.Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", U.C.Irvine, Compaq, Xerox, Microsoft, MIT/LCS, 1999.
26 AUTHORS' ADDRESSES
Geoffrey Clemm
Rational Software
20 Maguire Road, Lexington, MA 02421
Email: geoffrey.clemm@rational.com
Jim Amsden
IBM
3039 Cornwallis, Research Triangle Park, NC 27709
Email: jamsden@us.ibm.com
Christopher Kaler
Microsoft
One Microsoft Way, Redmond, WA 90852
Email: ckaler@microsoft.com
Jim Whitehead
University of California, Irvine
Clemm, et al. [Page 70]
INTERNET-DRAFT WebDAV Versioning September 30, 2000
Irvine, CA 92697
Email:ejw@ics.uci.edu
Clemm, et al. [Page 71]
