[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]
Versions: (draft-whitehead-webdav-versioning)
00 01 02
INTERNET-DRAFT Chris Kaler, Microsoft, Editor
draft-ietf-webdav-versioning-01.txt Jim Amsden, IBM
Goeff Clemm, Rational
Bruce Cragun, Novell
David Durand, BU
Bradley Sergeant, Microfocus
Jim Whitehead, UC Irvine
Expires June 20, 1999 January 20, 1999
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, et. al. [Page 1]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
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 .............................................6
2.2.Immutable and Mutable Properties ......................7
2.3.Versioning a Resource .................................8
2.4.Immutable and Mutable Revisions .......................8
2.5.Versioning and COPY/MOVE ..............................9
2.6.Sharing ...............................................9
2.7.Default Revision .....................................10
2.8.Collection Versioning ................................11
2.9.Basic Revision Properties ............................11
2.10. Basic Versioning Headers ...........................13
2.10.1. Revision-Id .....................................13
2.10.2. Branch-Id .......................................14
2.10.3. Override-Checkin ................................14
2.10.4. Revision-Path ...................................14
3. CHECKING OUT/IN RESOURCES ............................15
3.1.Checkout .............................................15
3.2.Checkin ..............................................17
3.3.Cancelling Checkout ..................................17
3.4.Enumeration ..........................................18
4. BRANCHING RESOURCES ..................................18
5. RESOURCE REPORTS .....................................19
5.1.Available Reports ....................................20
5.2.Default History ......................................21
5.3.Active Checkouts .....................................22
5.4.Direct Lineage .......................................23
5.5.Full Lineage .........................................24
6. CONFIGURATION BASICS .................................26
6.1.Discovery ............................................27
6.2.Creating Configurations ..............................28
6.3.Access Using Configurations ..........................30
6.4.Deleting Configurations ..............................30
6.5.Resolution Queues ....................................30
6.6.Configuration Properties .............................31
6.7.Headers ..............................................32
7. CONFIGURATION REPORTS ................................33
Kaler, et. al. [Page 2]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
7.1.Configuration Derivation .............................33
7.2.Configuration Merge Graph ............................34
8. DYNAMIC CONFIGURATIONS ...............................35
9. WORKSPACE CONFIGURATIONS .............................37
9.1.Managing Configuration Content .......................37
9.2.Default Workspace Configurations .....................38
10. CHECKIN SETS .........................................38
11. VERSION MAPPING ......................................39
11.1. Discovery ..........................................40
11.2. Mapping Configurations .............................41
11.3. Mapping Resource Versions ..........................41
12. THE DAV VERSIONING GRAMMAR ...........................42
13. INTERNATIONALIZATION CONSIDERATIONS ..................42
14. SECURITY CONSIDERATIONS ..............................43
15. SCALABILITY ..........................................43
16. AUTHENTICATION .......................................43
17. IANA CONSIDERATIONS ..................................43
18. COPYRIGHT ............................................43
19. INTELLECTUAL PROPERTY ................................43
20. REFERENCES ...........................................43
21. AUTHOR'S ADDRESSES ...................................44
22. OPEN ISSUES ..........................................44
23. CHANGE HISTORY .......................................45
Kaler, et. al. [Page 3]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
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 (independent of any specific version)
Revision - This refers to a specific version of a versioned
resource
Revision History - This refers to the set of changes to a versioned
resource
Kaler, et. al. [Page 4]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
Working Resource - This refers to a resource that is an
intermediate revision of a versioned resource. That is, the
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.
Revision Thread - This refers to a sequence of revisions that have
been branched for a specific purpose.
Line of Descent - This refers to the sequence of revisions that
have occurred from the initial revision to a specified revision.
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 new versioning-specific
methods.
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.
Kaler, et. al. [Page 5]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
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 presence of Versioning in the response
header indicates support for DAV versioning. This header indicates
the level of support.
The following defines the BNF for the Versioning header:
Versioning := "Versioning" ":" URI
The valid values of the URI are:
- DAV:basicversioning
- TBD
This example shows that the /somefolder resource supports
versioning.
>> Request
OPTIONS /somefolder/ HTTP/1.1
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, MKREF, FREEZE, THAW,
CHECKIN,
CHECKOUT, UNCHECKOUT, BRANCH
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW,
CHECKIN,
CHECKOUT, UNCHECKOUT, BRANCH
Versioning: DAV:basicversioning
Content-Length: 0
Since some aspects of DAV versioning require clients to know
additional information, clients can include a request body that
specifies that DAV versioning information is desired. The
information is returned in the response body, formatted in XML.
Kaler, et. al. [Page 6]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
>> Request
OPTIONS /somefolder/ HTTP/1.1
Host: foobar.com
Content-Length: xxx
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:verinfo/>
</D:options>
>> 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, MKREF, FREEZE, THAW,
CHECKIN,
CHECKOUT, UNCHECKOUT, BRANCH
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW,
CHECKIN,
CHECKOUT, UNCHECKOUT, BRANCH
Versioning: DAV:basicversioning
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:verinfo>
...
</D:verinfo>
</D:options>
The details of the tags returned are described throughout this
specification.
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, et. al. [Page 7]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
2.3. Versioning a Resource
By default, a resource may not be subject to versioning. This can
be discovered by examining the DAV:isversioned property. To place
a non-versioned resource under version control, clients use the
VERSION method and specify the URI of the resource to version.
Note that if the specified resource is a collection, then the Depth
header is used to identify the scope of the operation. A depth of
infinity is assumed by default.
The DAV:isautoversioned 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. This
applies to any method that modifies a resource (e.g., PUT, MKCOL,
COPY, MOVE, DELETE, PROPPATCH, ...)
Using the DAV:versioningenabled and DAV:autoversioning tags,
clients can establish the versioning policy.
>> Request
VERSION /somefolder/ HTTP/1.1
Host: foobar.com
Depth: infinity
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:versioning xmlns:D="DAV:">
<D:versioningenabled>On</D:versioningenabled>
<D:autoversioning>On</D:autoversioning>
</D:versioning>
>> Response
HTTP/1.1 200 OK
Content-Length: 0
2.4. Immutable and Mutable Revisions
By default, the contents of a revision are immutable. That is,
once a revision is created, it cannot be altered. However, in many
document management systems this is not the case. To address these
scenarios, the THAW/FREEZE methods are introduced. Note that
support for THAW and FREEZE are optional, but these operations MUST
fail if not supported.
The THAW method specifies that the indicated revision should be
made mutable so that subsequent methods can alter the immutable
aspects of the resource. The FREEZE method indicates that all
changes have been made and the revision should be marked immutable
again.
Kaler, et. al. [Page 8]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
The DAV:canthaw property indicates if a revision can be thawed.
Similarly, the DAV:hasthawed property indicates if a revision has
ever been thawed. Finally, the DAV:isthawed property specifies if
the revision is currently thawed (frozen if not).
The following example shows the use of THAW and FREEZE.
>>Request
THAW /foo/bar.htm HTTP/1.1
Revision-Id: VER:FHF45409
Host: www.foobar.com
Content-Length: 0
...
PUT /foo/bar.htm HTTP/1.1
Revision-Id: VER:FHF45409
Host: www.foobar.com
Content-Length: xxx
...
FREEZE /foo/bar.htm HTTP/1.1
Revision-Id: VER:FHF45409
Host: www.foobar.com
Content-Length: 0
...
2.5. Versioning and COPY/MOVE
When a COPY method is issued against a versioned resource or
revision, only the "current" revision of the versioned resource or
the specified revision is copied to the specified destination.
That is, the entire history is NOT copied.
When a MOVE method is issued against a versioned resource the
"move" SHOULD be represented in the revision history. That is, a
MOVE operation CANNOT be represented as a delete and an add. A
MOVE operation cannot be issued against a specific revision.
2.6. 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 working group addresses this need
with direct referential members. Support for direct referential
members is required for DAV versioning.
Kaler, et. al. [Page 9]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
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 SETDEFAULT method. Note that PUT or CHECKIN will
remove any default version. Also note that branching a resource
has no effect on the default revision of the resource, even if the
default revision is branched. If the default is removed, the
default revision is the tip revision of the initial (primary)
branch of the versioned resource.
Setting the default revision to DAV:none cancels the default
revision.
>>Request
SETDEFAULT /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:setdefault xmlns:D="DAV:">
<D:href>VER:HT58GHDW49</D:href>
</D:setdefault>
>>Response
HTTP/1.1 200 OK
Content-Length: 0
>>Request
SETDEFAULT /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:setdefault xmlns:D="DAV:">
<D:none/>
</D:setdefault>
>>Response
HTTP/1.1 200 OK
Content-Length: 0
If a resource is shared, servers MUST support the ability to set
different default revisions at each point of the share.
Kaler, et. al. [Page 10]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
Clients can determine the default revision by examining the
DAV:revisionid from the default revision.
>>Request
PROPFIND /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:propfind xmlns:D="DAV:">
<D:prop>
<D:revisionid/>
</D:prop>
</D:propfind>
2.8. Collection Versioning
Collections can be versioned just like non-collection resources,
however, they are only versioned when a direct change is made to
the collection.
It is up to each collection resource to determine if it supports
default versions. If it doesn't, then SETDEFAULT requests MUST
fail.
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.
2.9. Basic Revision 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 URL or it may be an arbitrary server-defined
string. However, it cannot contain the "," character. Because it
is not required to be a URL, the DAV:revisionurl property is
required to obtain a URI for the specific revision of the resource.
Kaler, et. al. [Page 11]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
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 and should be globally unique.
DAV:previousrevisionids - 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:distinguishedpredecessorid - This read-only property indicates
the primary predecessor for a revision in the event they are
multiple predecessors.
DAV:nextrevisionids - 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.
DAV:revisionurl - This is a read-only property that returns a URL
for this specific revision.
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 and DAV:revisionid
properties 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. This is a
mutable property.
DAV:mergedto - This property specifies a comma separated list of
revision ids from which this revision is purported to be merged
into. This information is provided and managed by the client. This
is a mutable property.
DAV:mergedfromunion - This read-only property specified a comma
separated list of revision ids from which this revision is derived.
Kaler, et. al. [Page 12]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
This is a union of the DAV:mergedfrom and DAV:previousrevisionids
properties.
DAV:revisioncomment - This property contains a client-defined
property associated with the revision. This as a mutable property.
This is a mutable property.
DAV:author - The creator of the revision. This is an arbitrary
string.
DAV:canthaw - This property indicates if the revision can be THAWed
for modification. Servers MAY implement this as read-only.
DAV:hasthawed - This read-only property indicates if the revision
has ever been thawed.
DAV:isthawed - This read-only property indicates if the revision is
currently thawed (or frozen if not).
DAV:lastcheckin - This read-only property specifies the date this
revision was "checked in" in ISO8601 format.
2.10. Basic Versioning Headers
The following sub-sections describe the new version headers that
MUST be supported for resources that support DAV:versioning.
2.10.1. 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 := "*" | Time-Ref | ANY
Time-Ref := "Time" "(" ISO8601 ")"
This property allows the specification of criteria that selects a
specific revision of a resource. This includes a DAV:revisionid or
any of the DAV:revisionlabel values to refer to a specific revision
of the resource. As well, a configuration (described later) can be
referenced here to select the default revision associated with the
configuration.
The use of the Time operator is to select the "current" revision as
of the specified time.
Kaler, et. al. [Page 13]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
The use of Revision-Id: * is only permitted with PROPFIND to obtain
properties across all revisions of a versioned resource.
2.10.2. Branch-Id
The Branch-Id header is used to identify a branch (revision
thread). 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.10.3. Override-Checkin
It is possible that the check-in operation will detect a conflict.
For example, version 5 was checked out shared, and before it is
checked back in, version 6 was created. In these situations, the
check-in MUST fail indicating a conflict. Clients can choose to
branch the resource, merge on the client, or overwrite. To
circumvent this check, clients can use the Override-Checkin header.
This specifies that the check-in operation SHOULD NOT fail (either
the client has merged to resolve the conflict, or desires an
overwrite). The BNF is as follows:
Override-Checkin := "Override-Checkin" ":" ("Yes" | "No")
2.10.4. Revision-Path
The Revision-Path header allows clients to identify specific
versions of collections that should be used rather than the default
revisions.
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
Content-Length: 0
The use of * for a revision is only permitted with PROPFIND to
obtain properties across all revisions of a versioned resource.
Kaler, et. al. [Page 14]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
3. 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 to alter.
If a resource supports DAV:versioning then it MUST support the
methods defined in this section.
3.1. Checkout
Using the CHECKOUT 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 cancelled. The diagram below illustrates this process:
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. The response indicates the
working resource as well as any requested locks.
The CHECKOUT method causes the creation of the working copy which
is specified by the Location header in the response.
Clients can optionally request locks to be taken as part of the
CHECKOUT operation. If the locks cannot be obtained, the CHECKOUT
operation MUST fail. The following table identifies the different
lock options:
Lock Tags Used Description
Target (DAV: assumed)
working wrlocktype, Limits access to the newly created
resource wrlockscope working resource
revision revisionlockty Blocks CHECKOUT/INs against this
pe, revision
revisionlocksc
ope
Kaler, et. al. [Page 15]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
branch branchlocktype Blocks CHECKOUT/INs against
, revisions in this branch
branchlockscop
e
versioned vrlocktype, Blocks CHECKOUT/INs against any
resource vrlockscope revision of the versioned
resource.
The semantics of the tags match those of DAV:locktype and
DAV:lockscope as specified for the LOCK method.
>>Request
CHECKOUT /foo/bar HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:checkout xmlns:D="DAV:">
<D:comment>checkout comment</D:comment>
<D:owner>client-defined token</D:owner>
<D:wrlocktype><D:write/></D:locktype>
<D:wrlockscope><D:exclusive/></D:lockscope>
</D:checkout>
>>Response
HTTP/1.1 201 CREATED
Location: http://www.foobar.com/tmp/VRJHJWE3493409
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:prop xmlns:D="DAV:">
<D:lockdiscovery>
<D:activelock>
<D:wrlocktype><D:write/></D:locktype>
<D:wrlockscope><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>
Servers MUST fail this operation if a branch is required.
Kaler, et. al. [Page 16]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
3.2. 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 CHECKIN method against
the working copy.
The DAV:keepcheckedout tag can be specified to indicate that the
resource should remain checked out. That is, create a new
revision, but leave the working copy checked out.
Using XML tags in the request body, clients can specify optional
checkin information.
>>Request
CHECKIN /tmp/VRJHJWE3493409 HTTP/1.1
Host: www.foobar.com
Lock-Token: <opaquelocktoken:rejrei-43343-rereffre>
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:checkin xmlns:D="DAV:">
<D:comment>checkin comment</D:comment>
</D:checkin>
>>Response
HTTP/1.1 201 CREATED
Revision-Id: VER:FREFRI49349
Content-Length: 0
The reply MUST include the Revision-Id of the newly created
revision.
It is possible that the check-in operation will detect a conflict.
Servers MUST fail this operation if a branch is required. The
Override-Checkin header is used to resolve these conflicts.
3.3. Cancelling Checkout
If a client chooses to cancel a checkout request, the UNCHECKOUT
method against the working copy. As well, optional XML body tags
can be used to supply additional information.
>>Request
UNCHECKOUT /tmp/VRJHJWE3493409 HTTP/1.1
Host: www.foobar.com
Lock-Token: <opaquelocktoken:rejrei-43343-rereffre>
Content-Type: text/xml
Content-Length: xxxxx
Kaler, et. al. [Page 17]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
<?xml version="1.0" encoding="utf-8" ?>
<D:uncheckout xmlns:D="DAV:">
<D:comment>cancel checkout comment</D:comment>
</D:uncheckout>
>>Response
HTTP/1.1 200 OK
Content-Length: 0
3.4. Enumeration
Refer to the Resource Reports section for details on check-out
enumeration.
4. 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.
A revision is branched using the BRANCH method. The resource to be
branched is specified as the target URI for the method.
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
BRANCH VER:FHHR4959 HTTP/1.1
Host: www.foobar.com
Content-Type: text/html
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:branch xmlns:D="DAV:">
Kaler, et. al. [Page 18]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
<D:branchlabel>MyBranch</D:branchlabel>
<D:comment>branch comment</D:comment>
</D:branch>
>>Response
HTTP/1.1 201 CREATED
Branch-Id: MyBranch
Revision-Id: VER:REUU48583
Content-Length: 0
When a branch is created, the reply MUST include a Branch-Id
header.
5. 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:availablereports> property. The
results indicate a list of the different reports which can,
themselves, be requested via PROPFIND.
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:
Kaler, et. al. [Page 19]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
- V2: Test1
- V1.1: Test2, Good
- V1.2: Tested
Additionally, when the V1.1 branch was created, it was labeled
"MyBranch".
5.1. Available Reports
Clients can obtain the available reports for a resource by
obtaining its DAV:availablereports property.
>>Request
PROPFIND /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:availablereports/>
</D:prop>
</D:propfind>
>>Response
...
<D:multistatus>
<D:response>
<D:href>http:/www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:availablereports>
<D:report>DAV:defaulthistory</D:report>
<D:report>DAV:directlineage</D:report>
<D:report>DAV:fulllineage</D:report>
</D:availablereports>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
...
Note that the report styles MUST be specified as DAV:href values.
Kaler, et. al. [Page 20]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
When clients issue PROPFIND requests to obtain reports, they may
include other properties in the request. These properties are
returned for each report item.
5.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.
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
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:defaulthistory limit=20/>
</D:propfind>
>>Response
...
<D:multistatus>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V3</D:revision>
<D:revisioncomment>Update it</D:comment>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V1</D:revision>
<D:revisioncomment>Update it</D:comment>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
Kaler, et. al. [Page 21]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
<D:propstat>
<D:prop>
<D:revisionid>V2</D:revision>
<D:revisioncomment>Update it</D:comment>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V1</D:revision>
<D:revisioncomment>Update it</D:comment>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
5.3. Active Checkouts
Clients can obtain a list of the active checkouts against a
resource using PROPFIND and DAV:activecheckouts.
>>Request
PROPFIND /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Revision-Id: VER:FHRJ494059
Depth: 0
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:activecheckouts/>
</D:propfind>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:checkout>
<D:owner>user-specified</D:owner>
<D:revisionid>VER:FHER4949</D:revision>
Kaler, et. al. [Page 22]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:workingcopy>
<D:href>http://www.foobar.com/tmp/FHFH34949</D:href>
</D:workingcopy>
</D:checkout>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
5.4. Direct Lineage
Resources SHOULD support the DAV:directlineage report. This
enumerates the direct parent revisions of the 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).
Clients can specify the limit parameter to limit the number
revisions returned.
>>Request
PROPFIND /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:directlineage scope="name"/>
</D:propfind>
>>Response
...
<D:multistatus>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V1</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
Kaler, et. al. [Page 23]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
<D:prop>
<D:revisionid>V2</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
<D:derivedfrom>V1</D:derivedfrom>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V3</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
<D:derivedfrom>V3</D:derivedfrom>
<D:revisionlabel>Test1</D:label>
<D:mergedfrom>V2</D:mergedfrom>
<D:mergedfrom>V1.2</D:mergedfrom>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
5.5. Full Lineage
Resources SHOULD 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).
Clients can specify the limit parameter to limit the number
revisions returned.
>>Request
PROPFIND /foo/bar.htm HTTP/1.1
Host: www.foobar.com
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:fulllineage scope="name"/>
</D:propfind>
>>Response
...
Kaler, et. al. [Page 24]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
<D:multistatus>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V1</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V2</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
<D:derivedfrom>V1</D:derivedfrom>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V3</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
<D:derivedfrom>V2</D:derivedfrom>
<D:revisionlabel>Test1</D:label>
<D:mergedfrom>V2</D:mergedfrom>
<D:mergedfrom>V1.2</D:mergedfrom>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V1.1</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
<D:derivedfrom>V1</D:derivedfrom>
<D:revisionlabel>Test2</D:label>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
Kaler, et. al. [Page 25]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
<D:propstat>
<D:prop>
<D:revisionid>V1.2</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
<D:derivedfrom>V1.1</D:derivedfrom>
<D:branchid>MyBranch</D:branchid>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foobar.com/foo/bar.htm</D:href>
<D:propstat>
<D:prop>
<D:revisionid>V1.1.1</D:revision>
<D:vresourceid>VER:FFHJE</D:vresource>
<D:revisioncomment>Update it</D:comment>
<D:derivedfrom>V1.1</D:derivedfrom>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
6. CONFIGURATION BASICS
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:
- Dynamic: A dynamic configuration is a collection of specific
revisions of selected versioned resources based on selection
rules. This can be used for labels, floating labels, etc.
- Workspace: A workspace configuration is a mechanism for tracking
and managing parallel changes to multiple resources.
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. This allows configurations to
be used as a reference mechanism without breaking URL hyperlinks.
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.
Kaler, et. al. [Page 26]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
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. Typically
both a revision id and a configuration id are not needed since the
revision URI is unique across all configurations.
6.1. Discovery
Configuration support is optional. This example shows that the
/somefolder resource supports configurations.
>> Request
OPTIONS /somefolder/ HTTP/1.1
Host: www.foobar.com
Content-Length: xxx
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:verinfo/>
</D:options>
>> 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, MKREF, FREEZE, THAW,
CHECKIN,
CHECKOUT, UNCHECKOUT, BRANCH
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW,
CHECKIN,
CHECKOUT, UNCHECKOUT, BRANCH
Versioning: DAV:basicversioning
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:verinfo>
<D:configroot>
<D:href>http://www.foobar.com/cfgs/</D:href>
</D:configroot>
</D:verinfo>
</D:options>
Kaler, et. al. [Page 27]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
6.2. Creating Configurations
Servers maintain configurations in a private portion of the
namespace. The root of this namespace is determined by examining
the OPTIONS extended 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 MKCONFIG method
against the configuration namespace. This requests the server to
create a new configuration.
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
of configuration:
xxx DAV:Dynamic or
</DAV:configurationtype> 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
automatically inherits
DAV:Auto changes from its derived-
</DAV:inheritancetype> from configuration.
Conflicts are recorded in
resolution queues (see
later section).
<DAV:inheritancetype> The configuration inherits
changes from its derived-
DAV:Manual from configuration, but
</DAV:inheritancetype> they are not automatically
inserted into the
configuration. Instead
they are recorded in
resolution queues (see
Kaler, et. al. [Page 28]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
Tag Description
later section).
<DAV:inheritancetype>
snapshot of the current
DAV:None versions in the derived-
DAV:inheritancetype> from configuration. There
The configuration is a
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.
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 at the specified time or using the default revisions.
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
MKCONFIG /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>
Kaler, et. al. [Page 29]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
</D:createconfiguration>
>>Response
HTTP/1.1 201 Created
Location: http://www.foobar.com/cfgs/RYURUS99009
Content-Length: 0
6.3. 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
Content-Length: 0
6.4. 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
6.5. Resolution Queues
There are times when an operation cannot be blocked that will
result in a state that requires user action. For example, when
configurations inherit, there is the potential for conflicts.
Resolution queues provide a mechanism for discovering these
conditions.
Configurations track and maintain a list 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. The configuration will continue to report the
condition until it is resolved.
Kaler, et. al. [Page 30]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
The resolution queue is obtained by obtaining the
DAV:resolutionqueue property from the configuration. This property
contains all of the identified issues.
>>Request
PROPFIND /cfgs/FDJE4949 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:resolutionqueue/>
</D:prop>
</D:propfind>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.foobar.com/cfgs/FDJE4949</D:href>
<D:propstat>
<D:prop>
<D:resolutionqueue>
<D:resolutionitem xmlns:D="DAV:">
<D:resolutiontype><D:conflict/></D:resolutiontype>
<D:resource>http:/foo/bar.htm</D:resource>
<D:newversion>DAV:FDFEE55544</D:newversion>
</D:resolutionitem>
</D:resolutionqueue>
</D:prop>
</D:propstat>
</D:response>
</D:multistatus>
Once a client has resolved an issue it will automatically be
removed from the resolution queue.
6.6. 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:
Kaler, et. al. [Page 31]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
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:defaultconfiguration - This property on the configuration root
identifies the default workspace configuration to use if one is not
specified.
DAV:resolutionqueue - A list of identified issues that require
client attention.
6.7. 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. Note that resources CANNOT be MOVEd from one
configuration to another.
Kaler, et. al. [Page 32]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
Target-Configuration := "Target-Configuration" ":" URL
7. 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
graphs, clients use PROPFIND and the <DAV:availablereports>
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
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:enumreport/>
</D:prop>
</D:propfind>
>>Response
...
<D:multistatus>
<D:response>
<D:href>http://www.foobar.com/cfgs/FHJRH3994</D:href>
<D:propstat>
<D:prop>
<D:enumreport>
<D:report>DAV:configurationderivation</D:report>
<D:report>DAV:configurationmerge</D:report>
</D:enumreport>
</D:prop>
</D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
...
When clients issue PROPFIND requests to obtain reports, they may
include other properties in the request. These properties are
returned for each report item.
7.1. Configuration Derivation
Configurations MUST support the DAV:configurationderivation report.
This enumerates the full derivation of a configuraiton. Note that
Kaler, et. al. [Page 33]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
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
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:configurationderivation limit=100/>
</D:propfind>
>>Response
...
<D:multistatus>
<D:response>
<D:href>http:/www.foobar.com/cfgs/234</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http:/www.foobar.com/cfgs/345</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
...
7.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
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:configurationmerge/>
</D:propfind>
>>Response
...
Kaler, et. al. [Page 34]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
<D:multistatus>
<D:response>
<D:href>http:/www.foobar.com/cfgs/234</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http:/www.foobar.com/cfgs/3FF</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
...
8. DYNAMIC CONFIGURATIONS
Dynamic configurations provide a mechanism to identify all
revisions that match specific criteria. For example, "all
revisions that have the label Beta1". The dynamic configuration is
a view onto the resources and is updated automatically as resources
and revisions are created, deleted, and modified.
All dynamic configurations support the DAV:rsrtypes property. This
identifies the different styles of dynamic configurations to be
supported. This specification defines a single common type,
DAV:basicrsr.
>>Request
PROPFIND /cfgs/FHHE49495 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:rsrtypes/>
</D:prop>
</D:propfind>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.foobar.com/cfgs/FHHE49495</D:href>
<D:propstat>
<D:prop>
<D:rsrtypes>
<D:basicrsr/>
</D:rsrtypes>
Kaler, et. al. [Page 35]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
</D:prop>
</D:propstat>
</D:response>
</D:multistatus>
Clients establish a selection criteria by setting the
DAV:selectionrule property. Once set, the dynamic configuration
collection contains references to the matching resources.
>>Request
PROPPATCH /cfgs/FHHE49495 HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop>
<D:selectionrule>
<D:basicdynamicconfig>
...
</D:basicdynamicconfig>
</D:selectionrule>
</D:prop>
</D:set>
</D:propertyupdate>
The DAV:basicrsr tag groups the selection criteria that are used to
populate the dynamic configuration. The selection criteria is
specified as a set of tags where nesting represents the
expressional ordering. The following tags are available:
- DAV:and - The included tags MUST all be true to select
- DAV:or - Any of the included tags MUST be true to select
- DAV:not - The include tag should be inverted (logically)
- DAV:href - The resource URL MUST be the included URL
- DAV:label - A revision MUST have the specified label
- DAV:tip - The "tip" revision is selected
- DAV:revisionid - The specified revision is selected
- DAV:configurationid - The configuration MUST be the specified
value
- DAV:branchid - The branch MUST be the specified value
- DAV:depth - Used with DAV:href to indicate a recursive match
Kaler, et. al. [Page 36]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
TBD - provide full DTD
The following example illustrates a selection rule that includes
all revisions in the /Foo/Bar folder (and below) that have been
labeled as "Beta1".
<?xml version="1.0" encoding="utf-8" ?>
<D:basicrsr xmlns:D="DAV:">
<D:and>
<D:href>http:/www.foobar.com/Foo/Bar/<D:depth>infinity</D:depth><
/D:href>
<D:label>Beta1</D:label>
</D:and>
</D:basicrsr>
9. WORKSPACE CONFIGURATIONS
Branching provides a mechanism for parallel changes to a resource.
A workspace configuration is a mechanism for parallel changes of
multiple resources.
For example, /MySite/ might contain all of the Web pages for V1 of
my companies e-commerce site. These have been put in the V1
workspace. A team responsible for developing V2 of the site would
create a new workspace configuration based on V1. The V2 workspace
is populated with the V1 versions, but these resources can be
versioned independently. Essentially all resources have been
"branched" in a coordinated fashion. Since this is a branch, both
the V1 and the V2 revisions refer to the same versioned resource.
This allows history and reports to be generated across workspaces.
9.1. Managing Configuration Content
Clients need to be able to access and manage the contents of a
configuration. This is done using several different DAV methods.
The COPY method can be used to copy a specific revision of a
resource. However, this results in a new versioned resource being
created.
Resources are added to and removed from workspace configurations
using the MKREF and DELREF methods defined by the DAV Advanced
Collections Working Group. Note that direct references are
required.
Clients can obtain the contents of a configuration using PROPFIND
to enumerate the hierarchy under the configuation's collection. As
well, as stated above, clients can use the Configuration-Id header
as described previously.
Kaler, et. al. [Page 37]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
9.2. 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, use the SETDEFAULT method against the
configuration root identifying the default configuration.
>>Request
SETDEFAULT /cfgs/ HTTP/1.1
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:setdefault xmlns:D="DAV:">
<D:href>http://www.foobar.com/cfgs/CHFH49594/</D:href>
</D:setdefault>
>>Response
HTTP/1.1 200 OK
Content-Length: 0
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 MKCHECKINSET 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.
Checkin sets are specific to a configuration and are created using
the MKCHECKINSET method. The DAV:checkinsetroot property on a
configuration specifies the URL of a collection where checkin sets
for the configuration exist. This can be used for discovery or
creation. If a configuration doesn't support checkin sets, then
this property will be empty.
Clients create checkin sets using MKCHECKINSET. The response
includes the location of the new checkin set.
>>Request
MKCHECKINSET /cs/244 HTTP/1.1
Host: www.foobar.com
Content-Length: 0
>>Response
HTTP/1.1 201 CREATED
Host: www.foobar.com
Location: http://www.foobar.com/cs/244
Kaler, et. al. [Page 38]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
Content-Length: 0
The following example illustrates use of checkin sets.
>>Request
CHECKIN /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:checkin>
...
</D:checkin>
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.
A checkin that references a checkin set MUST be made to the
configuration associated with the checkin set.
11. 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.
Note that mappings are dynamic. That is, as resources are added,
removed, and modified, the changes are reflected in any active
maps.
To delete a mapping, use DELETE against the URI specified in the
MKMAP request.
Kaler, et. al. [Page 39]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
11.1. Discovery
Mapping support is optional and support is discovered using OPTIONS
to verify if the MKMAP method is supported. Using the request body
and the DAV:verinfo tag, clients can obtain the supported map
styles.
This example shows that the /cfgs/DFEE2034 configuration supports
mapping to the /map/ root in the namespace.
>> Request
OPTIONS /cfgs/DFEE2034 HTTP/1.1
Host: foobar.com
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:verinfo/>
</D:options>
>> 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, MKREF, FREEZE, THAW,
CHECKIN,
CHECKOUT, UNCHECKOUT, BRANCH
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW,
CHECKIN,
CHECKOUT, UNCHECKOUT, BRANCH
Versioning: DAV:versioning
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:verinfo>
<D:mapstyles>
<D:mapstyle>DAV:detailedmap </D:mapstyle>
<D:mapstyle>DAV:branchmap </D:mapstyle>
<D:mapstyle>DAV:nestedbranch </D:mapstyle>
</D:mapstyles>
</D:verinfo>
</D:options>
Kaler, et. al. [Page 40]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
11.2. Mapping Configurations
The MKMAP 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
MKMAP /maps/mymap HTTP/1.1
Host: foobar.com
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
11.3. Mapping Resource Versions
The MKMAP 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
Kaler, et. al. [Page 41]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
| | | | | | |
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
MKMAP /maps/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 MKMAP, then it MUST support DAV:detailedmap as
illustrated above.
12. THE DAV VERSIONING GRAMMAR
To be supplied - Describe and detail the DTDs
13. INTERNATIONALIZATION CONSIDERATIONS
To be supplied.
Kaler, et. al. [Page 42]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
14. SECURITY CONSIDERATIONS
To be supplied.
15. SCALABILITY
To be supplied.
16. AUTHENTICATION
Authentication mechanisms defined in WebDAV will also apply to DAV
Versioning.
17. 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.
18. COPYRIGHT
To be supplied.
19. INTELLECTUAL PROPERTY
To be supplied.
20. REFERENCES
[DAVVERREQ] TBD, "Requirements for DAV Versioning and Variant
Authoring", October 1998, internet-draft, 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
Kaler, et. al. [Page 43]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
Web", April. 1998, internet-draft, work-in-progress, draft-ietf-
webdav-protocol-08.
[White] E.J. Whitehead, "A Web Versioning Protocol", June 1998,
internet-draft, work-in-progress, draft-whitehead-webdav-
versioning-00.
21. AUTHOR'S ADDRESSES
Christopher Kaler, Editor
Microsoft
One Microsoft Way
Redmond WA, 9085-6933
Email:ckaler@microsoft.com
Jim Amsden
IBM
Email: jamsden@us.ibm.com
Geoff Clemm
Rational
Email: gclemm@atria.com
Bruce Cragun
Novell Inc.
1555 N. Technology Way
Orem, UT 84097
Email: bcragun@novell.com
David Durand
Email: dgd@cs.bu.edu
Bradley Sergeant
MicroFocus
Email: bradley_sergeant@intersolv.com
E. James Whitehead, Jr.
Dept. of Information and Computer Science
University of California, Irvine
Irvine, CA 92697-3425
Email: ejw@ics.uci.edu
22. OPEN ISSUES
The following list identifies key open issues against this
document:
. Can you checkout a collection? What does it mean?
. What tags do we want to use for resource/configuration report
results?
Kaler, et. al. [Page 44]
INTERNET-DRAFT WebDAV Versioning January 20, 1999
. What structure do we create for maps?
. 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.
23. CHANGE HISTORY
Sep 28, 1998
Initial Draft based on [White] and [Kaler].
Oct 24, 1998
Incorporate feedback from October 01-02 working group meeting.
Jan 20, 1999
Incorporate feedback from December 1998 working group meeting.
Kaler, et. al. [Page 45]
Html markup produced by rfcmarkup 1.129b, available from
https://tools.ietf.org/tools/rfcmarkup/