One document matched: draft-ietf-webdav-versioning-00.txt
INTERNET-DRAFT Christopher Kaler,
draft-ietf-webdav-versioning-00.txt Microsoft
Editor
Expires April 26, 1999
October 26, 1998
Versioning Extensions to WebDAV
Status of this Memo
This document is an Internet draft. 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 information as Internet drafts.
Internet Drafts are draft documents valid for a maximum of six
months and can 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 as other than as "work in
progress".
To learn the current status of any Internet draft please check the
"lid-abstracts.txt" listing contained in the Internet drafts shadow
directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ftp.isi.edu (US East coast) or
ftp.isi.edu (US West coast). Further information about the IETF
can be found at URL: http://www.ietf.org/
Distribution of this document is unlimited. Please send comments
to the mailing list at <ietf-dav-versioning@w3.org>, which may be
joined by sending a message with subject "subscribe" to <ietf-dav-
versioning-request@w3.org>.
Discussions of the list are archived at
<URL:http://www.w3.org/Archives/Public/ietf-dav-versioning/>.
Abstract
This document specifies a set of methods, headers, and content-
types composing DAV Versioning extensions, an application of the
HTTP/1.1 protocol to version DAV resources.
Kaler, ed. [Page 1]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
Table of Contents
VERSIONING EXTENSIONS TO WEBDAV...........................1
TABLE OF CONTENTS.........................................2
1.INTRODUCTION...........................................4
1.1. DAV Versioning......................................4
1.2. Relationship to DAV.................................4
1.3. Terms...............................................4
1.4. Definitions.........................................4
1.5. Notational Conventions..............................5
2.BASIC VERSIONING.......................................5
2.1. Discovery...........................................5
2.2. Immutable and Mutable Properties....................6
2.3. Automatic Versioning................................7
2.4. Resource Properties.................................7
2.5. Basic Versioning Headers............................8
2.5.1.Versioning-Support................................8
2.5.2.Revision-Id.......................................8
2.5.3.Merged-From.......................................9
2.6. Checking Out/In Resources...........................9
2.6.1.Checkout..........................................9
2.6.2.Branching Resources..............................11
2.6.3.Checkin..........................................12
2.6.4.Undo Checkout....................................13
2.6.5.Enumeration......................................13
2.7. Default Revision...................................13
2.8. Sharing............................................14
2.9. Collection Versioning..............................15
2.9.1.Default Revisions................................16
2.9.2.Headers..........................................16
2.9.3.Properties.......................................16
2.10.Resource Reports...................................17
2.10.1.Example.........................................17
2.10.2.Default History.................................18
2.10.3.Direct Lineage..................................19
2.10.4.Full Lineage....................................20
3.CONFIGURATIONS........................................21
3.1. Discovery..........................................22
3.2. Creating Configurations............................22
3.3. Configuration Properties...........................24
3.4. Headers............................................25
3.5. Deleting Configurations............................25
3.6. Managing Configuration Content.....................25
3.6.1.Access Using Configurations......................26
3.6.2.Adding Resources to a Configuration..............26
3.6.3.Removing Resources from a Configuration..........26
3.7. Workspace Configurations...........................27
3.7.1.Default Workspace Configurations.................27
3.7.2.Synchronizing Worksapce Configurations...........27
Kaler, ed. [Page 2]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
3.7.3.Condensing Workspace Configurations..............29
3.8. Configuration Reports..............................29
3.8.1.Configuration Derivation.........................30
3.8.2.Configuration Merge Graph........................31
3.9. Resolution Queues..................................31
3.9.1.Discovery........................................32
3.9.2.Obtaining Resolutions............................32
3.9.3.Processing Resolution Items......................32
3.10.Checkin Sets.......................................33
3.10.1.Discovery.......................................33
3.10.2.Usage...........................................34
4.VERSION MAPPING.......................................34
4.1. Discovery..........................................35
4.2. Mapping Configurations.............................35
4.3. Mapping Resource Versions..........................36
5.MISCELLANEOUS FUNCTIONS...............................37
5.1. Destroy............................................37
5.1.1.Discovery........................................37
5.1.2.Usage............................................37
5.1.3.Headers..........................................38
5.1.4.Properties.......................................38
6.THE DAV VERSIONING GRAMMAR............................38
7.INTERNATIONALIZATION CONSIDERATIONS...................38
8.SECURITY CONSIDERATIONS...............................38
9.SCALABILITY...........................................38
10. AUTHENTICATION......................................38
11. IANA CONSIDERATIONS.................................38
12. COPYRIGHT...........................................39
13. INTELLECTUAL PROPERTY...............................39
14. REFERENCES..........................................39
15. AUTHOR'S ADDRESSES..................................39
16. OPEN ISSUES.........................................39
17. CHANGE HISTORY......................................40
Kaler, ed. [Page 3]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
1. INTRODUCTION
1.1. DAV Versioning
This document defines DAV Versioning extensions, an application of
HTTP/1.1 for handling resource versioning in a DAV environment.
[DAVVERREQ] describes the motivation and requirements for DAV
Versioning.
DAV Versioning will minimize the complexity of clients so as to
facilitate widespread deployment of applications capable of
utilizing the DAV services. As well, DAV Versioning supports a
rich level of versioning options for versioning-aware clients.
DAV Versioning consists of:
- Automatic versioning support for HTTP/1.1-based clients,
- Basic versioning for DAV Versioning-aware clients,
- File branching for basic parallel development, and
- Configuration support for sophisticated parallel development.
1.2. Relationship to DAV
DAV Versioning relies on the resource and property model defined by
[WebDAV]. DAV Versioning does not alter this model. Instead, DAV
Versioning allows clients to version and access DAV-modeled
resources and histories.
1.3. Terms
This draft uses the terms defined in [RFC2068], [WebDAV], and
[DAVVERREQ].
1.4. Definitions
The section defines several terms that are used throughout the
document specific to DAV versioning.
Versioned Resource - This refers to a resource that is subject to
versioning
Revision - This refers to a specific version of a versioned
resource
Revision History - This refers to the set of changes to a versioned
resource
Working Resource - This refers to a resource that is an
intermediate revision of a versioned resource. That is, the
Kaler, ed. [Page 4]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
versioned resource has been "checked out" and this is where changes
are made until it is ready to be "checked in". Note that working
resources are not versioned.
1.5. 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].
2. BASIC VERSIONING
The base level of versioning support defined by this specification
includes both automatic versioning and the basic versioning
properties defined for all resources. To support basic versioning,
resources MUST allow for versioning to occur automatically on
selected resources whenever immutable aspects are changed, and
support the properties defined in this section.
Resources that support DAV:versioning MUST also provide additional
versioning semantics for versioning-aware clients. This section
describes these new semantics which include enhancements to
existing DAV methods, new headers, and a new versioning-specific
method.
Although the semantics can vary, most versioning systems support
the notion of indicating intent to modify a document (check-out)
and then submission of the modified version (check-in). Typically
this involves some form of locking (either shared or exclusive).
As well, many systems support the ability to cancel a check-out or
undo a recent check-in. These options are available to the owner
or to the Administrator.
Users can generally enumerate the current check-outs although they
may not be able to determine the user in all cases. Likewise,
users can review check-ins to see the change history. Most systems
allow users to select different versions from the change history
and present a comparison of the versions.
Note that locks are not covered in this specification as they are
addressed by [WebDAV].
2.1. Discovery
The OPTIONS method allows the client to discover if a resource
supports versioning.
The client issues the OPTIONS method against a resource named by
the Request-URI. This is a normal invocation of OPTIONS defined in
Kaler, ed. [Page 5]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
[RFC2068] with an extension. If the client includes the Verify-
Extension header, then the reply includes additional information
beyond that which is defined in [RFC2068].
Using this header with the extension DAV:versioning, clients can
determine what versioning support is available.
The following defines the BNF for the Verify-Extension header:
Verify-Extension := "Verify-Extension" ":" URI-list
URI-list := URI | (URI-list "," URI)
This example shows that the /somefolder resource supports
versioning.
>> Request
OPTIONS /somefolder/ HTTP/1.1
Verify-Extension: DAV:versioning
Host: foobar.com
Content-Length: 0
>> Response
HTTP/1.1 200 OK
Date: Tue, 20 Jan 1998 20:52:29 GMT
Connection: close
Accept-Ranges: none
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF
Verify-Extension: DAV:versioning
Versioning-Support: DAV:basicversioning
Content-Length: 0
The Verify-Extension header in the reply indicates that the server
understood the request with Verify-Extension and that
DAV:versioning is supported. As well, the Versioning-Support
header indicates the level of versioning support provided. The BNF
for this header is provided later in this document.
2.2. Immutable and Mutable Properties
An immutable property is defined as a property that, when changed,
causes a new revision of a versioned resource to be created.
Likewise, a mutable property is a property that can be changed
without having a new revision created.
Resources can support both mutable and immutable properties
although there MAY be restrictions that the mutability is
consistent across all resources.
This specification doesnÆt cover the discovery or management of
property mutability.
Kaler, ed. [Page 6]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
2.3. Automatic Versioning
The DAV:autoversion property indicates if a resource is
automatically versioned when any immutable aspect of it is changed.
Resources with automatic versioning allow HTTP/1.1 clients to have
changes versioned without explicit versioning commands.
Automatic versioning includes the following methods:
- Updates via PUT, MKCOL, COPY, MOVE, or DELETE
- Immutable properties updates via PROPPATCH
2.4. Resource Properties
For resources that support versioning, they MUST support the
following properties using the "DAV:" namespace. Note that 0/1 is
used as a FALSE (0) / TRUE (1) indicator.
DAV:isversioned - 0/1 to indicate if the resource is versionable.
Note that this can be implemented as a read-only property.
DAV:autoversion - 0/1 to indicate if the resource is automatically
versioned when modified. Note that this can be implemented this
as a read-only property.
DAV:revisionid - This is a read-only property that returns a server
determined id for this specific revision of the resource. Every
revision of a resource will have a unique DAV:revisionid. A
revision id may be a URI or it may be an arbitrary server-defined
string. However, it cannot contain the "," character. Because it
is not required to be a URI, the DAV:revisionuri property is
required to obtain a URI for the specific revision of the resource.
DAV:vresourceid - This is a read-only property that returns a
server determined id for the versioned resource. That is, all
revisions of the resource have the same DAV:vresourceid. This MUST
be preserved over MOVE requests.
DAV:previousversionids - This is a read-only property that returns
the server defined id for the previous revision of the resource.
An empty value indicates that there are no previous revisions.
Note that there could be multiple previous versions. If there are
multiple revisions, they are returned as a comma-separated list.
Note that this property returns previous revisions that the server
determines. That is, this does not include user identified merged
revisions.
DAV:nextversionids - This is a read-only property that returns the
server defined id for the next revision of the resource. An empty
value indicates that there is no subsequent revision. Note that
there could be multiple next revisions. If there are multiple
revisions, they are returned as a comma-separated list. Note that
this property returns successor revisions that the server
determines. That is, this does not include user identified merged
revisions.
Kaler, ed. [Page 7]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
DAV:revisionuri - This is a read-only property that returns a URI
for this specific revision.
DAV:revisiondisplayname - This is a read-only property that returns
a string that clients may use to display this revision. This is
often a more user friendly string than DAV:revisionid.
DAV:revisionlabel - This property allows the specification of
textual names that refer to this version of the resource. If there
are multiple labels, they are returned as a comma separated list.
Labels MUST be unique for the versioned resource. That is, no two
revisions of the same versioned resource can have the same
DAV:revisionlabel. As well, DAV:revisionlabel, DAV:revisionid, and
DAV:vresourceid all share the same namespace and there can be no
duplicates. Servers MAY reserve specific portions of this
namespace and return an error if a client uses a reserved name as a
revision label. This property MUST be mutable.
DAV:mergedfrom - This property specifies a comma separated list of
revision ids from which this revision is purported to be derived.
This information is provided and managed by the client.
DAV:revisioncomment - This property contains a client-defined
property associated with the revision. This as a mutable property.
2.5. Basic Versioning Headers
The following sub-sections describe the new version headers that
MUST be supported for resources that support DAV:versioning.
2.5.1. Versioning-Support
The Versioning-Support header specifies the type of versioning that
is available. The following BNF defines this header.
Versioning-Support := "Versioning-Support" ":" URI-list
To support versioning, the URI list MUST include
DAV:basicversioning. Later sections of this document specify other
optional support.
2.5.2. Revision-Id
The Revision-Id header is used to identify a specific revision of a
versioned resource. This header can be specified on all methods
and qualifies the resource named in the method. As well, this
header is included in all replies to indicate the revision of the
versioned resource used or created.
The BNF for this header is as follows.
Revision-Id := "Revision-Id" ":" RID
RID := "*" | ANY
Kaler, ed. [Page 8]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
Clients can specify a DAV:revisionid or any of the
DAV:revisionlabel values to refer to a specific revision of the
resource.
The use of Revision-Id: * is only permitted with PROPFIND to obtain
properties across all revisions of a versioned resource.
2.5.3. Merged-From
When clients use resource branching, they will likely need to
perform merge operations. A merge is the process by which changes
from different versions are combined to produce a new version. It
is likely that clients will want to track this semantic
information. When the Merged-From header is specified on a PUT,
UNLOCK, or PROPPATCH method, it indicates the revision (or
revisions) from which the change is derived. The server tracks
this information and makes it available in the DAV:mergedfrom
property.
Merged-Item := ANY
Merged-List := Merged-Item | (Merged-List "," Merged-Item)
Merged-From := "Merged-From" ":" Merged-List
>>Request
PUT /foo/bar HTTP/1.1
Host: www.foobar.com
Merged-From: VER:FDHJ43058
Content-Type: text/html
Content-Length: xxxx
...
>>Response
HTTP/1.1 200 OK
Content-Length: 0
2.6. Checking Out/In Resources
For versioning-aware clients, more advanced requests allow them to
perform specific versioning operations. These methods are directed
at a specific URI and the body contains XML indicating the action
to take.
If a resource supports DAV:versioning then it MUST support the
LOCK/UNLOCK extensions defined in this section.
2.6.1. Checkout
Using the LOCK method, clients can request resources to be "checked
out". This involves creating a working resource that is not
automatically versioned. Checked out resources must be checked in
or aborted, using the UNLOCK method. The diagram below illustrates
this process:
Kaler, ed. [Page 9]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
Revisions of foo.htm: V1
Checkout is performed: V1
|
+-> Working Resource
Checkin is performed: V1 -> V2
The body XML indicates an optional checkout comment, an optional
user token, and locking actions. Clients specify the checkout lock
in all update operations (e.g., PUT or PROPPATCH) to alter the
working resource.
The working resource will always be DAV:checkout locked. Clients
can choose to make the appropriate scope (DAV:shared,
DAV:exclusive, ...). Optionally, using the DAV:vresoucelockscope
tag, clients can have the versioned resource DAV:checkout locked
for a specified scope (DAV:shared, DAV:exclusive, ...). If a client
requests the versioned resource to be locked, and it cannot be,
then the lock operation MUST fail.
The DAV:checkout lock state is equivalent to the DAV:write lock
state in terms of interoperability with other locks.
Resources SHOULD allow clients to propose a DAV:locktoken in the
LOCK request. If a resource does not accept a clientÆs proposed
lock token, it MUST fail the LOCK request.
>>Request
LOCK /foo/bar HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:lockinfo xmlns:D="DAV:">
<D:locktype><D:checkout/></D:locktype>
<D:comment>checkout comment</D:comment>
<D:owner>client-defined token</D:owner>
<D:lockscope><D:exclusive/></D:lockscope>
<D:vresourcelockscope><D:shared/></D:vresourcelockscope>
</D:lockinfo>
>>Response
HTTP/1.1 201 CREATED
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:prop xmlns:D="DAV:">
<D:lockdiscovery>
<D:activelock>
<D:locktype><D:checkoutlock/></D:locktype>
<D:lockscope><D:exclusive/><D:lockscope>
<D:owner>client-define token</D:owner>
Kaler, ed. [Page 10]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
<D:locktoken>
<D:href>opaquelocktoken:rejrei-43343-rereffre</D:href>
</D:locktoken>
</D:activelock>
</D:lockdiscovery>
</D:prop>
2.6.2. Branching Resources
For more sophisticated clients, basic resource branching is
required. Resource branching means that for a given resource, the
history is not linear. That is, there are different lines of
descent. The diagram below illustrates this.
Revision history V1 -> V2 -> V3
Of foo.htm: |
+-> V1.1 -> V1.2
|
+-> V1.1.1
Individual resource branching is common in many versioning systems
today. Project branching (configurations) are described in a later
section. Note that when a collection is branched, the depth of the
branch is infinity. There is no way to change this.
If a resource supports branching, it MUST return
DAV:resourcebranching in the Versioning-Support header reply from
OPTIONS.
A resource is branched using the LOCK method and the DAV:checkout
lock type. The resource to be branched is specified as the target
URI for the method.
Clients have a choice of three approaches to branching which are
specified with specific tags in the request:
- perform a branch <DAV:branchresource>
- do not branch, error if necessary <DAV:dontbranchresource>
- branch if necessary <DAV:branchallowed>
As well, clients can specify a branch label to identify a created
branch using the DAV:branchlabel tag. The reply MUST include a
Branch-Id header specifying a resource defined branch id or the
specified branch label if a branch is created. The label or id can
be specified in a Branch-Id or Revision-Id header to determine the
revision to access.
>>Request
LOCK /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Content-Type: text/html
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:lockinfo xmlns:D="DAV:">
Kaler, ed. [Page 11]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
<D:branchresource/>
<D:branchlabel>MyBranch</D:branchlabel>
<D:locktype><D:checkout/></D:locktype>
<D:comment>checkout comment</D:comment>
<D:owner>client-defined token</D:owner>
<D:lockscope><D:exclusive/></D:lockscope>
<D:vrsourcelockscope><D:shared/></D:vresourcelockscope>
</D:lockinfo>
>>Response
HTTP/1.1 201 CREATED
Branch-Id: MyBranch
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:prop xmlns:D="DAV:">
<D:lockdiscovery>
<D:activelock>
<D:locktype><D:checkoutlock/></D:locktype>
<D:lockscope><D:exclusive/><D:lockscope>
<D:owner>client-define token</D:owner>
<D:locktoken>
<D:href>opaquelocktoken:rejrei-43343-rereffre</D:href>
</D:locktoken>
</D:activelock>
</D:lockdiscovery>
</D:prop>
When a branch is created, the reply MUST include a Branch-Id
header. The BNF for the header is as follows:
Branch-Id := "Branch-Id" ":" ANY
The Branch-Id can be used anywhere a revision-id is used. When
specified, it indicates that the latest version of the indicated
branch is to be selected as the revision to use for the operation.
2.6.3. Checkin
When the client has completed changes to a resource and wishes it
to become part of the revision history, the client must check in
the resource. This is performed using the UNLOCK method against
the versioned resource with special body tags and identification of
the checkout lock in the header.
>>Request
UNLOCK /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Lock-Token: <opaquelocktoken:rejrei-43343-rereffre>
Content-Type: text/xml
Content-Length: xxx
Kaler, ed. [Page 12]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
<?xml version="1.0" encoding="utf-8" ?>
<D:unlockinfo xmlns:D="DAV:">
<D:comment>checkin comment</D:comment>
</D:unlockinfo>
>>Response
HTTP/1.1 204 CREATED
Revision-Id: VER:FREFRI49349
Content-Length: 0
The reply MUST include the Revision-Id of the newly created
revision.
2.6.4. Undo Checkout
If a client chooses to cancel a checkout request, the UNLOCK method
is used with optional body tags and identification of the checkout
lock.
>>Request
UNLOCK /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Lock-Token: <opaquelocktoken:rejrei-43343-rereffre>
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:unlockinfo xmlns:D="DAV:">
<D:cancelcheckout/>
<D:comment>cancel checkout comment</D:comment>
</D:unlockinfo>
>>Response
HTTP/1.1 200 OK
Content-Length: 0
2.6.5. Enumeration
Clients can enumerate the current checkouts to a resource using the
PROPFIND method and standard lock discovery. All attributes
specified in the lock request (e.g. DAV:comment) MUST be returned
in lock discovery.
2.7. Default Revision
If a Revision-Id (or Branch-Id) header is not specified when
referring to a resource, then the tip (latest) revision (from the
primary branch) is used, unless a default revision has been
identified. To mark a specified revision as the default revision,
clients use the PIN method. Note that PUT or checkin will create
new revisions which will be returned unless a PIN is defined. When
a revision is PINned, new revisions can be created with PUT or
Kaler, ed. [Page 13]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
checkin, but they will not be returned unless they are referenced
explicitly.
Note that branching a resource has no effect on the default
revision of the resource, even if the default revision is branched.
If unpinned, the default revision is the tip revision of the
initial (primary) branch of the versioned resource.
>>Request
PIN /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:pin xmlns:D="DAV:">VER:HT58GHDW49</D:pin>
>>Response
HTTP/1.1 200 OK
Content-Length: 0
>>Request
PIN /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:unpin xmlns:D="DAV:"/>
>>Response
HTTP/1.1 200 OK
Content-Length: 0
It should be noted that setting a default revision may impact
automatic versioning. If a client performs a PUT operation that is
automatically versioned, it MUST fail if a GET will not return the
new version (possibly because of a PIN).
2.8. Sharing
Many versioning systems today provide the ability to have a given
resource visible in multiple parts of the namespace. In these
situations, a resource is shared. That is, changes to the resource
are visible to all versions.
The WebDAV advanced collections adds support for referential
members, however, this is not sufficient for sharing in a
versioning environment because of the requirement to establish
default revisions. Indirect references cannot map to specific
versions for down-level (e.g. HTTP/1.1) clients and direct
references map directly to the shared resource.
Kaler, ed. [Page 14]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
This specification introduces a new type of referential member,
semi-direct. A semi-direct reference is like a direct reference
except that it can have attributes of its own or it can map
directly to the shared resource. By default, when a semi-direct
reference is used in a request, it behaves like a direct reference.
However, if the Pass-Through header is specified on the request
with a value of "*", then the operation is performed against the
semi-direct reference not the object it points to. This is an
extension of the WebDAV advanced collection specification in value
and because the header can be specified with any request against a
semi-direct reference.
In the example below, a semi-direct reference is created.
>>Request
MKREF /bing/bar.htm HTTP/1.1
Host: www.foobar.com
Ref-Target: /foo/bar.htm
Ref-Integrity: DAV:semidirect
Content-Length: 0
>>Response
HTTP/1.1 201 CREATED
...
In the example below, a request is made to a semi-direct reference.
The object that the reference refers to is returned.
>>Request
GET /bing/bar.htm HTTP/1.1
Host: www.foobar.com
Content-Length: 0
In the example below, the semi-direct reference is PINned to a
specific revision.
>>Request
PIN /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Pass-Through: *
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:pin xmlns:D="DAV:">VER:HT58GHDW49</D:pin>
2.9. Collection Versioning
Collections can be versioned just like non-collection resources,
however, there are special situations that must be taken into
account. Collections are versioned in the following ways:
- DonÆt version the collection regardless of the changes.
Kaler, ed. [Page 15]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
- Version the collection only if there is a direct change to the
resource.
- Version the collection if there is a change anywhere under the
collection (i.e., bubble of the changes).
Each collection resource MAY choose the behavior it supports. The
behavior is specified through properties, which resources MAY
choose to make read-only.
The DAV:autoversion property indicates if a collection resource
supports versioning when changes are made to it. The
DAV:autocollectionversion property indicates if the collection
resource supports versioning when changes are made anywhere in the
namespace below it.
2.9.1. Default Revisions
It is up to each collection resource to determine if it supports
default versions. If it doesnÆt, then PIN requests MUST fail. If
a collection resource doesnÆt support versioning, then is MUST also
fail PIN requests.
2.9.2. Headers
If collections are versioned, then clients may choose to access
resources that are part of specific revisions. The Revision-Path
header is used to identify specific revisions that are part of the
"path" to the resource. This header servers as an alternative to
"URL munging". This header can be specified on all methods and
qualifies the resource named in the method.
The BNF for this header is as follows.
Revision-Path := "Revision-Path" ":" Path
Path := PItem | (Path PItem)
PItem := "/" ANY Rev
Rev := | (";" RID)
RID := "*" | ANY | "(" ANY ")"
>>Request
GET /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Revision-Path: /foo;VER:HT58GHDW49/bar.htm;VER:HT58GHDW49
Content-Length: 0
The use of * for a revision is only permitted with PROPFIND to
obtain properties across all revisions of a versioned resource.
2.9.3. Properties
DAV:autocollectionversion - This propertyÆs value (0/1) specifies
if a collection is automatically versioned when its contents
(anywhere under it) change. That is, if /foo/bar.htm is versioned,
Kaler, ed. [Page 16]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
is /foo/ versioned as well. Resources MAY implement this as a
read-only property.
DAV:canautocollectionversion - This propertyÆs value (0/1)
specifies if the resource supports the ability to automatically
version collections when a contained resource changes. This is a
read-only property.
2.10. Resource Reports
Revision history graphs and other reports of a resource are
accessed via PROPFIND. Note that resources MAY support multiple
styles of history and reports. To enumerate the supported history
graphs and reports, clients use PROPFIND and the <DAV:enumreport>
property. The results indicate the different reports which can,
themselves, be requested via PROPFIND.
Note that clients can request properties to be included in reports
by specifying the desired properties inside the DAV:enumreport tag.
For the examples in this section, assume that the resource /foo.htm
has the following revision graph:
Revision history V1 -> V2 -> V3
Of foo.htm: |
+-> V1.1 -> V1.2
|
+-> V1.1.1
Clients have specified the following merge annotations:
- V1.2 is a merge of V1.1 and V1.1.1
- V3 is a merge of V2 and V1.2
As well, the default revision history (those revisions marked as
the default) is as follows:
- V1 (the initial revision was created)
- V2 (a new revision was created)
- V1 (a client changed the default revision)
- V3 (an updated revision was created)
Also, the following labels have been specified:
- V2: Test1
- V1.1: Test2, Good
- V1.2: Tested
Additionally, when the V1.1 branch was created, it was labeled
"MyBranch".
2.10.1. Example
>>Request
Kaler, ed. [Page 17]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
PROPFIND /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:enumreport/>
</D:propfind>
>>Response
...
<D:propfind>
<D:prop>
<D:enumreport>
<D:report><D:href>DAV:defaulthistory</D:href></D:report>
<D:report><D:href>DAV:directlineage</D:href></D:report>
<D:report><D:href>DAV:fulllineage</D:href></D:report>
</D:enumreport>
</D:prop>
</D:propfind>
...
Note that the report styles MUST be specified as DAV:href values.
2.10.2. Default History
Resources MUST support the DAV:defaulthistory report. This
enumerates the historical record of revisions that have been
visible as the default revision of the versioned resource.
Clients can specify the limit parameter to limit the number
revisions returned. By definition, revisions are returned in
reverse chronological order starting with the most recent.
>>Request
PROPFIND /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:enumreport type="DAV:defaulthistory" limit=20/>
</D:propfind>
>>Response
...
<D:propfind>
<D:prop>
<D:enumreport type="DAV:defaulthistory">
<D:revision id="V1" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
Kaler, ed. [Page 18]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
</D:revision>
<D:revision id="V2" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
<D:revisionlabel>Test1</D:revisionlabel>
</D:revision>
<D:revision id="V1" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
</D:revision>
<D:revision id="V3" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
</D:revision>
</D:enumreport>
</D:prop>
</D:propfind>
2.10.3. Direct Lineage
Resources MUST support the DAV:directlineage report. This
enumerates the direct parent revisions of the versioned resource.
This report is from the default revision or the specified revision.
Clients can request that a report be based on the namespace entry
specified, or the associated DAV:vresourceid. Clients use the
scope parameter to specify (name or id).
>>Request
PROPFIND /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Revision-Id: V3
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:enumreport type="DAV:directlineage" scope="name"/>
</D:propfind>
>>Response
...
<D:propfind>
<D:prop>
<D:enumreport type="DAV:directlineage" scope="name">
<D:revision id="V1" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
<D:revision id="V2" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
<D:revisionlabel>Test1</D:revisionlabel>
<D:revision id="V3" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
<D:merge id="V2" vresourceid="VER:FFHJE"/>
<D:merge id="V1.2" vresourceid="VER:FFHJE"/>
</D:revision>
</D:revision>
</D:revision>
Kaler, ed. [Page 19]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
</D:enumreport>
</D:prop>
</D:propfind>
2.10.4. Full Lineage
Resources MUST support the DAV:fulllineage report. This enumerates
the full graph of revisions for this resource.
Clients can request that a report be based on the namespace entry
specified, or the associated DAV:vresourceid. Clients use the
scope parameter to specify (name or id).
>>Request
PROPFIND /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Revision-Id: VER:FHJRH3994
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:enumreport type="DAV:fulllineage" scope="name"/>
</D:propfind>
>>Response
...
<D:propfind>
<D:prop>
<D:enumreport type="DAV:fulllineage" scope="name">
<D:revision id="V1" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
<D:revision id="V2" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
<D:revisionlabel>Test1</D:revisionlabel>
<D:revision id="V3" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
<D:merge id="V2" vresourceid="VER:FFHJE"/>
<D:merge id="V1.2" vresourceid="VER:FFHJE"/>
</D:revision>
<D:revision id="V1.1" vresourceid="VER:FFHJE"
branchid="MyBranch">
<D:revisionlabel>Test2, Good</D:revisionlabel>
<D:revisioncomment>Update it</D:revisioncomment>
<D:revision id="V1.2" vresourceid="VER:FFHJE"
branchid="MyBranch">
<D:revisionlabel>Tested</D:revisionlabel>
<D:revisioncomment>Update it</D:revisioncomment>
<D:merge id="V1.1" vresourceid="VER:FFHJE"/>
<D:merge id="V1.1.1" vresourceid="VER:FFHJE"/>
</D:revision>
<D:revision id="V1.1.1" vresourceid="VER:FFHJE">
<D:revisioncomment>Update it</D:revisioncomment>
</D:revision>
Kaler, ed. [Page 20]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
</D:revision>
</D:revision>
</D:revision>
</D:enumreport>
</D:prop>
</D:propfind>
3. CONFIGURATIONS
Many clients require more sophisticated management and organization
of their versioned data. For this reason, configuration support is
defined as part of this specification.
Configuration management is a large space. This specification
addresses several types of configurations:
- Label: A label configuration is a collection of specific
revisions of selected versioned resources. Changes to the
versioned resources do not effect the contents of the label
configuration.
- Floating Label: A floating label configuration is a collection of
the default revisions of selected versioned resources. When the
default revision of a selected resource changes, the contents of
the floating label configuration is updated automatically. Note
that when a versioned resource is added to a floating level
configuration, the Branch-Id header can be specified. In this
case, the floating label will contain the tip revision the
specified branch.
- Workspace: A workspace configuration is a collection of multiple
revisions of selected versioned resources. As the selected
versioned resources are changed, in the context of the workspace
configuration, the workspace tracks the version history.
Configurations provide a mechanism for organizing resources and
quick access to specific revisions of resources. Clients can
access resources in the context of a configuration. By referencing
a configuration, requests are automatically mapped to the correct
revision of the versioned resource.
Note that servers provide a default workspace configuration. This
is were all resources exist. Clients can request other workspace
configurations to be created and have operations performed within
their context if workspace configurations are supported.
A configuration can be derived from another configuration. That
is, the new configuration is based on the versions in the "parent"
configuration. Optionally, derived configurations can
automatically inherit new versions in the parent configuration
(assuming there are no conflicts). However, a configuration can be
derived from at most one other configuration.
Clients can specify configuration ids wherever a revision id can be
specified. This requests that the default revision for the
specified configuration be used. Requests that include both a
revision id and a configuration id MUST fail if the specified
revision is not part of the specified configuration.
Kaler, ed. [Page 21]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
3.1. Discovery
Configuration support is optional. This example shows that the
/somefolder resource supports configurations.
>> Request
OPTIONS /somefolder/ HTTP/1.1
Verify-Extension: DAV:versioning
Host: foobar.com
Content-Length: 0
>> Response
HTTP/1.1 200 OK
Date: Tue, 20 Jan 1998 20:52:29 GMT
Connection: close
Accept-Ranges: none
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF
Verify-Extension: DAV:versioning
Versioning-Support: DAV:basicversioning, DAV:configurations
Configuration-Types: DAV:Label, DAV:Floating, DAV:Workspace
Configuration-Root: /cfgs/
Content-Length: 0
The Configuration-Types header in the OPTIONS reply indicates the
types of configurations supported. Presence of this header
indicates support for configurations. The BNF for this header is:
Configuration-Types := "Configuration-Types" ":" Ctypes
CTypes := CType | (CTypes "," CType)
CType := "Label" | "Floating" | "Workspace" |
URI
The Configuration-Root header in the OPTIONS reply indicates the
root of the configuration namespace. Note that there could be
multiple configuration roots. The BNF for this headers is:
Configuration-Root := "Configuration-Root" ":" URI-List
3.2. Creating Configurations
Servers maintain configurations in a private portion of the
namespace. The root of this namespace is determined by examining
the OPTIONS reply. All configurations names MUST be unique on a
server. Using the configuration namespace, clients can create and
manage configurations.
Clients create new configurations by issuing the MKCOL method
against the configuration namespace. This requests the server to
create a new configuration.
Kaler, ed. [Page 22]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
When a configuration is created, special tags can be used to define
the characteristics and relationships (e.g. derivations) for the
configuration. The following table enumerates these tags.
Tag Description
<DAV:configurationtype> This tag defines the type
xxx of configuration:
</DAV:configurationtype> DAV:Label, DAV:Floating,
or DAV:Workspace.
<DAV:derivedfrom> This tag allows the client
xxx to specify a URI to
</DAV:derivedfrom> identify another
configuration from which
this new configuration is
to be derived.
<DAV:inheritancetype> The configuration
DAV:Auto automatically inherits
</DAV:inheritancetype> changes from its derived-
from configuration.
Conflicts are recorded in
resolution queues (see
later section).
<DAV:inheritancetype> The configuration inherits
DAV:Manual changes from its derived-
</DAV:inheritancetype> from configuration, but
they are not automatically
inserted into the
configuration. Instead
they are recorded in
resolution queues (see
later section).
<DAV:inheritancetype> The configuration is a
DAV:None snapshot of the current
</DAV:inheritancetype> versions in the derived-
from configuration. There
is no inheritance of
changes. This is the
default type if no type is
specified.
<DAV:basetime>"xxx" The configuration is based
</DAV:basetime> on the current versions in
the derived-from
configuration at the
indicated time. Note that
use of this tag is
incompatible with DAV:Auto
inheritance types and
usage in this way MUST
return an error.
Kaler, ed. [Page 23]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
When a non-derived configuration is created, it contains no
resources. Configurations that are derived from another
configuration include the resources in the derived from
configuration.
The example below illustrates creating a new configuration that is
derived from, and auto-inherits another configuration. For this
example, the root of the configuration namespace has been
determined to be /cfgs.
>>Request
MKCOL /cfgs/ HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:createconfiguration xmlns:D="DAV:">
<D:configurationtype>DAV:Workspace</D:configurationtype>
<D:derivedfrom>http://www.foobar.com/cfgs/DDEJRJ445
</D:derivedfrom>
<D:inherit>Auto</D:inherit>
</D:createconfiguration>
>>Response
HTTP/1.1 201 Created
Location: http://www.foobar.com/cfgs/RYURUS99009
Content-Length: 0
3.3. Configuration Properties
The standard PROPFIND and PROPPATCH methods can be used on the
configuration resource to get and set properties on a
configuration. Configurations MUST provide configuration
properties if configurations are supported. The following list
identifies pre-defined properties that MUST be supported:
DAV:configurationtype - The type of the configuration.
Configurations can choose to make this a read-only property.
DAV:derivedfrom - The configuration from which the configuration is
derived. Configurations can choose to make this a read-only
property.
DAV:inheritancetype - The type of inheritance for the
configuration. Configurations can choose to make this a read-only
property.
DAV:basetime - The base time used to create the configuration.
Configurations can choose to make this a read-only property.
DAV:configurationame - A user-defined display name for the
configuration.
Kaler, ed. [Page 24]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
DAV:defaultconfiguration - This property on the configuration root
identifies the default workspace configuration to use if one is not
specified.
3.4. Headers
To support configurations, two new headers are introduced that can
be used with a variety of the DAV and HTTP methods. The following
list identifies these headers:
Configuration-Id - This header is used to identify the
configuration that is to be used when performing an operation.
For workspace configurations, this can be specified to set default
revisions per-configuration, enumeration of checkouts/checkins
against a specific configuration, or to establish locks specific to
a configuration.
If a configuration is not specified, the default workspace
configuration is used. All servers have a default workspace where
resources reside. The configuration "*" can be specified with
PROPFIND to locate properties irrespective of configuration.
Configuration-Id := "Configuration-Id" ":" (URL | "*")
Note that the configuration id can be used in place of a revision
id. In this case, the revision selected is the default revision of
the versioned resource within the specified configuration.
Target-Configuration - This header is used to specify a target
configuration when dealing with cross-configuration operations.
For example, resources can be copied from one configuration to
another using the Configuration-Id and Target-Configuration headers
with the COPY method.
Target-Configuration := "Target-Configuration" ":" URL
3.5. Deleting Configurations
To delete a configuration, use the location returned from the
configuration creation. Note that configurations SHOULD NOT allow
delete if other configurations are derived from them.
>>Request
DELETE /cfgs/RYURUS99009 HTTP/1.1
Host: www.foobar.com
Content-Length: 0
3.6. Managing Configuration Content
Clients need to be able to access and manage the contents of a
configuration. This is done using the GET, COPY, and DELETE
methods.
Kaler, ed. [Page 25]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
3.6.1. Access Using Configurations
Configurations are maintained as a special collection.
Configurations maintain referential members to all revisions that
are part of the configuration. Consequently, one approach to
enumerating the contents of a configuration is to use PROPFIND to
discover the contents of the collection.
Alternatively, clients can request a specific resource from a
configuration. This approach allows clients to use the URL they
are familiar with. If a client requests a resource that is not
part of a configuration, then an error is returned.
>>Request
GET /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Configuration-Id: /cfgs/DFEE2034
Version-Id: VER:JKGRKJ9094
Content-Length: 0
3.6.2. Adding Resources to a Configuration
Resources are added to a configuration using the COPY method. A
special body tag is used to indicate that the resource is being
added to the configuration.
>>Request
COPY /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Depth: infinity
Configuration-Id: /cfgs/DFEE2034
Target-Configuration: /cfgs/ERRJ3440
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:updateconfiguration xmlns:D="DAV:"/>
If a specific revision is not specified, then the default revision
is copied.
Note that clients can also create referential members within the
configuration collection to add them to the collection.
3.6.3. Removing Resources from a Configuration
Resources are removed from a configuration using the DELETE. The
target URI indicates the resource to delete and the Configuration-
Id header to identify the configuration. The Depth header can be
used to remove collection contents. A special tag is used to
indicate that the resource is being removed from the configuration
(not deleted).
>>Request
Kaler, ed. [Page 26]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
DELETE /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Depth: infinity
Configuration-Id: /cfgs/DFEE2034
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:updateconfiguration xmlns:D="DAV:"/>
Note that clients can also delete referential members within the
configuration collection to remove them from the collection.
3.7. Workspace Configurations
Workspace configurations provide the ability to track multiple
revisions of a resource independent of the resource in other
workspace configurations. This section describes aspects of the
protocol specific to workspace configurations.
3.7.1. Default Workspace Configurations
Clients can establish a default workspace configuration that is to
be used, for all clients, if they do not specify a workspace
configuration. To do this, clients set a property on the
configuration namespace root collection identifying the default
workspace configuration.
>>Request
PROPPATCH /cfgs/ HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop>
<D:defaultconfiguration>/cfgs/RYURUS99009
</D:defaultconfiguration>
</D:prop>
</D:set>
</D:propertyupdate>
3.7.2. Synchronizing Worksapce Configurations
In some scenarios, clients are working on separate workspace
configurations to keep themselves isolated from other team members.
However, they occasionally need to synchronize their workspace
configuration with the derived-from workspace configuration so that
they donÆt get too far out of synchronization. As well, changes
(or entire configurations) can be copied from one workspace
Kaler, ed. [Page 27]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
configuration to another. Both operations are performed using the
COPY method and special body tags.
Clients can request that specific resources are copied by including
the resource tag. If no resources are specified, then all
resources are copied. Note that configurations MAY fail requests
that do not fully synchronize.
The example below shows the synchronization of one configuration
against another. All resources are synchronized.
>>Request
COPY /cfgs/DHFHR99392 HTTP/1.1
Host: www.foobar.com
Destination: http://www.foobar.com/cfgs/RRURU329049
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:configurationsync xmlns:D="DAV:"/>
The example below shows the synchronization of one configuration
against another. The specified resources are synchronized to the
indicated time.
>>Request
COPY /cfgs/DHFHR99392 HTTP/1.1
Host: www.foobar.com
Destination: http://www.foobar.com/cfgs/RRURU329049
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:configurationsync xmlns:D="DAV:">
<D:resource>/foo/bar.htm</resource>
<D:resource>/bing/bop.htm</resource>
<D:basetime>...</D:basetime>
</D:configurationsync>
A synchronization request could result in conflicts. By default,
if conflicts exist, the synchronization fails and the conflicts are
returned (as shown below). To override, clients should include the
<DAV:override/> tag. This tag indicates that the synchronization
should do as much as possible and return any conflicts.
>>Response
TBD - show failure response
...
<D:multistatus>
<D:response>
<D:href> http://www.foobar.com/foo/bar.htm</D:href>
<D:conflict>
<D:conflictid>VER:DJHFH443</D:conflictid>
<D:baseversion>VER:DJHFH443</D:baseversion>
<D:newversion>VER:FDFEE55544</D:newversion>
Kaler, ed. [Page 28]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
</D:conflict>
<D:response>
...
</D:multistatus>
...
The sample response above shows that each conflict includes an ID
and a reference to the resource in conflict. A configuration MAY
choose to restrict operations until conflicts have been resolved.
To inform the configuration that a conflict has been resolved,
clients should include a Conflict-ID header on PUT, PROPPATCH, etc.
methods specifying the ID returned in the synchronization response.
Conflict-ID := "Conflict-ID" ":" URI
It is permitted for servers to refuse (fail) synchronization
requests that do not originate at the root. That is, arbitrary
resources.
3.7.3. Condensing Workspace Configurations
Condensing a configuration means reducing the number of revisions
in a configuration. That is, collapse the changes into a single
revision. This is performed by extending the DELETE method. In
the example below, all but the latest three versions are condensed
into a single revision.
>>Request
DELETE /cfgs/BHFR59593 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:condense xmlns:D="DAV:">
<D:resource>/foo/bar.htm<D:keep>3</D:keep></D:resource>
</D:condense>
Note that the DAV:maxrevisions property can be used to set the
maximum number of revisions that are maintained for a versioned
resource.
If the DAV:revisionid header is specified, the condensing starts
with the specified revision. This means that if a versioned
resource has 10 revisions, revisions 3-6 can be condensed.
Servers MUST fail this request if there are dependencies on
revisions that will be eliminated.
3.8. Configuration Reports
Revision history and configuration dependency graphs are accessed
via PROPFIND. Note that configurations MAY support multiple styles
of history and dependency. To enumerate the supported history
Kaler, ed. [Page 29]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
graphs, clients use PROPFIND and the <DAV:enumreport> property.
The results indicate the different graphs and reports which can,
themselves, be requested via PROPFIND.
>>Request
PROPFIND /cfgs/FHJRH3994 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:enumreport/>
</D:propfind>
>>Response
...
<D:propfind>
<D:prop>
<D:enumreport>
<D:report><D:href>DAV:configurationderivation</D:href>
</D:report>
<D:report><D:href>DAV:configurationmerge</D:href></D:report>
</D:enumreport>
</D:prop>
</D:propfind>
...
Note that the report styles MUST be specified as DAV:href values.
3.8.1. Configuration Derivation
Configurations MUST support the DAV:configurationderivation report.
This enumerates the full derivation of a configuraiton. Note that
the limit parameter can be specified to limit the number of items
returned. By definition the order of the configurations is
immediate predecessor.
>>Request
PROPFIND /cfgs/BHFR59593 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:enumreport type="DAV:configurationderivation" limit=100/>
</D:propfind>
>>Response
...
<D:propfind>
Kaler, ed. [Page 30]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
<D:prop>
<D:enumreport type="DAV:configurationderivation" limit=100>
<D:configuration id="VER:KJFJ444"/>
<D:configuration id="VER:KJFJ445"/>
</D:enumreport>
</D:prop>
</D:propfind>
...
3.8.2. Configuration Merge Graph
Configurations SHOULD support the DAV:configurationmerge report.
This enumerates the derivation of a configuration including merges
from one configuration to another.
>>Request
PROPFIND /cfgs/BHFR59593 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:enumreport type="DAV:configurationmerge"/>
</D:propfind>
>>Response
...
<D:propfind>
<D:prop>
<D:enumreport type="DAV:configurationmerge">
<D:revision id="V1" vresourceid="VER:FFHJE"
configurationid="VER:FJJR344">
<D:revision id="V2" vresourceid="VER:FFHJE"
configurationid="VER:FJJR344">
<D:revision id="V3" vresourceid="VER:FFHJE"
configurationid="VER:FJJR344">
<D:merge id="V2" vresourceid="VER:FFHJE"
configurationid="VER:FJJR344"/>
<D:merge id="V1.2" vresourceid="VER:FFHJE"
configurationid="VER:FJJR344"/>
</D:revision>
</D:revision>
</D:revision>
</D:enumreport>
</D:prop>
</D:propfind>
...
3.9. Resolution Queues
When configurations inherit, there is the potential for conflicts.
Configurations have the option to help clients manage these
Kaler, ed. [Page 31]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
conflicts. However, if they do not, then configurations MUST
return an error if the operation would result in a conflict.
Configurations that help resolve conflicts track and maintain lists
of issues that need to be resolved as a result of actions. These
lists are referred to as resolution queues. Clients can request
the resolution issues and react accordingly. Note that the
configuration only manages the list. That is, the client is
responsible for resolving the issue (or deciding not to) and then
removing the resolution item.
3.9.1. Discovery
Resolution queue support is optional for configurations. Support
for resolution queues is determined by examining the
DAV:resolutionqueue property on a configuration. If this property
is not blank, then the configuration supports a resolution queue at
the specified URL. If this property is blank, then it doesnÆt
support resolution queues.
3.9.2. Obtaining Resolutions
Conflicts can arise against any resource, however, they are always
associated with a configuration. Pending resolutions items are
obtained by examining the resolution queue for a configuration.
The resolution queue is actually a configuration-specific
collection in the DAV namespace. The collection resource
identifying the resolution queue for a configuration is obtained
via the DAV:resolutionqueue property on the configuration. To
enumerate the pending resolutions, clients use PROPFIND to obtain
the resources within the collection.
Each resource within the collection represents a separate
resolution queue item and are named such that a standard ANSI sort
on the resource name will ensure correct temporal ordering.
3.9.3. Processing Resolution Items
Clients can GET the contents of a resolution item. This is an XML
document that describes the action that caused the resolution item
to be created. For example:
<?xml version="1.0" encoding="utf-8" ?>
<D:resolutionitem xmlns:D="DAV:">
<D:resolutionid>http://foobar.com/reso/ZZZZ3493</D:resolutionid>
<D:resource>http:/foo/bar.htm</D:resource>
<D:newversion>DAV:FDFEE55544</D:newversion>
</D:resolutionitem>
Once a client has resolved an issue (or decided to ignore it), the
client is responsible for canceling the resolution item. This is
done using the DELETE method on the resolution item.
>>Request
Kaler, ed. [Page 32]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
DELETE http://foobar.com/reso/ZZZZ3493 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: 0
3.10. Checkin Sets
Clients may desire the ability to track a set of changes as a unit.
That is, create a grouping of related changes. This is achieved
using the MKCOL method to create a special collection. Clients
refer to the checkin set on all checkin (or change) requests. The
server automatically creates a "share" to the newly created
revision in the identified collection.
3.10.1. Discovery
Servers may choose to restrict where checkin sets can be created in
the namespace. Clients can discover this using OPTIONS. The
Checkin-Sets-Root header identifies valid portions in the
namespace. Each header (there can be multiple specified) identify
a root and a depth. The BNF for this header is:
Checkin-Sets-Root:= "Checkin-Sets-Root" ":" URL "," Depth
Depth := "inifinity" | number
Note that if a resourceÆs parent in the namespace has a defined
checkin set root, the resource CANNOT define a separate root for
itself.
This example shows how to discover the checkin set root for the
/somefolder resource.
>> Request
OPTIONS /somefolder/ HTTP/1.1
Verify-Extension: DAV:versioning
Host: foobar.com
Content-Length: 0
>> Response
HTTP/1.1 200 OK
Date: Tue, 20 Jan 1998 20:52:29 GMT
Connection: close
Accept-Ranges: none
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF
Verify-Extension: DAV:versioning
Versioning-Support: DAV:basicversioning, DAV:configurations,
DAV:checkinsets
Checkin-Sets-Root: /, infinity
Content-Length: 0
Kaler, ed. [Page 33]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
3.10.2. Usage
Clients create checkin sets using MKCOL and specify a special body
tag to indicate that a checkin set collection is being created.
>>Request
MKCOL /cs/244 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:checkinset xmlns:D="DAV:"/>
Clients refer to this checkin set using the Checkin-Set header.
The BNF for this header is as follows:
Checkin-Set := "Checkin-Set" ":" URI
The following example illustrates use of checkin sets.
>>Request
UNLOCK /foo/bar HTTP/1.1
Host: www.foobar.com
Lock-Token: <opaquelocktoken:rejrei-43343-rereffre>
Checkin-Set: /cs/244
Content-Type: text/html
Content-Length: xxxx
<D:unlockinfo>
...
</D:unlockinfo>
The following properties MUST be supported on all checkin set
collections:
DAV:closed - This is a true (1) / false (0) property that indicates
if this checkin set can be referenced in CHECKIN requests. When a
checkin set is created, this property is defaulted to 0. Note that
resources MAY choose to disallow clients from setting this property
to 0 once a client has set it to 1.
The following properties MUST be supported on all resources:
DAV:checkinid - This read-only property returns the checkin id
associated with this revision of the resource.
4. VERSION MAPPING
This specification defines headers to specify configurations and
resource versions. However, there are times when clients require a
single URI for when working against configurations or versions.
Version mapping support allows servers to create namespaces that
map to configurations and versions.
Kaler, ed. [Page 34]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
Note that mappings are dynamic. That is, as resources are added,
removed, and modified, the changes are reflected in any active
maps.
4.1. Discovery
Version mapping support is optional. This example shows that the
/cfgs/DFEE2034 configuration supports mapping to the /map/ root in
the namespace.
>> Request
OPTIONS /cfgs/DFEE2034 HTTP/1.1
Verify-Extension: DAV:versioning
Host: foobar.com
Content-Length: 0
>> Response
HTTP/1.1 200 OK
Date: Tue, 20 Jan 1998 20:52:29 GMT
Connection: close
Accept-Ranges: none
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF
Verify-Extension: DAV:versioning
Versioning-Support: DAV:basicversioning, DAV:mapping
Mapping-Root: /map/
Mapping-Styles: DAV:detailedmap, DAV:branchmap, DAV:nestedbranch
Content-Length: 0
The BNF for this OPTIONS header is as follows:
Mapping-Root := "Mapping-Root" ":" URL
Mapping-Styles := "Mapping-Styles" ":" URL-List
Note that multiple Mapping-Root headers is permitted.
4.2. Mapping Configurations
The MKCOL method is used to create namespaces based on a
configuration. When a configuration is mapped to a new namespace,
all elements within the configuration can be directly accessed
within the namespace without requiring the configuration to be
identified in the header.
In the example below, a new namespace is created for accessing the
contents of the /cfgs/DFEE2034 configuration.
>> Request
MKCOL /map/mymap HTTP/1.1
Host: foobar.com
Kaler, ed. [Page 35]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
Configuration-Id: /cfgs/DFEE2034
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:configurationmap xmlns:D="DAV:"/>
>> Response
HTTP/1.1 201 CREATED
Context-Length: 0
4.3. Mapping Resource Versions
The MKCOL method is also used to create namespaces based on a
resourceÆs versions (i.e., its revision graph). When a resource is
mapped, its revision history (revision graph) within the
configuration is made available without requiring the Revision-Id
header. Within the mapped namespace, a hierarchy is created for
the revisions.
However, there are different ways to map the history. Consider the
following revision history of the versioned resource bar.htm:
V1 -> V2 -> V3 (primary branch)
|
+-> V1.1 -> V1.2 ("test" branch)
The following diagrams illustrate possible mappings:
(DAV:detailedmap) (DAV:branchmap) (DAV:nestedbranchmap)
V1 Primary Test Primary
| | | |
+----+--------+ V1 V1.1 +------Test
| | | | | | |
V2 bar.htm V1.1 V2 V1.2 V1 V1.1
| | | | |
+----+ +-----+ V3 V2 V1.2
| | | | |
V3 bar.htm V1.2 bar.htm V3
| |
bar.htm bar.htm
In the example below, a new namespace is created for accessing the
versions of the /foo/bar.htm resource in the /cfgs/DFEE2034
configuration.
>> Request
Kaler, ed. [Page 36]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
MKCOL /map/mymap2 HTTP/1.1
Host: foobar.com
Configuration-Id: /cfgs/DFEE2034
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:revisionmap xmlns:D="DAV:">
<D:href>/foo/bar.htm</D:href>
<D:mapstyle>DAV:detailedmap</D:mapstyle>
</D:revisionmap>
>> Response
HTTP/1.1 201 CREATED
Context-Length: 0
Note that resources MAY support any mapping styles, however, if
they support DAV:detailedmap, DAV:branchmap, or
DAV:nestedbranchmap, they must map as illustrated above.
5. MISCELLANEOUS FUNCTIONS
The following sub-sections detail miscellaneous versioning
functions.
5.1. Destroy
Many version management systems use tombstones to note deleted
items. These systems also support the ability to permanently
destroy tombstones for an object. The DESTROY method provides this
functionality and resources SHOULD support it, but resources are
not required to implement it. Resources MUST return an error for
DESTROY requests that are not honored.
5.1.1. Discovery
Discovery of this feature is determined by seeing if the resource
options include the DESTROY method.
5.1.2. Usage
The DESTROY method is used against a specific resource to
permanently remove it. This is a namespace level-operation. That
is, all resources matching the specified URI are destroyed.
>>Request
DESTROY /foo/bar/x.cpp HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
Kaler, ed. [Page 37]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
Note that this request can be qualified by a configuration.
Requests to DESTROY resources that are in use by other
configurations MAY fail or delay the destruction until all
references are removed.
5.1.3. Headers
Clients may chose to display deleted but not destroyed objects
however they choose. The header keyword Show-Deleted is used to
indicate if deleted items should be included in the GET request.
By default, they are not. Inclusion of "Show-Deleted: Y" indicates
that deleted resources should be included. Using "Show-Deleted: O"
indicates that only resources that have been deleted should be
returned. Using "Show-Deleted: N" indicates that deleted resources
shouldnÆt be returned.
Show-Deleted := "Show-Deleted" ":" ("Y" | "N" | "O")
5.1.4. Properties
DAV:isdeleted - A 0/1 property where 1 indicates that the resource
has been deleted.
6. THE DAV VERSIONING GRAMMAR
To be supplied - Describe and detail the DTDs
7. INTERNATIONALIZATION CONSIDERATIONS
To be supplied.
8. SECURITY CONSIDERATIONS
To be supplied.
9. SCALABILITY
To be supplied.
10. AUTHENTICATION
Authentication mechanisms defined in WebDAV will also apply to DAV
Versioning.
11. IANA CONSIDERATIONS
This document uses the namespace defined by [WebDAV] for XML
elements. All other IANA considerations mentioned in [WebDAV] also
applicable to DAV Versioning.
Kaler, ed. [Page 38]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
12. COPYRIGHT
To be supplied.
13. INTELLECTUAL PROPERTY
To be supplied.
14. REFERENCES
[DAVVERREQ] TBD, "Requirements for DAV Versioning and Variant
Authoring", October 1998, work-in-progress, draft-ietf-webdav-
versionreqs-00.txt
[Kaler] C. Kaler, "Versioning Extensions for WebDAV", September
1998, internet-draft, work-in-progress, draft-kaler-webdav-
versioning-00.
[RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T.
Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068,
U.C. Irvine, DEC, MIT/LCS, January 1997.
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
Requirement Levels." RFC 2119, BCP 14. Harvard University. March,
1997.
[WebDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D.
Jenson, "Extensions for Distributed Authoring on the World Wide
Web", October 1998, internet-draft, work-in-progress, draft-ietf-
webdav-protocol-09.
[White] E.J. Whitehead, "A Web Versioning Protocol", June 1998,
internet-draft, work-in-progress, draft-whitehead-webdav-
versioning-00.
15. AUTHOR'S ADDRESSES
Christopher Kaler, Editor
Microsoft
One Microsoft Way
Redmond WA, 9085-6933
Email:ckaler@microsoft.com
E. James Whitehead, Jr.
Dept. of Information and Computer Science
University of California, Irvine
Irvine, CA 92697-3425
Email: ejw@ics.uci.edu
TBD - list all members of the working group
16. OPEN ISSUES
The following list identifies key open issues against this
document:
Kaler, ed. [Page 39]
INTERNET-DRAFT WebDAV Versioning October 26, 1998
- Can you checkout a collection? What does it mean?
- What tags do we want to use for resource/configuration report
results?
- What structure do we create for maps?
- What time format should we use?
- Should PIN be a method or a property?
- What additional resource branching support is needed?
- Schema discovery is an issue. For example, how to
discover/change mutable/immutable properties?
- There are several missing examples / replies that need to be
specified.
17. CHANGE HISTORY
Sep 28, 1998
Initial Draft based on [White] and [Kaler].
Oct 24, 1998
Incorporate feedback from October 01-02 working group meeting.
Kaler, ed. [Page 40]
| PAFTECH AB 2003-2026 | 2026-04-24 10:28:29 |