ANY value: A sequence of elements with at most one
DAV:workspace-collection-set element.
<!ELEMENT workspace-collection-set (href*)>
If DAV:workspace-collection-set is included in the request body,
the response body for a successful request MUST contain a
DAV:workspace-collection-set element identifying collections that
may contain workspaces. An identified collection MAY be the root
collection of a tree of collections, all of which may contain
workspaces. Since different servers can control different parts
of the URL namespace, different resources on the same host MAY
have different DAV:workspace-collection-set values. The
identified collections MAY be located on different hosts from the
resource.
6.4.1 Example - OPTIONS
>>REQUEST
OPTIONS /doc HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:version-history-collection-set/>
<D:workspace-collection-set/>
</D:options>
>>RESPONSE
HTTP/1.1 200 OK
DAV: 1
DAV: version-control,checkout-in-place,version-history,workspace
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options-response xmlns:D="DAV:">
<D:version-history-collection-set>
<D:href>http://repo.webdav.org/his</D:href>
</D:version-history-collection-set>
<D:workspace-collection-set>
<D:href>http://www.webdav.org/public/ws</D:href>
<D:href>http://www.webdav.org/private/ws</D:href>
</D:workspace-collection-set>
</D:options-response>
In this example, the server indicates that it provides Class 1 DAV
support and basic-server-workspace versioning support. In addition,
the server indicates the requested locations of the version history
resources and the workspace resources.
6.5 Additional DELETE Semantics
Additional Postconditions:
(DAV:delete-workspace-members): If a workspace is deleted, any
resource that identifies that workspace in its DAV:workspace
property MUST be deleted.
6.6 Additional MOVE Semantics
Additional Postconditions:
(DAV:workspace-member-moved): If the request-URL did not identify
a workspace, the DAV:workspace of the destination MUST have been
updated to have the same value as the DAV:workspace of the parent
collection of the destination.
(DAV:workspace-moved): If the request-URL identified a workspace,
any reference to that workspace in a DAV:workspace property MUST
have been updated to refer to the new location of that workspace.
6.7 Additional VERSION-CONTROL Semantics
A VERSION-CONTROL request can be used to create a new version-
controlled resource for an existing version history. This allows the
creation of version-controlled resources for the same version history
in multiple workspaces.
Additional Marshalling:
<!ELEMENT version-control ANY>
ANY value: A sequence of elements with at most one DAV:version
element.
<!ELEMENT version (href)>
Additional Preconditions:
(DAV:cannot-add-to-existing-history): If the DAV:version-control
request body element contains a DAV:version element, the request-
URL MUST NOT identify a resource.
(DAV:must-be-version): The DAV:href of the DAV:version element
MUST identify a version.
(DAV:one-version-controlled-resource-per-history-per-workspace):
If the DAV:version-control request body specifies a version, and
if the request-URL is a member of a workspace, then there MUST NOT
already be a version-controlled member of that workspace whose
DAV:checked-in or DAV:checked-out property identifies any version
from the version history of the version specified in the request
body.
Additional Postconditions:
(DAV:new-version-controlled-resource): If the request-URL did NOT
identify a resource, a new version-controlled resource exists at
the request-URL whose content and dead properties are initialized
by those of the version in the request body, and whose
DAV:checked-in property identifies that version.
6.7.1 Example - VERSION-CONTROL (using an existing version history)
>>REQUEST
VERSION-CONTROL /ws/public/bar.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-control xmlns:D="DAV:">
<D:version>
<D:href>http://repo.webdav.org/his/12/ver/V3</D:href>
</D:version>
</D:version-control>
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, a new version-controlled resource is created at
/ws/public/bar.html. The content and dead properties of the new
version-controlled resource are initialized to be the same as those
of the version identified by http://repo.webdav.org/his/12/ver/V3.
7 UPDATE Feature
The update feature provides a mechanism for changing the state of a
checked-in version-controlled resource to be that of another version
from the version history of that resource.
7.1 UPDATE Method
The UPDATE method modifies the content and dead properties of a
checked-in version-controlled resource (the "update target") to be
those of a specified version (the "update source") from the version
history of that version-controlled resource.
The response to an UPDATE request identifies the resources modified
by the request, so that a client can efficiently update any cached
state it is maintaining. Extensions to the UPDATE method allow
multiple resources to be modified from a single UPDATE request (see
Section 12.13).
Marshalling:
The request body MUST be a DAV:update element.
<!ELEMENT update ANY>
ANY value: A sequence of elements with at most one DAV:version
element and at most one DAV:prop element.
<!ELEMENT version (href)>
prop: see RFC2518, Section 12.11
The response for a successful request MUST be a 207 Multi-Status,
where the DAV:multistatus XML element in the response body
identifies all resources that have been modified by the request.
multistatus: see RFC2518, Section 12.9
The response MUST include a Cache-Control:no-cache header.
Postconditions:
(DAV:update-content-and-properties): If the DAV:version element in
the request body identified a version that is in the same version
history as the DAV:checked-in version of a version-controlled
resource identified by the request-URL, then the content and dead
properties of that version-controlled resource MUST be the same as
those of the version specified by the DAV:version element, and the
DAV:checked-in property of the version-controlled resource MUST
identify that version. The request-URL MUST appear in a
DAV:response element in the response body.
(DAV:report-properties): If DAV:prop is specified in the request
body, the properties specified in the DAV:prop element MUST be
reported in the DAV:response elements in the response body.
7.1.1 Example - UPDATE
>>REQUEST
UPDATE /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:update xmlns:D="DAV:">
<D:version>
<D:href>http://repo.webdav.org/his/23/ver/33</D:href>
</D:version>
</D:update>
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Cache-Control: no-cache
<?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:status>HTTP/1.1 200 OK</D:status>
</D:response>
In this example, the content and dead properties of
http://repo.webdav.org/his/23/ver/33 are copied to the version-
controlled resource /foo.html, and the DAV:checked-in property of
/foo.html is updated to refer to
http://repo.webdav.org/his/23/ver/33.
7.2 Additional OPTIONS Semantics
If the server supports the update feature, it MUST include "update"
as a field in the DAV response header from an OPTIONS request on any
resource that supports any versioning properties, reports, or
methods.
8 Label Feature
A version "label" is a string that distinguishes one version in a
version history from all other versions in that version history. A
label can automatically be assigned by a server, or it can be
assigned by a client in order to provide a meaningful name for that
version. A given version label can be assigned to at most one
version of a given version history, but client assigned labels can be
reassigned to another version at any time. Note that although a
given label can be applied to at most one version from the same
version history, the same label can be applied to versions from
different version histories.
For certain methods, if the request-URL identifies a version-
controlled resource, a label can be specified in a Label request
header (see Section 8.3) to cause the method to be applied to the
version selected by that label from the version history of that
version-controlled resource.
8.1 Additional Version Properties
The label feature introduces the following REQUIRED property for a
version.
8.1.1 DAV:label-name-set (protected)
This property contains the labels that currently select this version.
<!ELEMENT label-name-set (label-name*)>
<!ELEMENT label-name (#PCDATA)>
PCDATA value: string
8.2 LABEL Method
A LABEL request can be applied to a version to modify the labels that
select that version. The case of a label name MUST be preserved when
it is stored and retrieved. When comparing two label names to decide
if they match or not, a server SHOULD use a case-sensitive URL-
escaped UTF-8 encoded comparison of the two label names.
If a LABEL request is applied to a checked in version-controlled
resource, the operation MUST be applied to the DAV:checked-in version
of that version-controlled resource.
Marshalling:
The request body MUST be a DAV:label element.
<!ELEMENT label ANY>
ANY value: A sequence of elements with at most one DAV:add,
DAV:set, or DAV:remove element.
<!ELEMENT add (label-name)>
<!ELEMENT set (label-name)>
<!ELEMENT remove (label-name)>
<!ELEMENT label-name (#PCDATA)>
PCDATA value: string
The request MAY include a Label header.
The request MAY include a Depth header. If no Depth header is
included, Depth:0 is assumed. Standard depth semantics apply, and
the request is applied to the collection identified by the
request-URL and to all members of the collection that satisfy the
Depth value. If a Depth header is included and the request fails
on any resource, the response MUST be a 207 Multi-Status that
identifies all resources for which the request has failed.
If a response body for a successful request is included, it MUST
be a DAV:label-response XML element.
<!ELEMENT label-response ANY>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:must-be-checked-in): If the request-URL identifies a
version-controlled resource, the version-controlled resource MUST
be checked in.
(DAV:must-select-version-in-history): If a Label request header is
included and the request-URL identifies a version-controlled
resource, the specified label MUST select a version in the version
history of the version-controlled resource.
(DAV:add-must-be-new-label): If DAV:add is specified in the
request body, the specified label MUST NOT appear in the
DAV:label-name-set of any version in the version history of that
version-controlled resource.
(DAV:label-must-exist): If DAV:remove is specified in the request
body, the specified label MUST appear in the DAV:label-name-set of
that version.
Postconditions:
(DAV:add-or-set-label): If DAV:add or DAV:set is specified in the
request body, the specified label MUST appear in the DAV:label-
name-set of the specified version, and MUST NOT appear in the
DAV:label-name-set of any other version in the version history of
that version.
(DAV:remove-label): If DAV:remove is specified in the request
body, the specified label MUST NOT appear in the DAV:label-name-
set of any version in the version history of that version.
8.2.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>default</D:label-name>
</D:set>
</D:label>
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, the label "default" is applied to the DAV:checked-in
version of /foo.html.
8.3 Label Header
For certain methods (e.g. GET, PROPFIND), if the request-URL
identifies a version-controlled resource, a label can be specified in
a Label request header to cause the method to be applied to the
version selected by that label from the version history of that
version-controlled resource.
The value of a label header is the name of a label, encoded using
URL-escaped UTF-8. For example, the label "release B.3" is
identified by the following header:
Label: release%20B.3
A Label header MUST have no effect on a request whose request-URL
does not identify a version-controlled resource. In particular, it
MUST have no effect on a request whose request-URL identifies a
version or a version history.
A server MUST return an HTTP-1.1 Vary header containing Label in a
successful response to a cacheable request (e.g., GET) that includes
a Label header.
8.4 Additional OPTIONS Semantics
If the server supports the label feature, it MUST include "label" as
a field in the DAV response header from an OPTIONS request on any
resource that supports any versioning properties, reports, or
methods.
8.5 Additional GET Semantics
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version-in-history): If a Label request header is
included and the request-URL identifies a version-controlled
resource, the specified label MUST select a version in the version
history of the version-controlled resource.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If the request-URL
identifies a version-controlled resource and a Label request
header is included, the response MUST contain the content of the
specified version rather than that of the version-controlled
resource.
8.6 Additional PROPFIND Semantics
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version-in-history): If a Label request header is
included and the request-URL identifies a version-controlled
resource, the specified label MUST select a version in the version
history of the version-controlled resource.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If the request-URL
identifies a version-controlled resource and a Label request
header is included, the response MUST contain the properties of
the specified version rather than that of the version-controlled
resource.
8.7 Additional COPY Semantics
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version-in-history): If a Label request header is
included and the request-URL identifies a version-controlled
resource, the specified label MUST select a version in the version
history of the version-controlled resource.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If the request-URL
identifies a version-controlled resource and a Label request
header is included, the request MUST have copied the properties
and content of the specified version rather than that of the
version-controlled resource.
8.8 Additional CHECKOUT Semantics
If the server supports the working-resource option, a LABEL header
may be included to check out the version selected by the specified
label.
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version-in-history): If a Label request header is
included and the request-URL identifies a version-controlled
resource, the specified label MUST select a version in the version
history of the version-controlled resource.
(DAV:must-not-have-label-and-apply-to-version): If a Label request
header is included, the request body MUST NOT contain a
DAV:apply-to-version element.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If the request-URL
identifies a checked-in version-controlled resource, and a Label
request header is included, the CHECKOUT MUST have been applied to
the version selected by the specified label, and not to the
version-controlled resource itself.
8.9 Additional UPDATE Semantics
If the request body of an UPDATE request contains a DAV:label-name
element, the update target is the resource identified by the
request-URL, and the update source is the version selected by the
specified label from the version history of the update target.
Additional Marshalling:
<!ELEMENT update ANY>
ANY value: A sequence of elements with at most one DAV:label-name
or DAV:version element (but not both).
<!ELEMENT label-name (#PCDATA)>
PCDATA value: string
The request MAY include a Depth header. If no Depth header is
included, Depth:0 is assumed. Standard depth semantics apply, and
the request is applied to the collection identified by the
request-URL and to all members of the collection that satisfy the
Depth value. If a Depth header is included and the request fails
on any resource, the response MUST be a 207 Multi-Status that
identifies all resources for which the request has failed.
Additional Preconditions:
(DAV:must-select-version-in-history): If the request includes a
DAV:label-name element in the request body, the label MUST select
a version in the version history of the version-controlled
resource identified by the request-URL.
(DAV:depth-update): If the request includes a Depth header,
standard depth semantics apply, and the request is applied to the
collection identified by the request-URL and to all members of the
collection that satisfy the Depth value. The request MUST be
applied to a collection before being applied to any members of
that collection, since an update of a version-controlled
collection might change the membership of that collection.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If a DAV:label-name
element appears in the request body, the content and dead
properties of the version-controlled resource must have been
updated to be those of the version selected by that label.
9 Working-Resource Feature
The working-resource feature provides an alternative to the workspace
feature for supporting parallel development. Unlike the workspace
feature, where the desired configuration of versions and checked-out
resources is maintained on the server, the working-resource feature
maintains the configuration on the client. This simplifies the
server implementation, but does not allow a user to access the
configuration from clients in different physical locations, such as
from another office, from home, or while traveling. Another
difference is that the workspace feature isolates clients from a
logical change that involves renaming shared resources, until that
logical change is complete and tested; with the working resource
feature, all clients use a common set of shared version-controlled
resources and every client sees the result of a MOVE as soon as it
occurs.
If a server supports the working-resource feature but not the
checkout-in-place feature, a CHECKOUT request can only be used to
create a working resource, and cannot be used to check out a
version-controlled resource. If a server supports the checkout-in-
place feature, but not the working-resource feature, a CHECKOUT can
only be used to change the state of a version-controlled resource
from checked-in to checked-out.
9.1 Additional Version Properties
The working-resource feature introduces the following REQUIRED
properties for a version.
9.1.1 DAV:checkout-fork
This property is defined in Section 4.1.1.
9.1.2 DAV:checkin-fork
This property is defined in Section 4.1.2.
9.2 Working Resource Properties
The working-resource feature introduces the following REQUIRED
properties for a working resource. Since a working resource is a
checked-out resource, it also has any property defined in this
document for a checked-out resource.
9.2.1 DAV:auto-update (protected)
This property identifies the version-controlled resource that will be
updated when the working resource is checked in.
<!ELEMENT auto-update (href)>
9.2.2 DAV:checkout-fork
This property is defined in Section 4.2.1.
9.2.3 DAV:checkin-fork
This property is defined in Section 4.2.2.
9.3 CHECKOUT Method (applied to a version)
A CHECKOUT request can be applied to a version to create a new
working resource. The content and dead properties of the working
resource are a copy of the version that was checked out.
Marshalling:
If a request body is included, it MUST be a DAV:checkout XML
element.
<!ELEMENT checkout ANY>
ANY value: A sequence of elements with at most one DAV:apply-to-
version and at most one DAV:fork-ok element.
<!ELEMENT apply-to-version EMPTY>
<!ELEMENT fork-ok EMPTY>
If a response body for a successful request is included,
it MUST be a DAV:checkout-response XML element.
<!ELEMENT checkout-response ANY>
The response MUST include a Location header.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:checkout-of-version-with-descendant-is-forbidden): See
Section 4.3.
(DAV:checkout-of-version-with-descendant-is-discouraged): See
Section 4.3.
(DAV:checkout-of-checked-out-version-is-forbidden): See Section
4.3.
(DAV:checkout-of-checked-out-version-is-discouraged): See Section
4.3.
Postconditions:
(DAV:create-working-resource): If the request-URL identified a
version, the Location response header MUST contain the URL of a
new working resource. The DAV:checked-out property of the new
working resource MUST identify the version that was checked out.
The content and dead properties of the working resource MUST be
copies of the content and dead properties of the DAV:checked-out
version. The DAV:predecessor-set property of the working resource
MUST be initialized to be the version identified by the request-
URL. The DAV:auto-update property of the working resource MUST
NOT exist.
(DAV:create-working-resource-from-checked-in-version): If the
request-URL identified a version-controlled resource, and
DAV:apply-to-version is specified in the request body, the
CHECKOUT is applied to the DAV:checked-in version of the version-
controlled resource, and not the version-controlled resource
itself. A new working resource is created and the version-
controlled resource remains checked-in. The DAV:auto-update
property of the working resource MUST identify the version-
controlled resource.
9.3.1 Example - CHECKOUT of a version
>>REQUEST
CHECKOUT /his/12/ver/V3 HTTP/1.1
Host: repo.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/wr/157
Cache-Control: no-cache
In this example, the version identified by
http://repo.webdav.org/his/12/ver/V3 is checked out, and the new
working resource is located at http://repo.webdav.org/wr/157.
9.4 CHECKIN Method (applied to a working resource)
A CHECKIN request can be applied to a working resource to produce a
new version whose content and dead properties are a copy of those of
the working resource. If the DAV:auto-update property of the working
resource was set because the working resource was created by applying
a CHECKOUT with the DAV:apply-to-version flag to a version-controlled
resource, the CHECKIN request will also update the content and dead
properties of that version-controlled resource to be those of the new
version.
Marshalling:
If a request body is included, it MUST be a DAV:checkin XML
element.
<!ELEMENT checkin ANY>
ANY value: A sequence of elements with at most one DAV:fork-ok
element.
<!ELEMENT fork-ok EMPTY>
If a response body for a successful request is included, it MUST
be a DAV:checkin-response XML element.
<!ELEMENT checkin-response ANY>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:must-be-checked-out): See Section 4.4.
(DAV:version-history-is-tree) See Section 4.4.
(DAV:checkin-fork-forbidden): See Section 4.4.
(DAV:checkin-fork-discouraged): See Section 4.4.
(DAV:no-overwrite-by-auto-update): If the DAV:auto-update property
for the checked-out resource identifies a version-controlled
resource, at least one of the versions identified by the
DAV:predecessor-set property of the checked-out resource MUST
identify a version that is either the same as or a descendant of
the version identified by the DAV:checked-in property of that
version-controlled resource.
Postconditions:
(DAV:create-version): See Section 4.4.
(DAV:initialize-version-content-and-properties): See Section 4.4.
(DAV:auto-update): If the DAV:auto-update property of the
checked-out resource identified a version-controlled resource, an
UPDATE request with the new version MUST have been applied to that
version-controlled resource.
(DAV:delete-working-resource): If the request-URL identifies a
working resource and if DAV:keep-checked-out is not specified in
the request body, the working resource is deleted.
9.4.1 Example - CHECKIN of a working resource
>>REQUEST
CHECKIN /wr/157 HTTP/1.1
Host: repo.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/his/23/ver/15
Cache-Control: no-cache
In this example, the working resource /wr/157 checked in, and a new
version is created at http://repo.webdav.org/his/23/ver/15.
9.5 Additional OPTIONS Semantics
If the server supports the working-resource feature, it MUST include
"working-resource" as a field in the DAV response header from an
OPTIONS request on any resource that supports any versioning
properties, reports, or methods.
9.6 Additional COPY Semantics
Additional Postconditions:
(DAV:copy-creates-new-resource): The result of copying a working
resource is a new non-version-controlled resource at the
destination of the COPY. The new resource MAY automatically be
put under version control, but the resulting version-controlled
resource MUST be associated with a new version history created for
that new version-controlled resource.
9.7 Additional MOVE Semantics
Additional Preconditions:
(DAV:cannot-rename-working-resource): If the request-URL
identifies a working resource, the request MUST fail.
Additional Postconditions:
(DAV:update-auto-update): If the request-URL identified a
version-controlled resource, any DAV:auto-update properties that
identified that version-controlled resource MUST have been updated
to contain the new location of that version-controlled resource.
10 Advanced Versioning Features
Advanced versioning addresses the problems of parallel development
and configuration management of multiple sets of interrelated
resources. Traditionally, artifacts of software development,
including requirements, design documents, code, and test cases, have
been a focus of configuration management. Web sites, comprising
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
advanced versioning capabilities for coordinating concurrent change
provide the infrastructure for efficient and controlled management of
large evolving web sites.
10.1 Advanced Versioning Packages
Although a server MAY support any combination of advanced versioning
features, in order to minimize the complexity of a WebDAV advanced
versioning client, a WebDAV advanced versioning server SHOULD support
one of the following packages:
Advanced-Server-Workspace Package: basic-server-workspace package
plus all advanced features
Advanced-Client-Workspace Package: basic-client-workspace package
plus all advanced features
The advanced-server-workspace package supports advanced versioning
capabilities for a client with no persistent state. The advanced-
client-workspace package supports advanced versioning capabilities
for a client that maintains configuration state on the client. A
server that supports both advanced workspace packages will
interoperate with all versioning clients.
10.2 Advanced Versioning Terms
The following additional terms are used by the advanced versioning
features.
Collection
A "collection" is a resource whose state consists of not only
content and properties, but also a set of named "bindings", where
a binding identifies what RFC2518 calls an "internal member" of
the collection. Note that a binding is not a resource, but rather
is a part of the state of a collection that defines a mapping from
a binding name (a URL segment) to a resource (an internal member
of the collection).
Collection Version Resource
A "collection version resource", or simply "collection version",
captures the dead properties of a version-controlled collection,
as well as the names of its version-controlled bindings (see
Section 14). A version-controlled binding is a binding to a
version-controlled resource. If the checkout-in-place feature is
supported, a collection version can be created by checking out and
then checking in a version-controlled collection. If the
working-resource feature is supported, a collection version can be
created by checking out a collection version (to create a "working
collection") and then checking in the working collection.
Configuration
A "configuration" is a set of resources that consists of a root
collection and all members (not just internal members) of that
root collection that are not members of another configuration.
The root collection is called the "configuration root", and the
members of this set are called the "members of the configuration".
Note that a collection (which is a single resource) is very
different from a configuration (which is a set of resources).
Baseline Resource
A "baseline resource", or simply "baseline", of a collection is a
version of the configuration that is rooted at that collection
(see Section 12). In particular, a baseline captures the
DAV:checked-in version of every version-controlled member of that
configuration. Note that a collection version (which captures the
state of a single resource) is very different from a collection
baseline (which captures the state of a set of resources).
Baseline-Controlled Collection
A "baseline-controlled collection" is a collection from which
baselines can be created (see Section 12).
Version-Controlled Configuration Resource
A "version-controlled configuration resource", or simply
"version-controlled configuration", is a special kind of version-
controlled resource that is associated with a baseline-controlled
collection, and is used to create and access baselines of that
collection (see Section 12). When a collection is both version-
controlled and baseline-controlled, a client can create a new
version of the collection by checking out and checking in that
collection, and it can create a new baseline of that collection by
checking out and checking in the version-controlled configuration
of that collection.
Activity Resource
An "activity resource", or simply "activity", is a resource that
selects a set of versions that correspond to a single logical
change, where the versions selected from a given version history
form a single line of descent through that version history (see
Section 13).
11 Merge Feature
When a user wants to accept the changes (new versions) created by
someone else, it is important not just to update the version-
controlled resources in the user's workspace with those new versions,
since this could result in "backing out" changes the user has made to
those version-controlled resources. Instead, the versions created in
another workspace should be "merged" into the user's version-
controlled resources.
The version history of a version-controlled resource provides the
information needed to determine the result of the merge. In
particular, the merge should select whichever version is later in the
line of descent from the root version. In case the versions to be
merged are on different lines of descent (neither version is a
descendant of the other), neither version should be selected, but
instead, a new version should be created that contains the logical
merge of the content and dead properties of those versions. The
MERGE request can be used to check out each version-controlled
resource that requires such a merge, and set the DAV:merge-set
property of each checked-out resource to identify the version to be
merged. The user 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. Before checking in the
automatically merged resource, the user is responsible for verifying
that the automatic merge is correct.
11.1 Additional Checked-Out Resource Properties
The merge feature introduces the following REQUIRED properties for a
checked-out resource.
11.1.1 DAV:merge-set
This property identifies each version that is to be merged into this
checked-out resource.
<!ELEMENT merge-set (href*)>
11.1.2 DAV:auto-merge-set
This property identifies each version that the server has merged into
this checked-out resource. The client should confirm that the merge
has been performed correctly before moving a URL from the DAV:auto-
merge-set to the DAV:predecessor-set of a checked-out resource.
<!ELEMENT auto-merge-set (href*)>
11.2 MERGE Method
The MERGE method performs the logical merge of a specified version
(the "merge source") into a specified version-controlled resource
(the "merge target"). If the merge source is neither an ancestor nor
a descendant of the DAV:checked-in or DAV:checked-out version of the
merge target, the MERGE checks out the merge target (if it is not
already checked out) and adds the URL of the merge source to the
DAV:merge-set of the merge target. It is then the client's
responsibility to update the content and dead properties of the
checked-out merge target so that it reflects the logical merge of the
merge source into the current state of the merge target. The client
indicates that it has completed the update of the merge target, by
deleting the merge source URL from the DAV:merge-set of the checked-
out merge target, and adding it to the DAV:predecessor-set. As an
error check for a client forgetting to complete a merge, the server
MUST fail an attempt to CHECKIN a version-controlled resource with a
non-empty DAV:merge-set.
When a server has the ability to automatically update the content and
dead properties of the merge target to reflect the logical merge of
the merge source, it may do so unless DAV:no-auto-merge is specified
in the MERGE request body. In order to notify the client that a
merge source has been automatically merged, the MERGE request MUST
add the URL of the auto-merged source to the DAV:auto-merge-set
property of the merge target, and not to the DAV:merge-set property.
The client indicates that it has verified that the auto-merge is
valid, by deleting the merge source URL from the DAV:auto-merge-set,
and adding it to the DAV:predecessor-set.
Multiple merge sources can be specified in a single MERGE request.
The set of merge sources for a MERGE request is determined from the
DAV:source element of the MERGE request body as follows:
- If DAV:source identifies a version, that version is a merge
source.
- If DAV:source identifies a version-controlled resource, the
DAV:checked-in version of that version-controlled resource is a
merge source.
- If DAV:source identifies a collection, the DAV:checked-in version
of each version-controlled resource that is a member of that
collection is a merge source.
The request-URL identifies the set of possible merge targets. If the
request-URL identifies a collection, any member of the configuration
rooted at the request-URL is a possible merge target. The merge
target of a particular merge source is the version-controlled or
checked-out resource whose DAV:checked-in or DAV:checked-out version
is from the same version history as the merge source. If a merge
source has no merge target, that merge source is ignored.
The MERGE response identifies the resources that a client must modify
to complete the merge. It also identifies the resources modified by
the request, so that a client can efficiently update any cached state
it is maintaining.
Marshalling:
The request body MUST be a DAV:merge element.
The set of merge sources is determined by the DAV:source element
in the request body.
<!ELEMENT merge ANY>
ANY value: A sequence of elements with one DAV:source element, at
most one DAV:no-auto-merge element, at most one DAV:no-checkout
element, at most one DAV:prop element, and any legal set of
elements that can occur in a DAV:checkout element.
<!ELEMENT source (href+)>
<!ELEMENT no-auto-merge EMPTY>
<!ELEMENT no-checkout EMPTY>
prop: see RFC2518, Section 12.11
The response for a successful request MUST be a 207 Multi-Status,
where the DAV:multistatus XML element in the response body
identifies all resources that have been modified by the request.
multistatus: see RFC2518, Section 12.9
The response to a successful request MUST include a Location
header containing the URL for the new version created by the
checkin.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:cannot-merge-checked-out-resource): The DAV:source element
MUST NOT identify a checked-out resource. If the DAV:source
element identifies a collection, the collection MUST NOT have a
member that is a checked-out resource.
(DAV:checkout-not-allowed): If DAV:no-checkout is specified in the
request body, it MUST be possible to perform the merge without
checking out any of the merge targets.
All preconditions of the CHECKOUT operation apply to the checkouts
performed by the request.
Postconditions:
(DAV:ancestor-version): If a merge target is a version-controlled
or checked-out resource whose DAV:checked-in version or
DAV:checked-out version is the merge source or is a descendant of
the merge source, the merge target MUST NOT have been modified by
the MERGE.
(DAV:descendant-version): If the merge target was a checked-in
version-controlled resource whose DAV:checked-in version was an
ancestor of the merge source, an UPDATE operation MUST have been
applied to the merge target to set its content and dead properties
to be those of the merge source. If the UPDATE method is not
supported, the merge target MUST have been checked out, the
content and dead properties of the merge target MUST have been set
to those of the merge source, and the merge source MUST have been
added to the DAV:auto-merge-set of the merge target. The merge
target MUST appear in a DAV:response XML element in the response
body.
(DAV:checked-out-for-merge): If the merge target was a checked-in
version-controlled resource whose DAV:checked-in version was
neither a descendant nor an ancestor of the merge source, a
CHECKOUT MUST have been applied to the merge target. All XML
elements in the DAV:merge XML element that could appear in a
DAV:checkout XML element MUST have been used as arguments to the
CHECKOUT request. The merge target MUST appear in a DAV:response
XML element in the response body.
(DAV:update-merge-set): If the DAV:checked-out version of the
merge target is neither equal to nor a descendant of the merge
source, the merge source MUST be added to either the DAV:merge-set
or the DAV:auto-merge-set of the merge target. The merge target
MUST appear in a DAV:response XML element in the response body.
If a merge source has been added to the DAV:auto-merge-set, the
content and dead properties of the merge target MUST have been
modified by the server to reflect the result of a logical merge of
the merge source and the merge target. If a merge source has been
added to the DAV:merge-set, the content and dead properties of the
merge target MUST NOT have been modified by the server. If
DAV:no-auto-merge is specified in the request body, the merge
source MUST NOT have been added to the DAV:auto-merge-set.
(DAV:report-properties): If DAV:prop is specified in the request
body, the properties specified in the DAV:prop element MUST be
reported in the DAV:response elements in the response body.
11.2.1 Example - MERGE
>>REQUEST
MERGE /ws/public HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge xmlns:D="DAV:">
<D:source>
<D:href>http://www.webdav.org/ws/dev/sally</D:href>
</D:source>
</D:merge>
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Cache-Control: no-cache
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/ws/public/src/parse.c</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.webdav.org/ws/public/doc/parse.html</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
In this example, the DAV:checked-in versions from the workspace
http://www.webdav.org/ws/dev/sally are merged into the version-
controlled resources in the workspace
http://www.webdav.org/ws/public. The resources
/ws/public/src/parse.c and /ws/public/doc/parse.html were modified by
the request.
11.3 DAV:merge-preview Report
A merge preview describes the changes that would result if the
versions specified by the DAV:source element in the request body were
to be merged into the resource identified by the request-URL
(commonly, a collection).
Marshalling:
The request body MUST be a DAV:merge-preview XML element.
<!ELEMENT merge-preview (source)>
<!ELEMENT source (href)>
The response body for a successful request MUST be a
DAV:merge-preview-report XML element.
<!ELEMENT merge-preview-report
(update-preview | conflict-preview | ignore-preview)*>
A DAV:update-preview element identifies a merge target whose
DAV:checked-in property would change as a result of the MERGE, and
identifies the merge source for that merge target.
<!ELEMENT update-preview (target, version)>
<!ELEMENT target (href)>
<!ELEMENT version (href)>
A DAV:conflict-preview element identifies a merge target that
requires a merge.
<!ELEMENT conflict-preview (target, common-ancestor, version)>
A DAV:common-ancestor element identifies the version that is a
common ancestor of both the merge source and the DAV:checked-in or
DAV:checked-out version of the merge target.
<!ELEMENT common-ancestor (href)>
A DAV:ignore-preview element identifies a version that has no
merge target and therefore would be ignored by the merge.
<!ELEMENT ignore-preview (version)>
11.3.1 Example - DAV:merge-preview Report
>>REQUEST
REPORT /ws/public HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge-preview xmlns:D="DAV:">
<D:source>
<D:href>http://www.webdav.org/ws/dev/fred</D:href>
</D:source>
</D:merge-preview>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge-preview-report xmlns:D="DAV:">
<D:conflict-preview>
<D:target>
<D:href>http://www.webdav.org/ws/public/foo.html</D:href>
</D:target>
<D:common-ancestor>
<D:href>http://repo.webdav.org/his/23/ver/18</D:href>
</D:common-ancestor>
<D:version>
<D:href>http://repo.webdav.org/his/23/ver/42</D:href>
</D:version>
</D:conflict-preview>
<D:update-preview>
<D:target>
<D:href>http://www.webdav.org/ws/public/bar.html</D:href>
</D:target>
<D:version>
<D:href>http://www.repo/his/42/ver/3</D:href>
</D:version>
</D:update-preview>
</D:merge-preview-report>
In this example, the merge preview report indicates that version
/his/23/ver/42 would be merged in /ws/public/foo.html, and version
/his/42/ver/3 would update /ws/public/bar.html if the workspace
http://www.webdav.org/ws/dev/fred was merged into the workspace
http://www.webdav.org/ws/public.
11.4 Additional OPTIONS Semantics
If the server supports the merge feature, it MUST include "merge" as
a field in the DAV response header from an OPTIONS request on any
resource that supports any versioning properties, reports, or
methods.
11.5 Additional DELETE Semantics
Additional Postconditions: