draft-ietf-webdav-versioning-01.txt   draft-ietf-webdav-versioning-02.txt 
INTERNET-DRAFT Geoffrey Clemm, Rational Software
draft-ietf-webdav-versioning-02.txt Chris Kaler, Microsoft
INTERNET-DRAFT Chris Kaler, Microsoft, Editor Expires December 25, 1999 June 25, 1999
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 Versioning Extensions to WebDAV
Status of this Memo
This document is an Internet draft. Internet drafts are working Status of this Memo.
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 This document is an Internet-Draft and is in full conformance with all
"lid-abstracts.txt" listing contained in the Internet drafts shadow provisions of Section 10 of RFC2026.
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 Internet-Drafts are working documents of the Internet Engineering Task
to the mailing list at <ietf-dav-versioning@w3.org>, which may be Force (IETF), its areas, and its working groups. Note that other groups
joined by sending a message with subject "subscribe" to <ietf-dav- may also distribute working documents as Internet-Drafts.
versioning-request@w3.org>.
Discussions of the list are archived at Internet-Drafts are draft documents valid for a maximum of six months
<URL:http://www.w3.org/Archives/Public/ietf-dav-versioning/>. and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress."
Abstract The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
This document specifies a set of methods, headers, and content- The list of Internet-Draft Shadow Directories can be accessed at
types composing DAV Versioning extensions, an application of the http://www.ietf.org/shadow.html.
HTTP/1.1 protocol to version DAV resources.
Table of Contents Abstract
VERSIONING EXTENSIONS TO WEBDAV ...........................1 This document specifies a set of methods, headers, and resource-types
that define the WebDAV Versioning extensions to the HTTP/1.1 protocol.
WebDAV Versioning will minimize the complexity of clients so as to
facilitate widespread deployment of applications capable of utilizing
the WebDAV Versioning services. WebDAV Versioning includes:
TABLE OF CONTENTS .........................................2 - Automatic versioning support for versioning-unaware clients,
1. INTRODUCTION ..........................................4 - Linear versioning , and
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 - Support for parallel development and configuration management.
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 Table of Contents
3.1.Checkout .............................................15
3.2.Checkin ..............................................17
3.3.Cancelling Checkout ..................................17
3.4.Enumeration ..........................................18
4. BRANCHING RESOURCES ..................................18 VERSIONING EXTENSIONS TO WEBDAV...........................1
5. RESOURCE REPORTS .....................................19 STATUS OF THIS MEMO.......................................1
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 ABSTRACT..................................................1
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 TABLE OF CONTENTS.........................................2
7.1.Configuration Derivation .............................33
7.2.Configuration Merge Graph ............................34
8. DYNAMIC CONFIGURATIONS ...............................35 1 INTRODUCTION...........................................4
1.1 Relationship to DAV.................................4
1.2 Terms...............................................5
1.3 Notational Conventions..............................5
9. WORKSPACE CONFIGURATIONS .............................37 2 CONCEPTS AND DEFINITIONS...............................5
9.1.Managing Configuration Content .......................37
9.2.Default Workspace Configurations .....................38
10. CHECKIN SETS .........................................38 3 WEBDAV VERSIONING SEMANTICS...........................10
3.1 Creating Versioned Resources.......................10
3.2 Modifying a Versioned Resource.....................11
3.3 Naming Revisions: Revision Ids and Labels..........11
3.4 Parallel Development and Activities................12
3.5 Revision Selection and Workspaces..................12
3.6 Configurations.....................................13
3.7 Versioned Collections..............................13
11. VERSION MAPPING ......................................39 4 VERSIONING RESOURCE TYPES AND PROPERTIES..............14
11.1. Discovery ..........................................40 4.1 Property Attributes................................14
11.2. Mapping Configurations .............................41 4.1.1 Writeable/Readonly Properties....................14
11.3. Mapping Resource Versions ..........................41 4.1.2 Immutable/Mutable Properties.....................14
4.1.3 Property Resources...............................14
4.2 Resource Properties................................15
4.2.1 DAV:author (immutable) [Core]...................15
4.2.2 DAV:comment (immutable) [Core]..................15
4.3 Revision Properties................................15
4.3.1 DAV:revision-id (readonly) [Core]................15
4.3.2 DAV:predecessor (readonly, resource) [Core]......15
4.3.3 DAV:successors (readonly, mutable, collection)...15
4.3.4 DAV:single-checkout (mutable) [Core].............15
4.3.5 DAV:auto-version (mutable) [Core]................16
4.3.6 DAV:revision-labels (mutable) [Core].............16
4.3.7 DAV:checkin-date (readonly) [Core]...............16
4.3.8 DAV:working-resources (readonly, collection) ....16
4.3.9 DAV:history-uuid (readonly) [Core]...............16
4.3.10DAV:history (readonly, resource) [Core]..........16
4.3.11DAV:merge-predecessors (mutable, collection).....16
4.3.12DAV:merge-successors ............................17
4.4 Working Resource Properties........................17
4.4.1 DAV:workspace (readonly, resource) [Core]........17
4.4.2 DAV:predecessor (read-only, resource) [Core].....17
4.4.3 DAV:checkin-policy [Core]........................17
4.4.4 DAV:merge-predecessors (collection) [Merging]....18
4.4.5 DAV:activity (readonly, resource) [Activity].....18
4.5 Workspace Properties...............................18
4.5.1 DAV:working-resources (readonly, collection) ....18
4.5.2 DAV:revision-selection-rule [Core]..............18
4.5.3 DAV:label [Core].................................19
4.5.4 DAV:activity [Activity]..........................19
4.6 Activity Properties................................19
4.6.1 DAV:revisions (readonly, collection) [Activity]..19
4.6.2 DAV:required-activities (collection) [Activity]..19
4.6.3 DAV:workspace (resource) [Activty]...............19
4.7 Configuration Properties...........................19
4.7.1 DAV:roots (immutable, collection) [Configuration]20
4.8 Versioned Collection Properties....................20
4.8.1 DAV:baselines (resource) [Baseline]..............20
4.9 History Resource Properties........................20
4.9.1 DAV:uuid (readonly) [Core].......................20
4.9.2 DAV:revisions (readonly, collection) [Core]......20
4.9.3 DAV:revision-labels (collection) [Core]..........20
12. THE DAV VERSIONING GRAMMAR ...........................42 5 VERSIONING METHODS....................................21
5.1 Existing Methods...................................21
5.1.1 GET..............................................21
5.1.2 BIND.............................................21
5.1.3 PUT..............................................21
5.1.4 PROPFIND.........................................22
5.1.5 PROPPATCH........................................22
5.1.6 DELETE...........................................22
5.1.7 COPY.............................................22
5.1.8 MOVE.............................................22
5.1.9 LOCK.............................................23
5.1.10 OPTIONS..........................................23
5.2 New Methods........................................23
5.2.1 MKRESOURCE.......................................23
5.2.2 REPORT...........................................24
5.3 New Versioning Methods.............................24
5.3.1 CHECKOUT.........................................24
5.3.2 CHECKIN..........................................25
5.3.3 UNCHECKOUT.......................................25
5.4 New Versioning Headers.............................26
5.4.1 Target-Selector..................................26
13. INTERNATIONALIZATION CONSIDERATIONS ..................42 6 THE DAV VERSIONING XML ELEMENTS.......................26
6.1 Revision Selection Rule Elements...................26
6.1.1 DAV:rsr-configuration............................26
6.1.2 DAV:rsr-activity-latest..........................26
6.1.3 DAV:rsr-label....................................27
6.1.4 DAV:rsr-revision-id..............................27
6.1.5 DAV:rsr-latest...................................27
6.1.6 DAV:rsr-or.......................................27
6.1.7 DAV:rsr-merge....................................27
6.2 Report Elements....................................28
6.2.1 Conflicts Report.................................28
6.2.2 Compare Report...................................28
7 INTERNATIONALIZATION CONSIDERATIONS...................29
14. SECURITY CONSIDERATIONS ..............................43 8 SECURITY CONSIDERATIONS...............................29
15. SCALABILITY ..........................................43 9 SCALABILITY...........................................29
16. AUTHENTICATION .......................................43 10 AUTHENTICATION......................................30
17. IANA CONSIDERATIONS ..................................43 11 IANA CONSIDERATIONS..................................30
18. COPYRIGHT ............................................43 12 INTELLECTUAL PROPERTY................................30
19. INTELLECTUAL PROPERTY ................................43 13 ACKNOWLEDGEMENTS.....................................30
20. REFERENCES ...........................................43 14 INDEX................................................30
21. AUTHOR'S ADDRESSES ...................................44 15 REFERENCES...........................................31
22. OPEN ISSUES ..........................................44 16 AUTHORS ADDRESSES....................................31
23. CHANGE HISTORY .......................................45 17 OPEN ISSUES..........................................31
1. INTRODUCTION
1.1. DAV Versioning 1 INTRODUCTION
This document defines DAV Versioning extensions, an application of This document defines DAV Versioning extensions, an application of
HTTP/1.1 for handling resource versioning in a DAV environment. HTTP/1.1 for handling resource versioning in a DAV environment.
[DAVVERREQ] describes the motivation and requirements for DAV [VerGoal] describes the motivation and requirements for DAV
Versioning. Versioning.
DAV Versioning will minimize the complexity of clients so as to DAV Versioning will minimize the complexity of clients so as to
facilitate widespread deployment of applications capable of facilitate widespread deployment of applications capable of
utilizing the DAV services. As well, DAV Versioning supports a utilizing the DAV services. As well, DAV Versioning supports a
rich level of versioning options for versioning-aware clients. rich level of versioning options for versioning-aware clients.
DAV Versioning consists of: DAV Versioning consists of:
- Automatic versioning support for HTTP/1.1-based clients, - Automatic versioning support for versioning-unaware 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 - Linear versioning , and
[DAVVERREQ].
1.4. Definitions - Support for parallel development and configuration management.
The section defines several terms that are used throughout the 1.1 Relationship to DAV
document specific to DAV versioning.
Versioned Resource - This refers to a resource that is subject to To maximize interoperability and use of existing protocol
versioning (independent of any specific version) functionality, versioning support is designed as extensions to the
WebDAV [RFC2518] and advanced-collection protocols [AdvCol]. In
particular, DAV Versioning relies on the resource and property
model defined by [RFC2518] and the binding model defined by
[AdvCol]. The versioning protocol is designed so that WebDAV
locking (class 2) support is optional. The effect of a lock on
versioning methods and content-types will be defined to provide
interoperability of servers that provide locking support.
Revision - This refers to a specific version of a versioned Versioning support is defined in the form of Core versioning
resource support, supplemented by a set of orthogonal extensions to the
Core: Activity, Merging, Configuration, Versioned Collection, and
Baseline versioning support. Core support provides versioning of
largely independent resources. It allows authors to concurrently
create and access distinct revisions of a resource. Activity
support extends Core support with logical change tracking and
management through activities. Merging support extends Core
support with conflict detection and resolution through merging.
Configuration support extends Core support with the creation of
sets of consistent revisions. Versioned Collection support extends
Core support with the ability to version the URL namespace.
Baseline support extends Configuration and Versioned Collection
support with the ability to create and compare configurations of
all revisions in a URL subtree.
Revision History - This refers to the set of changes to a versioned Throughout this specification the [xyz] notation is used to
resource indicate that a property is introduced at the "xyz" level of
Working Resource - This refers to a resource that is an versioning support. The levels of versioning support provided by a
intermediate revision of a versioned resource. That is, the server can be discovered via an OPTIONS request.
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 1.2 Terms
been branched for a specific purpose.
Line of Descent - This refers to the sequence of revisions that This draft uses the terms defined in [RFC2068] and [RFC2518].
have occurred from the initial revision to a specified revision.
1.5. Notational Conventions 1.3 Notational Conventions
The augmented BNF used by this document to describe protocol The augmented BNF used by this document to describe protocol
elements is exactly the same as the one described in Section 2.1 of elements is exactly the same as the one described in Section 2.1 of
[RFC2068]. Because this augmented BNF uses the basic production [RFC2068]. Because this augmented BNF uses the basic production
rules provided in Section 2.2 of [RFC2068], those rules apply to rules provided in Section 2.2 of [RFC2068], those rules apply to
this document as well. this document as well.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in [RFC2119]. this document are to be interpreted as described in [RFC2119].
2. BASIC VERSIONING 2 CONCEPTS AND DEFINITIONS
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.
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.
>> 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.
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.
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.
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.
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.
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.
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 The section presents the versioning concepts and terms/definitions
for modification. Servers MAY implement this as read-only. used in this protocol.
DAV:hasthawed - This read-only property indicates if the revision Versionable Resource
has ever been thawed.
DAV:isthawed - This read-only property indicates if the revision is A versionable resource is a resource that can be placed under
currently thawed (or frozen if not). version control. A null resource is a versionable resource.
DAV:lastcheckin - This read-only property specifies the date this Versioned Resource
revision was "checked in" in ISO8601 format.
2.10. Basic Versioning Headers A versioned resource is a resource that is under version control.
To update a resource under version control, it must be checked out
and then subsequently checked in. The checked in states of a
versioned resource are saved by the server to capture the history
of that resource.
The following sub-sections describe the new version headers that Revision
MUST be supported for resources that support DAV:versioning. A revision contains a particular state of a versioned resource. An
immutable revision is a revision whose body and immutable
properties cannot be modified. A mutable revision is a revision
whose state can be overwritten by a subsequent check in request.
2.10.1. Revision-Id Revision Name
The Revision-Id header is used to identify a specific revision of a A revision name is a name that can be used to identify a single
versioned resource. This header can be specified on all methods revision of a versioned resource. There are two types of revision
and qualifies the resource named in the method. As well, this names: revision identifiers and revision labels.
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 Identifier
Revision-Id := "Revision-Id" ":" RID A revision identifier (or revision ID) is a revision name that is
RID := "*" | Time-Ref | ANY assigned by the server when the revision is created and cannot be
Time-Ref := "Time" "(" ISO8601 ")" changed to refer to a different revision.
This property allows the specification of criteria that selects a Revision Label
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 A revision label is a revision name that is assigned by a client
of the specified time. and may later be changed to refer to a different revision. The same
label may be assigned to many different versioned resources.
The use of Revision-Id: * is only permitted with PROPFIND to obtain Initial Revision
properties across all revisions of a versioned resource.
2.10.2. Branch-Id An initial revision is the first revision of a versioned resource.
The Branch-Id header is used to identify a branch (revision Predecessor, Successor
thread). The BNF for the header is as follows:
Branch-Id := "Branch-Id" ":" ANY A predecessor of a revision is the previous revision that was
checked out to create the revision. A successor of a revision is a
revision whose predecessor is that revision. Each revision has a
single predecessor (except for the initial revision which has no
predecessor) and zero or more successors.
The Branch-Id can be used anywhere a revision-id is used. When Merge Predecessor, Merge Successor
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 A merge predecessor of a revision is a revision that has been
merged into this revision. A merge successor of a revision is a
revision into which that revision has been merged. A revision can
have zero or more merge predecessors and zero or more merge
successors.
It is possible that the check-in operation will detect a conflict. Line Of Descent
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") A line of descent to a specified revision is a sequence of
revisions connected by successor relationships from the initial
revision to that revision.
2.10.4. Revision-Path The following diagram illustrates several of the previous
definitions.
The Revision-Path header allows clients to identify specific Versioned --> Foo.htm
versions of collections that should be used rather than the default Resource
revisions. +----+ \
Label --> "initial" | V1 | | |
\ +----+ | |
\ | | |
\ v | |
\ +----+ | Line |
-> "beta1" | V2 | | of |
+----+ | Descent |
/ | | |
v v | |
+----+ +----+ | |
Revision Id --> | V3 | | V4 | | | History
+----+ +----+ | |
^ | | | |
| v v | |
Predecessor | +----+ +----+ v |
| V5 | | V6 | |
+----+ +----+ |
\ | | Successor |
| v v | |
Merge Successor | +----+ v |
v | V7 | |
+----+ /
The BNF for this header is as follows. Immutable/Mutable Property
Revision-Path := "Revision-Path" ":" Path An immutable property is a property of an immutable revision that
Path := PItem | (Path PItem) cannot be changed. A mutable property is a property of an
PItem := "/" ANY Rev immutable revision that can be changed. Only properties of
Rev := | (";" RID) revisions can be immutable or mutable.
RID := "*" | ANY | "(" ANY ")"
>>Request Working Resource
GET /foo/bar.htm HTTP/1.1 A working resource is an editable resource created by checking out
Host: www.foobar.com a revision of a versioned resource.
Revision-Path: /foo;VER:HT58GHDW49/bar.htm
Content-Length: 0
The use of * for a revision is only permitted with PROPFIND to Checkout/Checkin Model
obtain properties across all revisions of a versioned resource.
3. CHECKING OUT/IN RESOURCES The checkout/checkin model is the process by which updates are made
to a versioned resource. A versioned resource is checked out to
create an editable working resource. The working resource is
updated or augmented as desired, and then checked in to make it
part of the revision history of the versioned resource.
For versioning-aware clients, more advanced requests allow them to The following diagram illustrates the checkout/checkin process.
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 ===CHECKOUT==> ===CHECKIN==>
methods defined in this section.
3.1. Checkout Foo.htm | Foo.htm | Foo.htm
| |
+----+ | +----+ | +----+
| V1 | | | V1 | | | V1 |
+----+ | +----+ | +----+
| | | | |
v | v | v
+----+ | +----+ | +----+
| V2 | | | V2 | | | V2 |
+----+ | +----+ | +----+
| | | |
| v | v
| +----+ | +----+
| | WR | | | V3 |
| +----+ | +----+
Activity
Using the CHECKOUT method, clients can request resources to be An activity is a resource that selects a set of revisions that
"checked out". This involves creating a working resource that is correspond to some unit of work or conceptual change. An activity
not automatically versioned. Checked out resources must be checked can contain revisions of multiple versioned resources, and multiple
in or cancelled. The diagram below illustrates this process: revisions of the same versioned resource. If an activity contains
multiple revisions of the same versioned resource, all of those
revisions must be on a single line of descent to one of those
revisions, and this revision is called the latest revision selected
by that activity for that versioned resource.
Revisions of foo.htm: V1 The following diagram illustrates activities. Revision V3 is the
latest revision of Foo.htm selected by activity 2, and revision V7
is the latest revision of Bar.htm selected by activity 2.
Checkout is performed: V1 Foo.htm | Bar.htm
| |
+-> Working Resource +----+ | +----+
| V1 | | | V5 |
Checkin is performed: V1 -> V2 +----+ | +----+
| Activity | | Activity
The body XML indicates an optional checkout comment, an optional v 1 | v 2
user token, and locking actions. The response indicates the +----+ | +----+
working resource as well as any requested locks. | V2 | | | V6 |
+----+ | +----+
The CHECKOUT method causes the creation of the working copy which | Activity | | Activity
is specified by the Location header in the response. v 2 | v 2
+----+ | +----+
Clients can optionally request locks to be taken as part of the | V3 | | | V7 |
CHECKOUT operation. If the locks cannot be obtained, the CHECKOUT +----+ | +----+
operation MUST fail. The following table identifies the different | | Activity
lock options: | v 3
| +----+
Lock Tags Used Description | | V8 |
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
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.
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 Workspace
CHECKIN /tmp/VRJHJWE3493409 HTTP/1.1 A workspace is a resource that is used to identify working
Host: www.foobar.com resources. A workspace can also contain a revision selection rule
Lock-Token: <opaquelocktoken:rejrei-43343-rereffre> that specifies what revision of an arbitrary versioned resource
Content-Type: text/xml should be accessed when the resource is referenced in the context
Content-Length: xxx of that workspace. A revision selection rule provides revision
selection based on criteria such as revision name, latest in an
activity, and membership in a configuration.
<?xml version="1.0" encoding="utf-8" ?> A workspace that does not contain a revision selection rule (and
<D:checkin xmlns:D="DAV:"> therefore can only be used to identify working resources) is called
<D:comment>checkin comment</D:comment> a basic workspace. A workspace that contains a revision selection
</D:checkin> rule (and therefore can be used to specify revision selection) is
called an extended workspace.
>>Response The following diagram illustrates an extended workspace.
HTTP/1.1 201 CREATED Foo.htm Bar.htm Bing.htm
Revision-Id: VER:FREFRI49349 +----+ +----+
Content-Length: 0 | V1 | | V1 |
+----+ +----+
| |
| |
+-----------------|------------|------------------+
| v v |
| +----+ +----+ +----+ |
| | V1 | | V2 | | WR | Workspace X |
| +----+ +----+ +----+ |
| | |
+-----------------|-------------------------------+
|
v
+----+
| V3 |
+----+
The reply MUST include the Revision-Id of the newly created Target
revision.
It is possible that the check-in operation will detect a conflict. The target of a versioned resource is the working resource or
Servers MUST fail this operation if a branch is required. The revision of that versioned resource that is selected by the current
Override-Checkin header is used to resolve these conflicts. workspace.
3.3. Cancelling Checkout Conflict Report
If a client chooses to cancel a checkout request, the UNCHECKOUT A conflict report lists all versioned resources for which the
method against the working copy. As well, optional XML body tags revision selection rule of a workspace selects multiple revisions
can be used to supply additional information. on different lines of descent. A conflict is resolved by checking
out one of the selected revisions, modifying the resulting working
resource so that it represents the logical merge of all selected
revisions, and then indicating these merges by adding these
revisions as merge predecessors of the working resource. Checking
in this working resource creates a new revision that resolves the
conflict.
>>Request Default Workspace
UNCHECKOUT /tmp/VRJHJWE3493409 HTTP/1.1 A server MUST provide a default workspace that is used to perform
Host: www.foobar.com version selection for versioning-unaware clients. The revision
Lock-Token: <opaquelocktoken:rejrei-43343-rereffre> selection rule of the default workspace MAY be a modifiable by a
Content-Type: text/xml client.
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:uncheckout xmlns:D="DAV:">
<D:comment>cancel checkout comment</D:comment>
</D:uncheckout>
>>Response Default Target
HTTP/1.1 200 OK The default target of a versioned resource is the target selected
Content-Length: 0 by the default workspace.
3.4. Enumeration Configuration
Refer to the Resource Reports section for details on check-out A configuration selects a particular revision from each of a set of
enumeration. versioned resources. Unlike a workspace, which can select both
working resources and revisions, a configuration can only select
revisions. Also, while the revision selected by a workspace for a
versioned resource can change as a result of a change to the
versioned resource (such as adding a label), the revision selected
by a configuration can change only by explicitly modifying the
configuration itself. Unlike an activity, a configuration can
select at most one revisions of a given versioned resource. Unlike
both a workspace and an activity, a configuration can be versioned.
4. BRANCHING RESOURCES The following diagram illustrates a configuration.
For more sophisticated clients, basic resource branching is Foo.htm Bar.htm Bing.htm
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 |
+-> 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 | +----+ +----+ +----+ Configuration |
section. Note that when a collection is branched, the depth of the | | V1 | | V2 | | V1 | V1.1 |
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. | |
v v
As well, clients can specify a branch label to identify a created +----+ +----+
branch using the DAV:branchlabel tag. The reply MUST include a | V3 | | V2 |
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:">
<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 Versioned Collection
has the following revision graph:
Revision history V1 -> V2 -> V3 A versioned collection is a type of versioned resource that results
Of foo.htm: | from placing a collection under version control. The members of a
+-> V1.1 -> V1.2 versioned collection revision are all versioned resources.
|
+-> V1.1.1
Clients have specified the following merge annotations: Baselined Collection
- V1.2 is a merge of V1.1 and V1.1.1 A baselined collection is a special type of versioned collection
that is associated with a versioned configuration. A revision of
the associated versioned configuration is called a baseline of the
baselined collection. A baseline contains a revision of the
versioned collection and a revision of every member of every
versioned collection revision in that baseline.
- V3 is a merge of V2 and V1.2 History Resource
As well, the default revision history (those revisions marked as A history resource for a versioned resource contains all revisions
the default) is as follows: of that versioned resource.
- V1 (the initial revision was created) 3 WEBDAV VERSIONING SEMANTICS
- V2 (a new revision was created) 3.1 Creating Versioned Resources
- V1 (a client changed the default revision) A resource may or may not be versioned. When a resource is created
by a PUT or MKRESOURCE request, it is commonly created as an
unversioned resource. Some unversioned resources can be put under
version control; these are called versionable resources. After a
resource is put under version control, it becomes a versioned
resource, and an initial revision is created that is a copy of the
versionable resource. This initial revision becomes the target of
the versioned resource.
- V3 (an updated revision was created) 3.2 Modifying a Versioned Resource
Also, the following labels have been specified: A versioned resource must be checked out before it can be modified.
Checking out a versioned resource produces a new resource, called a
working resource. A working resource is a modifiable copy of the
revision, and is identical to an unversioned resource in all
respects other than that it is associated with a particular
revision of a particular versioned resource. It may be edited by
setting its properties or contents any number of times. When the
author is satisfied that the working resource is in a state that
should be retained in the versioned resource history, the author
checks in the working resource to create a new revision of the
versioned resource. The revision that was checked out is the
predecessor of the new revision.
- V2: Test1 The use of checkout/checkin and working resources to update a
versioned resource addresses the lost update problem by ensuring
that each author is updating his or her own working resource rather
than a shared resource, and by ensuring that the predecessor of the
updated resource is reliably tracked. Authors can use
checkout/checkin to register intent to modify a versioned resource
similar to the way lock /unlock are used in WebDAV level 2, but the
underlying semantics are very different. With lock/unlock, work is
serialized and avoiding lost updates depends on clients using the
lock/unlock protocol. With checkout/checkin, work can be performed
in parallel, and the server prevents lost updates by retaining all
saved states (revisions) of the resource.
- V1.1: Test2, Good A revision may be created as either immutable or mutable. An
immutable revision cannot be changed and provides a stable
environment for history management, change recovery, merging, and
configuration management. A mutable revision is more suitable for
situations where versioning is treated more informally, and it is
not necessary or desirable to maintain strict version histories, or
to guarantee the possibility of backtracking to a previous saved
state. If the revision is mutable, the author may request that a
subsequent checkin should overwrite the revision that was checked
out, instead of creating a new revision. In this case, the
previous state captured by that revision is lost. Servers may
choose to support only immutable revisions, only mutable revisions,
or both.
- V1.2: Tested 3.3 Naming Revisions: Revision Ids and Labels
Additionally, when the V1.1 branch was created, it was labeled Revision names are used to distinguish a revision of a versioned
"MyBranch". resource from other revisions of that versioned resource. A
revision name is either a revision id or any number of revision
labels. A revision of a versioned resource is given a server
assigned revision id when it is created. This revision id acts as a
persistent, immutable identifier distinguishing this revision from
all others of the same versioned resource. The revision id cannot
be changed, assigned to another revision, or reused.
5.1. Available Reports A user may assign revision labels to a revision in order to provide
a more meaningful name for the revision. A given revision label
can be assigned to at most one revision of a given versioned
resource, but may be reassigned to any revision of the versioned
resource at any time. Revisions of different versioned resources
may have the same label.
Clients can obtain the available reports for a resource by 3.4 Parallel Development and Activities
obtaining its DAV:availablereports property.
>>Request In a locking model, when a resource is locked for modifications by
one author, all other authors are supposed to respect that lock and
not work on a copy of that resource until the lock has been
released. To avoid the work serialization inherent in the locking
model, a versioning model allows multiple authors in different
workspaces to check out the same revision at the same time, work on
their respective working resources in parallel, check in their
respective working resources as soon as their changes are complete,
and then merge the resulting revisions at some later time.
PROPFIND /foo/bar.htm HTTP/1.1 Although a simple versioning model works well for isolated changes
Host: www.foobar.com to independent resources, the required merge process becomes
Depth: 0 unmanageable when sequences of inter-related changes are performed
Content-Type: text/xml on sets of related resource. To address this merge problem,
Content-Length: xxxx resources can be checked out in the context of an activity. An
activity captures the set of revisions that form a set of related
changes an author is making to one or more versioned resources.
Each activity represents a thread of development, where any thread
can be isolated from other threads to provide a stable environment
for parallel work. In case parallel work on isolated activities
results in branches in the underlying versioned resource histories,
the activities can be unified through a merge operation.
<?xml version="1.0" encoding="utf-8" ?> 3.5 Revision Selection and Workspaces
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:availablereports/>
</D:prop>
</D:propfind>
>>Response Resources, working resources, and revisions of versioned resources
are all accessed using a URL. When a client accesses a versioned
resource, it is necessary to provide additional information to
specify which working resource or which revision of the versioned
resource should be accessed. Specifying the resource URL and a
revision name can access a specific revision of the versioned
resource. However, this requires the user to add and remember
labels for each revision; it does not provide a way of accessing a
consistent set of revisions captured by an activity or contained in
a configuration; it does not enable non-versioning aware clients to
access revisions; and it does not provide a client with access to a
working resource of a versioned resource.
... To address the restrictions inherent in revision-name based
<D:multistatus> revision selection, the revision selected when a specific revision
<D:response> name is not specified is resolved through a workspace. A workspace
<D:href>http:/www.foobar.com/foo/bar.htm</D:href> is a resource whose primary purpose is to identify working
<D:propstat> resources. If the workspace contains no working resource for a
<D:prop> given versioned resource, it can also be used to select an
<D:availablereports> appropriate revision of the versioned resource. This allows
<D:report>DAV:defaulthistory</D:report> versioned resources and unversioned resources to be accessed
<D:report>DAV:directlineage</D:report> consistently by both versioning-aware and versioning-unaware
<D:report>DAV:fulllineage</D:report> clients.
</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. In order to specify revision selection, a workspace contains a
revision selection rule. A revision selection rule can specify
revision names, activities, configurations, or use operators that
combine several of these rule elements. A revision name selects a
revision with that name. An activity selects the latest revision
that was created in that activity. Configurations select the
revision contained in the configuration. The "or" operator contains
a sequence of rule elements, and applies them in order until the
first match is found. If there is no matching revision, then a
resource-not-found status is returned.
When clients issue PROPFIND requests to obtain reports, they may If a request is made and no workspace is specified, a server
include other properties in the request. These properties are determined default workspace is used. This is the workspace used by
returned for each report item. all versioning-unaware clients. A server MAY allow modifications to
the revision selection rule of the default workspace.
5.2. Default History 3.6 Configurations
Resources MUST support the DAV:defaulthistory report. This A workspace selects a volatile set of revisions. Changes to
enumerates the historical record of revisions that have been selected activities or changes to labels may result in the
visible as the default revision. selection of different revisions. A configuration is a resource
that selects a set of immutable revisions. A workspace whose
version selection rule contains a configuration will always select
the same revisions as long as the configuration is not modified and
no checkouts are performed in that workspace.
Clients can specify the limit parameter to limit the number Configurations are convenient for defining a persistent set of
revisions returned. By definition, revisions are returned in revisions that relate to each other in some specific way at some
reverse chronological order starting with the most recent. point in time. This can be useful for a variety of purposes such as
publishing consistent versions of resources to deploy an
application, or for recovering a specific state for legal or
maintenance reasons.
>>Request 3.7 Versioned Collections
PROPFIND /foo/bar.htm HTTP/1.1 A collection contains a set of named bindings to other resources
Host: www.foobar.com that are the members of that collection. For a versioned
Depth: 0 collection, the bindings are to versioned resources, not to
Content-Type: text/xml particular revisions. To modify the state of a versioned collection
Content-Length: xxxx (i.e. add or remove a binding), the versioned collection must be
checked out, just like any other versioned resource. Requests that
modify the state of a collection member, such as checking it out or
checking in a new revision, have no effect on the state of the
collection. Conversely, requests that modify the state of a
versioned collection, such as deleting or adding a binding to
resource, have no effect on the state of that resource. In
particular, the resource will remain bound in any other revisions
of the collection of which it was a member.
<?xml version="1.0" encoding="utf-8" ?> If a URL identifies a sequence of nested versioned collections,
<D:propfind xmlns:D="DAV:"> revision selection is performed for each versioned collection in
<D:defaulthistory limit=20/> the sequence, to select the versioned collection revision that will
</D:propfind> be used to map the next segment of the URL to the appropriate
versioned resource.
>>Response 4 VERSIONING RESOURCE TYPES AND PROPERTIES
... This section defines the new resource types and properties
<D:multistatus> introduced by WebDAV versioning.
<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>
<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 4.1 Property Attributes
Clients can obtain a list of the active checkouts against a There are several important attributes of properties that will be
resource using PROPFIND and DAV:activecheckouts. defined for every property introduced by this document.
>>Request 4.1.1 Writeable/Readonly Properties
PROPFIND /foo/bar.htm HTTP/1.1 A writeable property can be modified by a client, while a readonly
Host: www.foobar.com property can only be modified by the server.
Revision-Id: VER:FHRJ494059
Depth: 0
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?> All properties defined in this document are writeable unless
<D:propfind xmlns:D="DAV:"> explicitly marked as "readonly".
<D:activecheckouts/>
</D:propfind>
>>Response 4.1.2 Immutable/Mutable Properties
HTTP/1.1 207 Multi-Status An immutable resource is a resource whose value cannot change. An
Content-Type: text/xml immutable property is a property whose value cannot change when it
Content-Length: xxx appears on an immutable resource. A mutable property is a property
whose value can change, even when it appears on an immutable
resource.
<?xml version="1.0" encoding="utf-8" ?> All properties defined in this document are immutable unless
<D:multistatus xmlns:D="DAV:"> explicitly marked as "mutable".
<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>
<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 4.1.3 Property Resources
Resources SHOULD support the DAV:directlineage report. This There are various properties whose contents can be represented as
enumerates the direct parent revisions of the resource. an HTTP resource. Doing so allows a client to use the full set of
HTTP methods to manipulate the contents of that property, rather
than being limited to the functionality provided by PROPFIND and
PROPPATCH. This is particularly valuable for a property value that
is naturally represented as a collection resource. By default,
PROPFIND returns an XML document as the value of a property
resource; however, when a DAV:property-resource-URL element is
specified in the PROPFIND request body, PROPFIND will return the
URL of the property resource. Servers MAY support DAV:property-
resource-URL for a property, but MUST support the default XML
value.
Clients can request that a report be based on the namespace entry All properties that are property resources are explicitly marked as
specified, or the associated DAV:vresourceid. Clients use the "resource". If the property resource is a collection, the property
scope parameter to specify (name or id). is marked as "collection".
Clients can specify the limit parameter to limit the number 4.2 Resource Properties
revisions returned.
>>Request WebDAV versioning introduces the following additional properties
for a resource:
PROPFIND /foo/bar.htm HTTP/1.1 4.2.1 DAV:author (immutable) [Core]
Host: www.foobar.com
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> This property is used to track the author of a resource.
<D:propfind xmlns:D="DAV:">
<D:directlineage scope="name"/>
</D:propfind>
>>Response 4.2.2 DAV:comment (immutable) [Core]
... This property is used to track a brief comment about a resource.
<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>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 4.3 Revision Properties
Resources SHOULD support the DAV:fulllineage report. This WebDAV versioning introduces the following additional properties
enumerates the full graph of revisions for this resource. for a revision:
Clients can request that a report be based on the namespace entry 4.3.1 DAV:revision-id (readonly) [Core]
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 The DAV:revision-id is an identifier assigned to a revision by the
revisions returned. server. Whenever a revision is created or modified by a CHECKIN, it
must be assigned a new DAV:revision-id. A revision cannot be given
a DAV:revision-id that has been given to any other revision of that
versioned resource, even a revision that has been deleted.
>>Request 4.3.2 DAV:predecessor (readonly, resource) [Core]
PROPFIND /foo/bar.htm HTTP/1.1 The DAV:predecessor of a revision is the revision that was checked
Host: www.foobar.com out to produce a working resource that was checked in to produce
Depth: 0 this revision. The XML document for DAV:predecessor contains the
Content-Type: text/xml revision-id of the DAV:predecessor.
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> 4.3.3 DAV:successors (readonly, mutable, collection) [Core]
<D:propfind xmlns:D="DAV:">
<D:fulllineage scope="name"/>
</D:propfind>
>>Response The DAV:successors collection of a revision contains the revisions
whose DAV:predecessor is that revision. The XML document for
DAV:successors contains a list of the revision-id's of the
DAV:successors.
... 4.3.4 DAV:single-checkout (mutable) [Core]
<D:multistatus> When the DAV:single-checkout property of a revision is set, only
<D:response> one working resource can be checked out from that revision at any
<D:href>http://www.foobar.com/foo/bar.htm</D:href> time.
<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>
<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 4.3.5 DAV:auto-version (mutable) [Core]
Many clients require more sophisticated management and organization When the DAV:auto-version property of a revision is set, a PUT
of their versioned data. For this reason, configuration support is request (or any request that modifies an immutable aspect of the
defined as part of this specification. revision) to this revision is automatically preceded by a CHECKOUT
into the default workspace and followed by a CHECKIN. This allows
a versioning-unaware client to modify a version-controlled
resource. The DAV:auto-version value can take the same values as
the DAV:checkin-policy of a working resource, and the DAV:checkin-
policy of the automatically created working resource is set to be
the DAV:auto-version policy of the revision.
Configuration management is a large space. This specification 4.3.6 DAV:revision-labels (mutable) [Core]
addresses several types of configurations:
- Dynamic: A dynamic configuration is a collection of specific This property is used to identify labels that are associated with a
revisions of selected versioned resources based on selection specific revision.
rules. This can be used for labels, floating labels, etc.
- Workspace: A workspace configuration is a mechanism for tracking 4.3.7 DAV:checkin-date (readonly) [Core]
and managing parallel changes to multiple resources.
Configurations provide a mechanism for organizing resources and This property contains the date when the revision was checked in.
quick access to specific revisions of resources. Clients can This property is automatically assigned and is formatted using
access resources in the context of a configuration. By referencing ISO8061.
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 4.3.8 DAV:working-resources (readonly, collection) [Core]
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 This property is a collection of the workspaces that contain
specified. This requests that the default revision for the working resources whose DAV:predecessor is this revision. The XML
specified configuration be used. Requests that include both a document for DAV:working-resources contains a description of these
revision id and a configuration id MUST fail if the specified working resources.
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 4.3.9 DAV:history-uuid (readonly) [Core]
Configuration support is optional. This example shows that the The DAV:history-uuid of a revision is the DAV:uuid of the history
/somefolder resource supports configurations. resource whose DAV:revisions collection contains this revision.
>> Request 4.3.10 DAV:history (readonly, resource) [Core]
OPTIONS /somefolder/ HTTP/1.1 The DAV:history of a revision is the history resource whose
Host: www.foobar.com DAV:revisions collection contains this revision. The XML document
Content-Length: xxx for DAV:history contains a description of revisions that form the
Content-Type: text/xml line-of-descent to this revision.
<?xml version="1.0" encoding="utf-8" ?> 4.3.11 DAV:merge-predecessors (mutable, collection) [Merging]
<D:options xmlns:D="DAV:">
<D:verinfo/>
</D:options>
>> Response The DAV:merge-predecessors collection of a revision contains the
revisions whose contents were explicitly merged by the client into
that revision. The client is free to add or delete members to this
collection to more accurately reflect the contents of that
revision. The XML document for DAV:merge-predecessors contains the
revision id's of the DAV:merge-predecessors.
HTTP/1.1 200 OK 4.3.12 DAV:merge-successors (mutable, collection, readonly) [Merging]
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" ?> The DAV:merge-successors collection of a revision contains a
<D:options xmlns:D="DAV:"> binding to each revision whose DAV:merge-predecessors collection
<D:verinfo> contains a binding to that revision. The XML document for
<D:configroot> DAV:merge-successors contains the revision id's of the DAV:merge-
<D:href>http://www.foobar.com/cfgs/</D:href> successors.
</D:configroot>
</D:verinfo>
</D:options>
6.2. Creating Configurations
Servers maintain configurations in a private portion of the 4.4 Working Resource Properties
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 WebDAV versioning introduces the following additional properties
against the configuration namespace. This requests the server to for a working resource:
create a new configuration.
When a configuration is created, special tags can be used to define 4.4.1 DAV:workspace (readonly, resource) [Core]
the characteristics and relationships (e.g. derivations) for the
configuration. The following table enumerates these tags.
Tag Description The DAV:workspace of a working resource is the workspace that
contains this working resource. The XML document for DAV:workspace
contains the URL of this workspace.
<DAV:configurationtype> This tag defines the type 4.4.2 DAV:predecessor (read-only, resource) [Core]
of configuration:
xxx DAV:Dynamic or
</DAV:configurationtype> DAV:Workspace.
<DAV:derivedfrom> This tag allows the client This property contains the revision that was checked out to create
"xxx" to specify a URI to this working resource. The XML document for DAV:predecessor
</DAV:derivedfrom> identify another contains the revision id of DAV:predecessor.
configuration from which
this new configuration is
to be derived.
<DAV:inheritancetype> The configuration 4.4.3 DAV:checkin-policy [Core]
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 The DAV:checkin-policy property of a working resource indicates how
changes from its derived- this working resource should be checked in. The following are
DAV:Manual from configuration, but defined values for DAV:checkin-policy. The default value is
</DAV:inheritancetype> they are not automatically DAV:immutable.
inserted into the
configuration. Instead
they are recorded in
resolution queues (see
Tag Description
later section). DAV:identical-abort - the CHECKIN should fail if the working
resource is identical to its DAV:predecessor.
<DAV:inheritancetype> DAV:identical-uncheckout - an UNCHECKOUT should be applied instead
snapshot of the current of CHECKIN if the working resource is identical to its
DAV:None versions in the derived- DAV:predecessor.
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:overwrite - the working resource should be copied into its
</DAV:basetime> on the current versions in DAV:predecessor instead of creating a new revision.
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 DAV:mutable - a new revision is created that can be overwritten by
resources. Configurations that are derived from another a subsequent DAV:overwrite CHECKIN.
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 DAV:immutable - a new revision is created that cannot be
derived from, and auto-inherits another configuration. For this overwritten by a subsequent DAV:overwrite CHECKIN.
example, the root of the configuration namespace has been
determined to be /cfgs.
>>Request DAV:keep-checked-out - create a new revision but does not delete
the working resource. The DAV:predecessor of the working resource
is changed to be the new revision.
MKCONFIG /cfgs/ HTTP/1.1 DAV:baseline - instead of creating a new revision of the versioned
Host: www.foobar.com collection, create a new baseline for it (the CHECKIN fails unless
Content-Type: text/xml it is applied to a versioned collection with a DAV:baselines
Content-Length: xxxx property).
<?xml version="1.0" encoding="utf-8" ?> 4.4.4 DAV:merge-predecessors (collection) [Merging]
<D:createconfiguration xmlns:D="DAV:">
<D:configurationtype>DAV:Workspace</D:configurationtype>
<D:derivedfrom>http://www.foobar.com/cfgs/DDEJRJ445</D:derivedfrom> The DAV:merge-predecessors collection of a working resource
<D:inherit>Auto</D:inherit> contains the revisions whose contents were explicitly merged by the
</D:createconfiguration> client into that working resource. The client adds and deletes
members of this collection to reflect the set of revisions that
were merged by the client into the working resource. The name of a
DAV:merge-predecessors binding is the DAV:revision-id of that
revision. The XML document for DAV:merge-predecessors contains the
revision id's of the DAV:merge-predecessors.
>>Response 4.4.5 DAV:activity (readonly, resource) [Activity]
HTTP/1.1 201 Created The DAV:activity property of a working resource is the DAV:activity
Location: http://www.foobar.com/cfgs/RYURUS99009 of the workspace when the working resource was checked out. The
Content-Length: 0 XML document for DAV:activity is the URL for the activity.
6.3. Access Using Configurations 4.5 Workspace Properties
Configurations are maintained as a special collection. WebDAV versioning introduces the following additional properties
Configurations maintain referential members to all revisions that for a workspace:
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 4.5.1 DAV:working-resources (readonly, collection) [Core]
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 The DAV:working-resources collection contains the versioned
resources that are checked out into this workspace. The XML
document for DAV:working-resources contains a description of these
working resources.
GET /foo/bar.htm HTTP/1.1 4.5.2 DAV:revision-selection-rule [Core]
Host: www.foobar.com
Configuration-Id: /cfgs/DFEE2034
Content-Length: 0
6.4. Deleting Configurations The DAV:revision-selection-rule of a workspace can contain an XML
document that describes how revision selection will be performed in
that workspace. The working resources checked out into a workspace
take priority over revisions selected by the revision selection
rule, thus target of a versioned resource in a workspace is the
working resource in that workspace for that versioned resource,
else the revision selected by the workspace revision selection
rule. To ensure that working resources continue to be visible in a
workspace after they are checked in, the DAV:label or DAV:activity
of a workspace is usually the first element of the DAV:revision-
selection-rule. If the DAV:revision-selection-rule is not set or is
empty, the revision selection rule will select no revision for any
versioned resource.
To delete a configuration, use the location returned from the Standard revision selection rule elements are defined in this
configuration creation. Note that configurations SHOULD NOT allow document, but additional revision selection rule elements may be
delete if other configurations are derived from them. supported by a WebDAV server.
>>Request 4.5.3 DAV:label [Core]
DELETE /cfgs/RYURUS99009 HTTP/1.1 The DAV:label property of a workspace can contain a revision label.
Host: www.foobar.com When a working resource in a workspace is checked in, it will be
Content-Length: 0 given this label.
6.5. Resolution Queues 4.5.4 DAV:activity [Activity]
There are times when an operation cannot be blocked that will The DAV:activity property of a workspace is the activity that is
result in a state that requires user action. For example, when currently being performed in that workspace. A new working
configurations inherit, there is the potential for conflicts. resource in a workspace will have its DAV:activity property set to
Resolution queues provide a mechanism for discovering these this activity. The XML document for DAV:activity contains the URL
conditions. of DAV:activity.
Configurations track and maintain a list of issues that need to be 4.6 Activity Properties
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.
The resolution queue is obtained by obtaining the WebDAV versioning introduces the following additional properties
DAV:resolutionqueue property from the configuration. This property for an activity:
contains all of the identified issues.
>>Request 4.6.1 DAV:revisions (readonly, collection) [Activity]
PROPFIND /cfgs/FDJE4949 HTTP/1.1 The DAV:revisions collection of an activity contains all revisions
Host: www.foobar.com whose DAV:activity property contains this activity. The XML
Content-Type: text/xml document for DAV:revisions contains the URL's of these revisions.
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?> 4.6.2 DAV:required-activities (collection) [Activity]
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:resolutionqueue/>
</D:prop>
</D:propfind>
>>Response The DAV:required-activities collection of an activity contains the
other activities that form a part of the logical change being
captured by the activity. The DAV:needed-activities of an activity
contribute to the revision selection behavior of that activity when
it is used in a revision selection rule. The purpose of this
property is to identify other activities that are a prerequisite to
this activity. The XML document for DAV:required-activities
contains the URL's of these activities.
HTTP/1.1 207 Multi-Status 4.6.3 DAV:workspace (resource) [Activty]
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?> The DAV:workspace property of an activity contains the workspace
<D:multistatus xmlns:D="DAV:"> that currently has that activity as its DAV:current activity. This
<D:response> implies that at most one workspace can be working in a given
<D:href>http://www.foobar.com/cfgs/FDJE4949</D:href> activity at a time. If any working resource of a workspace is
<D:propstat> checked out into a given activity, the DAV:workspace of that
<D:prop> activity can only be that workspace. The XML document for
<D:resolutionqueue> DAV:workspace contains the URL of the workspace.
<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 4.7 Configuration Properties
removed from the resolution queue.
6.6. Configuration Properties WebDAV versioning introduces the following properties for a
configuration:
The standard PROPFIND and PROPPATCH methods can be used on the 4.7.1 DAV:roots (immutable, collection) [Configuration]
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. The DAV:roots collection of a configuration contains the versioned
Configurations can choose to make this a read-only property. resources that are not named by versioned collection revisions in
that configuration. The XML document for DAV:roots contains the
URL's of these versioned resources.
DAV:derivedfrom - The configuration from which the configuration is 4.8 Versioned Collection Properties
derived. Configurations can choose to make this a read-only
property.
DAV:inheritancetype - The type of inheritance for the WebDAV versioning introduces the following additional properties
configuration. Configurations can choose to make this a read-only for a versioned collection:
property.
DAV:basetime - The base time used to create the configuration. 4.8.1 DAV:baselines (resource) [Baseline]
Configurations can choose to make this a read-only property.
DAV:defaultconfiguration - This property on the configuration root The DAV:baselines of a versioned collection is a versioned
identifies the default workspace configuration to use if one is not configuration whose DAV:roots contains only that versioned
specified. collection. A revision of the DAV:baselines of a versioned
collection effectively provides a "deep-revision" of that versioned
collection. The XML document for DAV:baselines contains the URL of
the versioned configuration.
DAV:resolutionqueue - A list of identified issues that require 4.9 History Resource Properties
client attention.
6.7. Headers WebDAV versioning introduces the following additional properties
for a history resource:
To support configurations, two new headers are introduced that can 4.9.1 DAV:uuid (readonly) [Core]
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 The DAV:uuid is an identifier assigned to a history resource by the
configuration that is to be used when performing an operation. server. A history resource cannot be given a DAV:uuid that has been
given to any other history resource, even a history resource that
has been deleted.
For workspace configurations, this can be specified to set default 4.9.2 DAV:revisions (readonly, collection) [Core]
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 The DAV:revisions collection of a history resource contains all
configuration is used. All servers have a default workspace where revisions of that history resource, where the name of a revision in
resources reside. The configuration "*" can be specified with the DAV:revisions collection is its DAV:revision-id. If a revision
PROPFIND to locate properties irrespective of configuration. id contains a URL reserved character, that character is escaped in
the DAV:revisions name. The XML document for DAV:revisions
contains the URL's of the revisions.
Configuration-Id := "Configuration-Id" ":" (URL | "*") 4.9.3 DAV:revision-labels (collection) [Core]
Note that the configuration id can be used in place of a revision The DAV:revision-labels collection of a history resource contains a
id. In this case, the revision selected is the default revision of binding for each label assigned to any revision of that history
the versioned resource within the specified configuration. resource, where the binding name is that label (reserved URL
characters are escaped) and the binding is to the revision selected
by that label. The client can label and unlabel revisions by
adding and deleting members of the DAV:revision-labels collection.
Target-Configuration - This header is used to specify a target The XML document for DAV:revision-labels contains the URL's of the
configuration when dealing with cross-configuration operations. members of the DAV:revision-labels collection.
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.
Target-Configuration := "Target-Configuration" ":" URL 5 VERSIONING METHODS
7. CONFIGURATION REPORTS 5.1 Existing Methods
Revision history and configuration dependency graphs are accessed This section describes the extensions to the existing WebDAV
via PROPFIND. Note that configurations MAY support multiple styles methods. Under versioning, the methods inherit all of the WebDAV
of history and dependency. To enumerate the supported history functionality with the following extensions.
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 5.1.1 GET
PROPFIND /cfgs/FHJRH3994 HTTP/1.1 When GET is applied to a versioned resource, it returns the body of
Host: www.foobar.com the target of that versioned resource. The result of GET on a
Depth: 0 workspace, activity, or history resource is undefined.
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> 5.1.2 BIND
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:enumreport/>
</D:prop>
</D:propfind>
>>Response When BIND creates a binding in a working resource for a versioned
collection, it MUST fail if the request URL of the BIND is not a
versioned resource.
... 5.1.3 PUT
<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 When PUT is applied to a versioned resource whose target is a
include other properties in the request. These properties are working resource, the PUT is applied to that working resource.
returned for each report item. When PUT is applied to a versioned resource whose target is a
revision, the PUT MUST fail except in the following two cases. If
the revision has a DAV:auto-version property and no Target-Selector
header has been specified, the revision is checked out into the
default workspace, the PUT is applied to the resulting working
resource, and the working resource is checked in. If the revision
is a revision of a baselined collection and the value of
DAV:checkin-policy is DAV:baseline, a new revision of the
DAV:baselines configuration is created by the CHECKIN.
7.1. Configuration Derivation When PUT is applied directly to a revision (i.e. not indirectly
via a versioned resource), it MUST fail.
Configurations MUST support the DAV:configurationderivation report. When PUT is applied to a null resource that is an internal member
This enumerates the full derivation of a configuraiton. Note that of a versioned collection whose target is a working resource, a new
the limit parameter can be specified to limit the number of items versioned resource is created at the request URL of the PUT. When
returned. By definition the order of the configurations is the target is a versioned collection revision, the PUT request
immediate predecessor. fails unless the revision has a DAV:auto-version property and no
Target-Selector header has been specified. If DAV:auto-version is
set, the versioned collection revision is checked out into the
default workspace, a new versioned resource is created as a member
of the working collection, and the working collection is checked
in.
>>Request When a PUT is applied to a workspace, activity or history resource,
it fails.
PROPFIND /cfgs/BHFR59593 HTTP/1.1 5.1.4 PROPFIND
Host: www.foobar.com
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> If a DAV:property-resource-URL is specified under a DAV:prop
<D:propfind xmlns:D="DAV:"> element in a PROPFIND request body, the property resource URL of
<D:configurationderivation limit=100/> that property will be returned in the PROPFIND response instead of
</D:propfind> the default XML document for that property resource. If a
DAV:property-resource-URL is specified directly under the
DAV:propfind element, the property resource URL will be returned
for all of the property resources in the PROPFIND response.
>>Response 5.1.5 PROPPATCH
... When PROPPATCH is applied to a versioned resource, its behavior is
<D:multistatus> similar to that of PUT. In particular, when PROPPATCH is applied to
<D:response> an immutable property of a revision, it MUST fail unless the
<D:href>http:/www.foobar.com/cfgs/234</D:href> revision has a DAV:auto-version property.
<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 5.1.6 DELETE
Configurations SHOULD support the DAV:configurationmerge report. When DELETE is applied to a versioned resource whose target is a
This enumerates the derivation of a configuration including merges revision, the versioned resource is deleted from the collection
from one configuration to another. that contains it, but the revision is unaffected. When DELETE is
applied to a workspace, the workspace and all working resources of
that workspace are deleted.
>>Request When DELETE is applied to a member of the DAV:revisions collection
of a history resource, it fails unless the All-Bindings header is
specified. When DELETE is applied to a history resource, the
history resource and all members of the DAV:revisions collection of
that history resource are deleted.
PROPFIND /cfgs/BHFR59593 HTTP/1.1 5.1.7 COPY
Host: www.foobar.com
Depth: 0
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> When COPY is applied to a versioned resource, it is applied to the
<D:propfind xmlns:D="DAV:"> target of the versioned resource. That is, only the selected
<D:configurationmerge/> revision is copied, not the full version history.
</D:propfind>
>>Response When a COPY request is applied to a workspace, activity, or history
resource, it fails.
... 5.1.8 MOVE
<D:multistatus> When MOVE is applied to a versioned resource, the MOVE request MUST
<D:response> fail unless a binding to that versioned resource can be created at
<D:href>http:/www.foobar.com/cfgs/234</D:href> the Destination of the MOVE.
<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 When a MOVE request is applied to an activity or a history
resource, it fails.
Dynamic configurations provide a mechanism to identify all Any request to MOVE a specific revision, and not the versioned
revisions that match specific criteria. For example, "all resource, MUST fail.
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 5.1.9 LOCK
identifies the different styles of dynamic configurations to be
supported. This specification defines a single common type,
DAV:basicrsr.
>>Request A write lock on a versioned resource is applied to the target of
that versioned resource.
PROPFIND /cfgs/FHHE49495 HTTP/1.1 A write lock on a revision prevents unauthorized modifications to
Host: www.foobar.com the properties of that revision.
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?> A write lock on a working resource prevents unauthorized changes to
<D:propfind xmlns:D="DAV:"> the body or properties of that working resource.
<D:prop>
<D:rsrtypes/>
</D:prop>
</D:propfind>
>>Response A write lock on an activity prevents unauthorized modifications to
the properties of that activity.
HTTP/1.1 207 Multi-Status A write lock on a history resource places a write lock on all
Content-Type: text/xml revisions of that history resource.
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?> A write lock on a workspace prevents unauthorized modifications to
<D:multistatus xmlns:D="DAV:"> the properties of that workspace.
<D:response>
<D:href>http://www.foobar.com/cfgs/FHHE49495</D:href>
<D:propstat>
<D:prop>
<D:rsrtypes>
<D:basicrsr/>
</D:rsrtypes>
</D:prop>
</D:propstat>
</D:response>
</D:multistatus>
Clients establish a selection criteria by setting the 5.1.10 OPTIONS
DAV:selectionrule property. Once set, the dynamic configuration
collection contains references to the matching resources.
>>Request The OPTIONS method allows the client to discover the level of
versioning support provided by a server.
PROPPATCH /cfgs/FHHE49495 HTTP/1.1 The following defines the BNF for the Versioning header:
Host: www.foobar.com
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0" encoding="utf-8" ?> Versioning := "Versioning" ":" Ver-type-list
<D:propertyupdate xmlns:D="DAV:"> Ver-type-list := Ver-type | (Ver-type-list "," Ver-type)
<D:set> Ver-type := "Core"
<D:prop> | "Activity"
<D:selectionrule> | "Merging"
<D:basicdynamicconfig> | "Configuration"
... | "Versioned-Collection"
</D:basicdynamicconfig> | "Baseline"
</D:selectionrule>
</D:prop>
</D:set>
</D:propertyupdate>
The DAV:basicrsr tag groups the selection criteria that are used to 5.2 New Methods
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 WebDAV versioning introduces two new methods, MKRESOURCE and
REPORT, that are not specific to versioning but are needed to
support the versioning extensions.
- DAV:or - Any of the included tags MUST be true to select 5.2.1 MKRESOURCE
- DAV:not - The include tag should be inverted (logically) The MKRESOURCE method requests the simultaneous creation of a
resource, identified by the Request URI, and initialization of its
properties. Creation of the resource and initialization of its
properties MUST both occur, or neither occurs. The request message
body of the MKRESOURCE method is the same as for the PROPPATCH
method, i.e. it MUST contain the DAV:propertyupdate XML element,
defined in section 12.13 of [RFC2518]. The property update
directives in the request message body provide the initial values
of the properties of the new resource. The type of the created
resource is specified by the DAV:resourcetype property, if present.
If the DAV:resourcetype property is not specified, the created
resource is an ordinary (i.e. untyped) resource. Like PROPPATCH,
instruction processing MUST occur in the order instructions are
received (i.e. from top to bottom). Instructions MUST all be
executed, or none executed. If MKRESOURCE is applied to an
existing resource, that resource is deleted prior to MKRESOURCE
processing. The behavior of MKRESOURCE on an existing resource can
be explicitly controlled through use of the Overwrite header.
- DAV:href - The resource URL MUST be the included URL MKRESOURCE can be used to create a new activity in a repository
DAV:activities collection. When MKRESOURCE is used to create a
repository from an existing versionable collection, every member of
that versionable collection is also placed under version control as
a history resource in that repository.
- DAV:label - A revision MUST have the specified label Status Codes:
- DAV:tip - The "tip" revision is selected 201 (Created) - The new resource has successfully been created.
- DAV:revisionid - The specified revision is selected 207 (Multi-Status) - If any error was encountered in the creation
of the resource, this response is generated. Status codes defined
for use with PROPPATCH (defined in section 8.2.1 of [RFC2518])
SHOULD be used to represent error cases in setting the value of
properties.
- DAV:configurationid - The configuration MUST be the specified TBD - Explain effect on existing resource types
value
- DAV:branchid - The branch MUST be the specified value TBD - Give request/response example
- DAV:depth - Used with DAV:href to indicate a recursive match 5.2.2 REPORT
TBD - provide full DTD
The following example illustrates a selection rule that includes The REPORT request is an extensible mechanism for obtaining
all revisions in the /Foo/Bar folder (and below) that have been information about a resource. This differs from OPTIONS because
labeled as "Beta1". the information is not static. That is, it is typically a report
that requires server processing in order to generate.
<?xml version="1.0" encoding="utf-8" ?> The REPORT method takes an XML body document that specifies the
<D:basicrsr xmlns:D="DAV:"> type of report. If no report is requested, the method returns a
<D:and> list of available reports.
<D:href>http:/www.foobar.com/Foo/Bar/<D:depth>infinity</D:depth>< TBD - More details on error codes
/D:href>
<D:label>Beta1</D:label>
</D:and>
</D:basicrsr>
9. WORKSPACE CONFIGURATIONS TBD - Give request/response example
Branching provides a mechanism for parallel changes to a resource. 5.3 New Versioning Methods
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 WebDAV versioning introduces three new methods to support the
my companies e-commerce site. These have been put in the V1 checkout/checkin versioning model.
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 5.3.1 CHECKOUT
Clients need to be able to access and manage the contents of a A CHECKOUT request can only be applied to a versioned resource.
configuration. This is done using several different DAV methods. When a CHECKOUT request is applied to a versioned resource whose
target is a revision, a new working resource is created that is a
copy of the revision, and the DAV:predecessor of the working
resource is set to be that revision. If the DAV:predecessor has a
DAV:single-checkout property and is already checked out into a
workspace, the CHECKOUT request fails. The DAV:workspace of the
working resource is set to be the workspace specified in the
Target-Selector header. If the Target-Selector is not a workspace
or if there is no Target-Selector header, the DAV:workspace for
that working resource is allocated by the server. The body of the
CHECKOUT request can be used to initialize the DAV:checkin-policy
of the working resource.
The COPY method can be used to copy a specific revision of a When a CHECKOUT request is applied to a versioned resource whose
resource. However, this results in a new versioned resource being target is a working resource, the CHECKOUT request MUST fail.
created.
Resources are added to and removed from workspace configurations On CHECKOUT, the DAV:activity of the new working resource is set to
using the MKREF and DELREF methods defined by the DAV Advanced be the DAV:activity of the current workspace. If DAV:activity is
Collections Working Group. Note that direct references are not set, a server with activity support automatically assigns an
required. activity to the new working resource. The CHECKOUT request fails
if neither DAV:activity nor DAV:label is set.
Clients can obtain the contents of a configuration using PROPFIND TBD - Failures must include "policy not supported"
to enumerate the hierarchy under the configuation's collection. As
well, as stated above, clients can use the Configuration-Id header
as described previously.
9.2. Default Workspace Configurations TBD - More details on error codes
Clients can establish a default workspace configuration that is to TBD - Give request/response example
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 5.3.2 CHECKIN
SETDEFAULT /cfgs/ HTTP/1.1 When a CHECKIN request is applied to a versioned resource whose
Host: www.foobar.com target is a working resource, a copy of the working resource is
Content-Type: text/xml made a new revision of that versioned resource and the working
Content-Length: xxx resource is deleted. The new revision is added to the
DAV:successors collection of the DAV:predecessor of the new
revision, and the workspace of the working resource is deleted from
the DAV:working-resources collection of the DAV:predecessor.
<?xml version="1.0" encoding="utf-8" ?> The body of a CHECKIN request can be used to override the current
<D:setdefault xmlns:D="DAV:"> DAV:checkin-policy values of the working resource. The effect of
<D:href>http://www.foobar.com/cfgs/CHFH49594/</D:href> DAV:checkin-policy on a CHECKIN request is described in the
</D:setdefault> definition of the DAV:checkin-policy property.
>>Response When the CHECKIN method is applied to a resource that is
versionable, but not currently versioned, the resource is put under
version control. If a versionable collection is put under version
control, all members of that collection are put under version
control as well.
HTTP/1.1 200 OK TBD - More details on error codes
Content-Length: 0
10. CHECKIN SETS TBD - Explain effect on existing resource types
Clients may desire the ability to track a set of changes as a unit. TBD - Give request/response example
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 5.3.3 UNCHECKOUT
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 When an UNCHECKOUT request is applied to a versioned resource whose
includes the location of the new checkin set. target is a working resource, the DAV:workspace of that working
resource is deleted from the DAV:working-resources collection of
the DAV:revision of the working resource, and the working resource
is deleted. This effectively cancels the CHECKOUT request that
produced the working resource.
>>Request TBD - More details on error codes
MKCHECKINSET /cs/244 HTTP/1.1 TBD - Explain effect on existing resource types
Host: www.foobar.com
Content-Length: 0
>>Response TBD - Give request/response example
HTTP/1.1 201 CREATED 5.4 New Versioning Headers
Host: www.foobar.com
Location: http://www.foobar.com/cs/244
Content-Length: 0
The following example illustrates use of checkin sets. 5.4.1 Target-Selector
>>Request The Target-Selector header contains a workspace URL or a revision
name. The Target-Selector header is used to specify which working
resource or revision of a versioned resource should be its target.
If a Target-Selector header is omitted in a request on a versioned
resource, the default workspace is implicitly used as the Target-
Selector.
CHECKIN /foo/bar HTTP/1.1 6 THE DAV VERSIONING XML ELEMENTS
Host: www.foobar.com
Lock-Token: <opaquelocktoken:rejrei-43343-rereffre>
Checkin-Set: /cs/244
Content-Type: text/html
Content-Length: xxxx
<D:checkin> 6.1 Revision Selection Rule Elements
...
</D:checkin>
The following properties MUST be supported on all checkin set A revision selection rule document is the value of the
collections: DAV:revision-selection-rule property of a workspace.
Semantically, a revision selection rule (or RSR) element can be
applied to an arbitrary versioned resource, and will either select
a particular revision of that versioned resource or select no
revision of that versioned resource. If it selects a particular
revision, it may also detect a conflict (e.g. when there were
multiple candidates for selection). A document describing the
conflicts can be obtained through a conflict REPORT request.
DAV:closed - This is a true (1) / false (0) property that indicates 6.1.1 DAV:rsr-configuration
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: A DAV:rsr-configuration element contains the URL of a
configuration. If the configuration contains a revision of the
versioned resource, that revision is selected by the DAV:rsr-
configuration element; otherwise, no revision is selected. A
DAV:rsr-configuration element never generates a conflict.
DAV:checkinid - This read-only property returns the checkin id 6.1.2 DAV:rsr-activity-latest
associated with this revision of the resource.
A checkin that references a checkin set MUST be made to the A DAV:rsr-activity-latest element contains the URL of an activity.
configuration associated with the checkin set. If the DAV:revisions collection of the activity contains one or
more revisions of the versioned resource, then the latest revision
in that activity is selected. The semantics of activities ensures
that there always is a unique latest revision for an activity. If
the activity contains no revisions of a versioned resource, the
DAV:rsr-activity-latest element selects no revisions of that
versioned resource.
11. VERSION MAPPING If the DAV:needed-activities collection of an activity is non-
empty, then the DAV:rsr-activity element acts like a DAV:rsr-merge
element that contains that activity and each of the DAV:needed-
activities. A DAV:rsr-activity-latest element can generate
conflicts only if the DAV:needed-activities collection is non-
empty.
This specification defines headers to specify configurations and 6.1.3 DAV:rsr-label
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, A DAV:rsr-label element contains a label. If a revision of the
removed, and modified, the changes are reflected in any active versioned resource has that label, that revision is selected by the
maps. DAV:rsr-label element; otherwise, no revision is selected. A
DAV:rsr-label element never generates a conflict.
To delete a mapping, use DELETE against the URI specified in the 6.1.4 DAV:rsr-revision-id
MKMAP request.
11.1. Discovery A DAV:rsr-revision-id element contains a revision id. If a
revision of the versioned resource has that revision id, that
revision is selected by the DAV:rsr-revision-id element; otherwise,
no revision is selected. A DAV:rsr-revision-id element never
generates a conflict.
Mapping support is optional and support is discovered using OPTIONS 6.1.5 DAV:rsr-latest
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 A DAV:rsr-latest element selects the revision of that versioned
mapping to the /map/ root in the namespace. resource with the latest DAV:creationdate. A DAV:rsr-latest
element never generates a conflict.
>> Request 6.1.6 DAV:rsr-or
OPTIONS /cfgs/DFEE2034 HTTP/1.1 A DAV:rsr-or element contains a sequence of RSR elements. The
Host: foobar.com behavior of a DAV:rsr-or element is identical to the behavior of
Content-Type: text/xml the first element in this sequence that selects a revision of the
Content-Length: xxx versioned resource. If no element selects a revision, then the
DAV:rsr-or element selects no revision of that versioned resource.
<?xml version="1.0" encoding="utf-8" ?> 6.1.7 DAV:rsr-merge
<D:options xmlns:D="DAV:">
<D:verinfo/>
</D:options>
>> Response A DAV:rsr-merge element contains a sequence of RSR elements. If
one of the elements in this sequence selects a revision that is the
descendent of all of the other revisions selected by elements in
this sequence, then that revision is selected by the DAV:rsr-merge
element. If no selected revision is a descendent of all the other
selected revisions, then the result of the DAV:rsr-merge is a
"conflict". A conflicts REPORT request can be used to identify the
conflicts.
HTTP/1.1 200 OK 6.2 Report Elements
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" ?> 6.2.1 Conflicts Report
<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>
11.2. Mapping Configurations
The MKMAP method is used to create namespaces based on a A conflicts report describes the conflicts in a specified workspace
configuration. When a configuration is mapped to a new namespace, for a specified resource or for all the members of a specified
all elements within the configuration can be directly accessed versioned collection.
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 6.2.1.1 DAV:conflicts-report-request
contents of the /cfgs/DFEE2034 configuration.
>> Request A DAV:conflicts-report-request contains the URL of a workspace and
the URL of a versioned resource.
MKMAP /maps/mymap HTTP/1.1 6.2.1.2 DAV:conflicts-report-response
Host: foobar.com
Configuration-Id: /cfgs/DFEE2034
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> A DAV:conflicts-report-response contains a DAV:conflict element for
<D:configurationmap xmlns:D="DAV:"/> each versioned resource for which the revision selection rule
specified in the DAV:conflicts-report-request produced a conflict.
The DAV:conflict element identifies the versioned resource which
generated a conflict, as well as information about how to resolve
the conflict (such as the revisions that would need to be merged).
>> Response 6.2.1.3 DAV:conflict
HTTP/1.1 201 CREATED The DAV:conflict element contains the URL of a versioned resource
Context-Length: 0 for which the revision selection rule generated a conflict, a
DAV:common-ancestor for the conflict, and two or more
DAV:contributor elements for the conflict.
11.3. Mapping Resource Versions 6.2.1.4 DAV:common-ancestor
The MKMAP method is also used to create namespaces based on a The DAV:common-ancestor element identifies a revision that is a
resource's versions (i.e., its revision graph). When a resource is common ancestor of all the DAV:contributor elements for a
mapped, its revision history (revision graph) within the particular conflict.
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 6.2.1.5 DAV:contributor
following revision history of the versioned resource bar.htm:
V1 -> V2 -> V3 (primary branch) The DAV:contributor element identifies a revision that is selected
| by an element of the revision selection rule but that is not an
+-> V1.1 -> V1.2 ("test" branch) ancestor of any of the other revisions selected by the revision
selection rule.
The following diagrams illustrate possible mappings: 6.2.2 Compare Report
(DAV:detailedmap) (DAV:branchmap) 6.2.2.1 DAV:compare-report-request
(DAV:nestedbranchmap)
V1 Primary Test Primary A DAV:compare-report-request contains the URL's of two resources of
| | | | the same type.
+----+--------+ 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 6.2.2.2 DAV:compare-report-response
versions of the /foo/bar.htm resource in the /cfgs/DFEE2034
configuration.
>> Request A DAV:compare-report-response identifies the differences between
two resources of the same type. These differences are indicated by
appropriate DAV:added, DAV:deleted, and DAV:changed elements.
MKMAP /maps/mymap2 HTTP/1.1 In particular, if a DAV:compare-report-request is applied to two
Host: foobar.com configuration revisions. The DAV:compare-report-response contains
Configuration-Id: /cfgs/DFEE2034 the revisions, needed-configurations, and activities that are
Content-Type: text/xml selected by one configuration revision but not the other.
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?> 6.2.2.3 DAV:added
<D:revisionmap xmlns:D="DAV:">
<D:href>/foo/bar.htm</D:href>
<D:mapstyle>DAV:detailedmap</D:mapstyle>
</D:revisionmap>
>> Response A DAV:added element identifies something that appears in the second
resource but not in the first.
HTTP/1.1 201 CREATED 6.2.2.4 DAV:deleted
Context-Length: 0
Note that resources MAY support any mapping styles, however, if A DAV:deleted element identifies something that appears in the
they support MKMAP, then it MUST support DAV:detailedmap as first resource but not in the second.
illustrated above.
12. THE DAV VERSIONING GRAMMAR 6.2.2.5 DAV:changed
To be supplied - Describe and detail the DTDs A DAV:changed element identifies something that is in both
resources but that is in some way different in the two resources.
For example, when two configurations are being compared, a
DAV:changed element can identify a versioned resource, a versioned
collection, or an activity. A versioned resource has changed if
the configurations select different revisions of that versioned
resource. A versioned collection has changed if the configurations
select different revisions or different baselines of that versioned
collection. An activity has changed if both configurations
contain that activity but the DAV:revisions or DAV:needed-
activities of that activity were different when those
configurations were created.
13. INTERNATIONALIZATION CONSIDERATIONS 7 INTERNATIONALIZATION CONSIDERATIONS
To be supplied. To be supplied.
14. SECURITY CONSIDERATIONS NOTE: If a revision label contains a URL reserved character, that
character is escaped in the DAV:revision-labels name.
8 SECURITY CONSIDERATIONS
To be supplied. To be supplied.
15. SCALABILITY 9 SCALABILITY
To be supplied. To be supplied.
16. AUTHENTICATION 10 AUTHENTICATION
Authentication mechanisms defined in WebDAV will also apply to DAV Authentication mechanisms defined in WebDAV will also apply to DAV
Versioning. Versioning.
17. IANA CONSIDERATIONS 11 IANA CONSIDERATIONS
This document uses the namespace defined by [WebDAV] for XML This document uses the namespace defined by [RFC2518] for XML
elements. All other IANA considerations mentioned in [WebDAV] also elements. All other IANA considerations mentioned in [RFC2518]
applicable to DAV Versioning. also applicable to DAV Versioning.
18. COPYRIGHT 12 INTELLECTUAL PROPERTY
To be supplied. The following notice is copied from RFC 2026 [RFC2026], section
10.4, and describes the position of the IETF concerning
intellectual property claims made against this document.
19. INTELLECTUAL PROPERTY The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use other technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on
the IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances
of licenses to be made available, or the result of an attempt made
to obtain a general license or permission for the use of such
proprietary rights by implementers or users of this specification
can be obtained from the IETF Secretariat.
To be supplied. The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF
Executive Director.
20. REFERENCES 13 ACKNOWLEDGEMENTS
[DAVVERREQ] TBD, "Requirements for DAV Versioning and Variant This protocol is the collaborative product of the Delta-V design
Authoring", October 1998, internet-draft, work-in-progress, draft- team: Jim Amsden (IBM, DeltaV Chair), Geoffrey Clemm (Rational),
ietf-webdav-versionreqs-00.txt Bruce Cragun (Novell), David Durand (INSO), Chris Kaler
(Microsoft), Jeff McAffer (OTI), Bradley Sergeant (Merant), and Jim
Whitehead (UCI). We would like to acknowledge the foundation laid
for us by the authors of the WebDAV and HTTP protocols upon which
this protocol is layered, and the invaluable feedback from the
WebDAV and DeltaV working groups.
[Kaler] C. Kaler, "Versioning Extensions for WebDAV", September 14 INDEX
1998, internet-draft, work-in-progress, draft-kaler-webdav-
versioning-00. To be supplied.
15 REFERENCES
[RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T.
Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068,
U.C. Irvine, DEC, MIT/LCS, January 1997. U.C. Irvine, DEC, MIT/LCS, January 1997.
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
Requirement Levels." RFC 2119, BCP 14. Harvard University. March, Requirement Levels." RFC 2119, BCP 14. Harvard University. March,
1997. 1997.
[WebDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D. [RFC2518] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D.
Jenson, "Extensions for Distributed Authoring on the World Wide Jenson, "HTTP Extensions for Distributed Authoring - WEBDAV", RFC
Web", April. 1998, internet-draft, work-in-progress, draft-ietf- 2518, Microsoft, UCIrvine, Netscape, Novell, February. 1999.
webdav-protocol-08.
[White] E.J. Whitehead, "A Web Versioning Protocol", June 1998, [AdvCol] http://www.ietf.org/internet-drafts/draft-ietf-webdav-
internet-draft, work-in-progress, draft-whitehead-webdav- collection-protocol-03.txt
versioning-00.
21. AUTHOR'S ADDRESSES [VerGoal] http://www.ietf.org/internet-drafts/draft-ietf-webdav-
version-goals-02.txt
Christopher Kaler, Editor 16 AUTHORSĘ ADDRESSES
Geoffrey Clemm
Rational Software
20 Maguire Road
Lexington MA 02421-3104
Email: geoffrey.clemm@rational.com
Christopher Kaler
Microsoft Microsoft
One Microsoft Way One Microsoft Way
Redmond WA, 9085-6933 Redmond WA 9085-6933
Email:ckaler@microsoft.com Email:ckaler@microsoft.com
Jim Amsden 17 OPEN ISSUES
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 The following list identifies key open issues against this
document: document:
. Can you checkout a collection? What does it mean? @ TODO: Add the appropriate DAV:resourcetype properties to
workspace, history resource, activity, and configuration.
. What tags do we want to use for resource/configuration report
results?
. 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 @ TODO: Flush out details on methods: e.g., request/response
examples needed.
Initial Draft based on [White] and [Kaler]. @ TODO: DTDs and semantics of properties
Oct 24, 1998 @ TODO: Lots of details
Incorporate feedback from October 01-02 working group meeting. @ ISSUE: How are policies discovered?
Jan 20, 1999 @ ISSUE: Does Versioning have to be a header, or can it be the body
of the OPTIONS response?
Incorporate feedback from December 1998 working group meeting. @ ISSUE: Couldn't MKRESOURCE be handled just by allowing PROPPATCH
to be applied to a null resource?
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/