INTERNET-DRAFT   

draft-ietf-webdav-versioning-xx.7

 

 

 

 

 

 

 

 

 

Expires April 16, 2004

G. Clemm

IBM

J. Amsden

IBM

T. Ellison

IBM

Chris Kaler

Microsoft

Jim Whitehead

U.C. Santa Cruz


October 16, 2003

Versioning Extensions to WebDAV

Status of this Memo

This document is an Internet-Draft and is in full conformance with all provisions of RFC 2026, Section 10.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups.  Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time.  It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

Abstract

This document specifies a set of methods, headers, and resource types that define the WebDAV Versioning extensions to the HTTP/1.1 protocol.  WebDAV Versioning will minimize the complexity of clients that are capable of interoperating with a variety of versioning repository managers, to facilitate widespread deployment of applications capable of utilizing the WebDAV Versioning services.  WebDAV Versioning includes: automatic versioning for versioning-unaware clients, version history management, workspace management, baseline management, activity management, and URL namespace versioning.


Table of Contents

1     Introduction. 7

1.1      Relationship to WebDAV. 7

1.2      Notational Conventions. 7

1.3      Terms. 8

1.4      Property Values. 10

1.4.1    Initial Property Value. 10

1.4.2    Protected Property Value. 10

1.4.3    Computed Property Value. 10

1.4.4    Boolean Property Value. 10

1.4.5    DAV:href Property Value. 10

1.5      DAV Namespace XML Elements in Request and Response Bodies. 10

1.6      Method Preconditions and Postconditions. 11

1.6.1    Example - CHECKOUT request with DAV:must-be-checked-in response. 11

1.7      Clarification of COPY Semantics with Overwrite:T. 11

1.8      Versioning Methods and Write Locks. 12

2     Basic Versioning Features. 12

2.1      Basic Versioning Packages. 12

2.2      Basic Versioning Semantics. 13

2.2.1    Creating a Version-Controlled Resource. 13

2.2.2    Modifying a Version-Controlled Resource. 14

2.2.3    Reporting. 15

3     Version-Control Feature. 15

3.1      Additional Resource Properties. 15

3.1.1    DAV:comment 16

3.1.2    DAV:creator-displayname. 16

3.1.3    DAV:supported-method-set (protected) 16

3.1.4    DAV:supported-live-property-set (protected) 16

3.1.5    DAV:supported-report-set (protected) 16

3.2      Version-Controlled Resource Properties. 16

3.2.1    DAV:checked-in (protected) 17

3.2.2    DAV:auto-version. 17

3.3      Checked-Out Resource Properties. 17

3.3.1    DAV:checked-out (protected) 17

3.3.2    DAV:predecessor-set 17

3.4      Version Properties. 18

3.4.1    DAV:predecessor-set (protected) 18

3.4.2    DAV:successor-set (computed) 18

3.4.3    DAV:checkout-set (computed) 18

3.4.4    DAV:version-name (protected) 18

3.5      VERSION-CONTROL Method. 18

3.5.1    Example - VERSION-CONTROL. 19

3.6      REPORT Method. 19

3.7      DAV:version-tree Report 20

3.7.1    Example - DAV:version-tree Report 20

3.8      DAV:expand-property Report 22

3.8.1    Example - DAV:expand-property. 22

3.9      Additional OPTIONS Semantics. 23

3.10       Additional PUT Semantics. 24

3.11       Additional PROPFIND Semantics. 24

3.12       Additional PROPPATCH Semantics. 24

3.13       Additional DELETE Semantics. 25

3.14       Additional COPY Semantics. 25

3.15       Additional MOVE Semantics. 26

3.16       Additional UNLOCK Semantics. 26

4     Checkout-In-Place Feature. 26

4.1      Additional Version Properties. 26

4.1.1    DAV:checkout-fork. 26

4.1.2    DAV:checkin-fork. 27

4.2      Checked-Out Resource Properties. 27

4.2.1    DAV:checkout-fork. 27

4.2.2    DAV:checkin-fork. 27

4.3      CHECKOUT Method (applied to a version-controlled resource) 27

4.3.1    Example - CHECKOUT of a version-controlled resource. 28

4.4      CHECKIN Method (applied to a version-controlled resource) 29

4.4.1    Example - CHECKIN. 30

4.5      UNCHECKOUT Method. 30

4.5.1    Example - UNCHECKOUT. 31

4.6      Additional OPTIONS Semantics. 31

5     Version-History Feature. 31

5.1      Version History Properties. 31

5.1.1    DAV:version-set (protected) 31

5.1.2    DAV:root-version (computed) 31

5.2      Additional Version-Controlled Resource Properties. 32

5.2.1    DAV:version-history (computed) 32

5.3      Additional Version Properties. 32

5.3.1    DAV:version-history (computed) 32

5.4      DAV:locate-by-history Report 32

5.4.1    Example - DAV:locate-by-history Report 32

5.5      Additional OPTIONS Semantics. 33

5.6      Additional DELETE Semantics. 34

5.7      Additional COPY Semantics. 34

5.8      Additional MOVE Semantics. 34

5.9      Additional VERSION-CONTROL Semantics. 35

5.10       Additional CHECKIN Semantics. 35

6     Workspace Feature. 35

6.1      Workspace Properties. 35

6.1.1    DAV:workspace-checkout-set (computed) 36

6.2      Additional Resource Properties. 36

6.2.1    DAV:workspace (protected) 36

6.3      MKWORKSPACE Method. 36

6.3.1    Example - MKWORKSPACE. 36

6.4      Additional OPTIONS Semantics. 37

6.4.1    Example - OPTIONS. 37

6.5      Additional DELETE Semantics. 38

6.6      Additional MOVE Semantics. 38

6.7      Additional VERSION-CONTROL Semantics. 38

6.7.1    Example - VERSION-CONTROL (using an existing version history) 39

7     Update Feature. 39

7.1      UPDATE Method. 40

7.1.1    Example - UPDATE. 40

7.2      Additional OPTIONS Semantics. 41

8     Label Feature. 41

8.1      Additional Version Properties. 41

8.1.1    DAV:label-name-set (protected) 41

8.2      LABEL Method. 41

8.2.1    Example - Setting a label 42

8.3      DAV:labeled-version Report 43

8.3.1    Example - DAV:labeled-version Report 43

8.4      Additional OPTIONS Semantics. 44

8.5      Additional UPDATE Semantics. 44

9     Working-Resource Feature. 45

9.1      Additional Version Properties. 45

9.1.1    DAV:checkout-fork. 45

9.1.2    DAV:checkin-fork. 45

9.2      Working Resource Properties. 46

9.2.1    DAV:auto-update (protected) 46

9.2.2    DAV:checkout-fork. 46

9.2.3    DAV:checkin-fork. 46

9.3      CHECKOUT Method (applied to a version) 46

9.3.1    Example - CHECKOUT of a version. 47

9.4      CHECKIN Method (applied to a working resource) 47

9.4.1    Example - CHECKIN of a working resource. 48

9.5      Additional OPTIONS Semantics. 48

9.6      Additional COPY Semantics. 49

9.7      Additional MOVE Semantics. 49

10       Advanced Versioning Features. 49

10.1       Advanced Versioning Packages. 49

10.2       Advanced Versioning Terms. 49

11       Merge Feature. 51

11.1       Additional Checked-Out Resource Properties. 51

11.1.1      DAV:merge-set 51

11.1.2      DAV:auto-merge-set 51

11.2       MERGE Method. 51

11.2.1      Example - MERGE. 53

11.3       DAV:merge-preview Report 54

11.3.1      Example - DAV:merge-preview Report 55

11.4       Additional OPTIONS Semantics. 55

11.5       Additional DELETE Semantics. 56

11.6       Additional CHECKIN Semantics. 56

12       Baseline Feature. 56

12.1       Version-Controlled Configuration Properties. 56

12.1.1      DAV:baseline-controlled-collection (protected) 57

12.2       Checked-Out Configuration Properties. 57

12.2.1      DAV:subbaseline-set 57

12.3       Baseline Properties. 57

12.3.1      DAV:baseline-collection (protected) 57

12.3.2      DAV:subbaseline-set (protected) 57

12.4       Additional Resource Properties. 57

12.4.1      DAV:version-controlled-configuration (computed) 58

12.5       Additional Workspace Properties. 58

12.5.1      DAV:baseline-controlled-collection-set (computed) 58

12.6       BASELINE-CONTROL Method. 58

12.6.1      Example - BASELINE-CONTROL. 59

12.7       DAV:compare-baseline Report 60

12.7.1      Example - DAV:compare-baseline Report 61

12.8       Additional OPTIONS Semantics. 62

12.9       Additional MKCOL Semantics. 62

12.10     Additional COPY Semantics. 62

12.11     Additional CHECKOUT Semantics. 62

12.12     Additional CHECKIN Semantics. 62

12.13     Additional UPDATE Semantics. 63

12.14     Additional MERGE Semantics. 64

13       Activity Feature. 64

13.1       Activity Properties. 65

13.1.1      DAV:activity-version-set (computed) 66

13.1.2      DAV:activity-checkout-set (computed) 66

13.1.3      DAV:subactivity-set 66

13.1.4      DAV:current-workspace-set (computed) 66

13.2       Additional Version Properties. 66

13.2.1      DAV:activity-set 66

13.3       Additional Checked-Out Resource Properties. 66

13.3.1      DAV:unreserved. 66

13.3.2      DAV:activity-set 67

13.4       Additional Workspace Properties. 67

13.4.1      DAV:current-activity-set 67

13.5       MKACTIVITY Method. 67

13.5.1      Example - MKACTIVITY.. 68

13.6       DAV:latest-activity-version Report 68

13.7       Additional OPTIONS Semantics. 68

13.8       Additional DELETE Semantics. 69

13.9       Additional MOVE Semantics. 69

13.10     Additional CHECKOUT Semantics. 69

13.10.1     Example - CHECKOUT with an activity. 70

13.11     Additional CHECKIN Semantics. 71

13.12     Additional MERGE Semantics. 71

14       Version-Controlled-Collection Feature. 71

14.1       Version-Controlled Collection Properties. 74

14.1.1      DAV:eclipsed-set (computed) 74

14.2       Collection Version Properties. 74

14.2.1      DAV:version-controlled-binding-set (protected) 74

14.3       Additional OPTIONS Semantics. 75

14.4       Additional DELETE Semantics. 75

14.5       Additional MKCOL Semantics. 75

14.6       Additional COPY Semantics. 75

14.7       Additional MOVE Semantics. 75

14.8       Additional VERSION-CONTROL Semantics. 76

14.9       Additional CHECKOUT Semantics. 76

14.10     Additional CHECKIN Semantics. 76

14.11     Additional UNCHECKOUT, UPDATE, and MERGE Semantics. 77

14.12     Additional DELETE Semantics. 77

15       Internationalization Considerations. 77

16       Security Considerations. 78

16.1       Auditing and Traceability. 78

16.2       Increased Need for Access Control 78

16.3       Security Through Obscurity. 78

16.4       Denial of Service. 78

17       IANA Considerations. 79

18       Intellectual Property. 79

19       Acknowledgements. 79

20       References. 79

21       Appendix A - Resource Classification. 81

21.1       DeltaV-Compliant Unmapped URL (a URL that identifies no resource) 81

21.2       DeltaV-Compliant Resource. 81

21.3       DeltaV-Compliant Collection. 81

21.4       Versionable Resource. 82

21.5       Version-Controlled Resource. 82

21.6       Version. 82

21.7       Checked-In Version-Controlled Resource. 82

21.8       Checked-Out Resource. 83

21.9       Checked-Out Version-Controlled Resource (checkout-in-place) 83

21.10     Working Resource (working-resource) 83

21.11     Version History (version-history) 83

21.12     Workspace (workspace) 83

21.13     Activity (activity) 84

21.14     Version-Controlled Collection (version-controlled-collection) 84

21.15     Collection Version (version-controlled-collection) 84

21.16     Version-Controlled Configuration (baseline) 84

21.17     Baseline (baseline) 84

21.18     Checked-Out Version-Controlled Configuration (baseline) 85

22       Authors' Addresses. 86

 

1         Introduction

This document specifies a set of methods, headers, and properties that define the WebDAV versioning extensions to the HTTP/1.1 protocol.  Versioning is concerned with tracking and accessing the history of important states of a web resource, such as a standalone web page.  The benefits of versioning in the context of the worldwide web include:

- A resource has an explicit history and a persistent identity across the various states it has had during the course of that history.  It allows browsing through past and alternative versions of a resource.  Frequently the modification and authorship history of a resource is critical information in itself.

- Resource states (versions) are given stable names that can support externally stored links for annotation and link server support.  Both annotation and link servers frequently need to store stable references to portions of resources that are not under their direct control.  By providing stable states of resources, version control systems allow not only stable pointers into those resources, but also well defined methods to determine the relationships of those states of a resource.

WebDAV Versioning defines both basic and advanced versioning functionality.

 

Basic versioning allows users to:

- Put a resource under version control

- Determine whether a resource is under version control

- Determine whether a resource update will automatically be captured as a new version

- Create and access distinct versions of a resource

 

Advanced versioning provides additional functionality for parallel development and configuration management of sets of web resources. 

This document will first define the properties and method semantics for the basic versioning features, and then define the additional properties and method semantics for the advanced versioning features.  An implementer that is only interested in basic versioning should skip the advanced versioning sections (Section 10 to Section 14).

1.1        Relationship to WebDAV

To maximize interoperability and the use of existing protocol functionality, versioning support is designed as extensions to the WebDAV protocol [RFC2518], which itself is an extension to the HTTP protocol [RFC2616].  All method marshalling and postconditions defined by RFC 2518 and RFC 2616 continue to hold, to ensure that versioning unaware clients can interoperate successfully with versioning servers.  Although the versioning extensions are designed to be orthogonal to most aspects of the WebDAV and HTTP protocols, a clarification to RFC 2518 is required for effective interoperable versioning.  This clarification is described in Section 1.7.

1.2        Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

The term "protected" is placed in parentheses following the definition of a protected property (see Section 1.4.2).

The term "computed" is placed in parentheses following the definition of a computed property (see Section 1.4.3).

When an XML element type in the "DAV:" namespace is referenced in this document outside of the context of an XML fragment, the string "DAV:" will be prefixed to the element type.

When a method is defined in this document, a list of preconditions and postconditions will be defined for that method.  If the semantics of an existing method is being extended, a list of additional preconditions and postconditions will be defined.  A precondition or postcondition is prefixed by a parenthesized XML element type that identifies that precondition or postcondition (see Section 1.6).

1.3        Terms

This document uses the terms defined in RFC 2616, in RFC 2518, and in this section.  Section 2.2 defines the semantic versioning model underlying this terminology.

Version Control, Checked-In, Checked-Out

"Version control" is a set of constraints on how a resource can be updated.  A resource under version control is either in a "checked-in" or "checked-out" state, and the version control constraints apply only while the resource is in the checked-in state.

Versionable Resource

A "versionable resource" is a resource that can be put under version control.

Version-Controlled Resource

When a versionable resource is put under version control, it becomes a "version-controlled resource".  A version-controlled resource can be "checked out" to allow modification of its content or dead properties by standard HTTP and WebDAV methods.

Checked-Out Resource

A "checked-out resource" is a resource under version control that is in the checked-out state.

Stable URL

A "stable URL" is a URL that is mapped to a resource when that resource is created, and that never is mapped to a different resource.

Version Resource

A "version resource", or simply "version", is a resource that is identified by a stable URL, and that contains a copy of a particular state (content and dead properties) of a version-controlled resource.  A version is created by "checking in" a checked-out resource.  The content and dead properties of a version never change.

Version History Resource

A "version history resource", or simply "version history", is a resource that is identified by a stable URL, and that contains all the versions of a particular version-controlled resource.

Version Name

A "version name" is a string chosen by the server to distinguish one version of a version history from the other versions of that version history.  Versions from different version histories may have the same version name.

Predecessor, Successor, Ancestor, Descendant

When a version-controlled resource is checked out and then subsequently checked in, the version that was checked out becomes a "predecessor" of the version created by the checkin.  A client can specify multiple predecessors for a new version if the new version is logically a merge of those predecessors.  When a version is connected to another version by traversing one or more predecessor relations, it is called an "ancestor" of that version.  The inverse of the predecessor and ancestor relations are the "successor" and "descendant" relations.  Therefore, if X is a predecessor of Y, then Y is a successor of X, and if X is an ancestor of Y, then Y is a descendant of X.

Root Version Resource

The "root version resource", or simply "root version", is the version in a version history that is an ancestor of every other version in that version history.

Workspace Resource

A "workspace resource", or simply "workspace", is a collection that contains at most one version-controlled resource for a given version history (see Section 6).

Working Resource

A "working resource" is a checked-out resource created by the server at a server-defined URL when a version (instead of a version-controlled resource) is checked out.  Unlike a checked-out version-controlled resource, a working resource is deleted when it is checked in. 

Fork, Merge

When a second successor is added to a version, this creates a "fork" in the version history.  When a version is created with multiple predecessors, this creates a "merge" in the version history.  A server may restrict the version history to be linear (with no forks or merges), but an interoperable versioning client should be prepared to deal with both forks and merges in the version history.

The following diagram illustrates several of the previous definitions.  Each box represents a version and each line between two boxes represents a predecessor/successor relationship.  For example, it shows V3 is a predecessor of V5, V7 is a successor of V5, V1 is an ancestor of V4, and V7 is a descendant of V4.  It also shows that there is a fork at version V2 and a merge at version V7.

                     History of foo.html

    

                             +---+

       Root Version -------> |   | V1

                             +---+           ^

                               |             |

                               |             |

                             +---+           |

       Version Name ----> V2 |   |           | Ancestor

                             +---+           |

                             /    \          |

                            /      \         |

                       +---+       +---+

                       |   | V3    |   | V4

                    ^  +---+       +---+

                    |    |           |       |

       Predecessor  |    |           |       |

                       +---+       +---+     |

                       |   | V5    |   | V6  | Descendant

                       +---+       +---+     |

       Successor    |       \      /         |

                    |        \    /          |

                    v        +---+           v

                             |   | V7

                             +---+

 

Label

A "label" is a name that can be used to select a version from a version history.  A label can be assigned by either a client or the server.  The same label can be used in different version histories.

1.4        Property Values

1.4.1           Initial Property Value

Unless an initial value of a property of a given type is defined by this document, the initial value of a property of that type is implementation dependent.

1.4.2           Protected Property Value

When a property of a specific kind of resource is "protected", the property value cannot be updated on that kind of resource except by a method explicitly defined as updating that specific property.  In particular, a protected property cannot be updated with a PROPPATCH request.  Note that a given property can be protected on one kind of resource, but not protected on another kind of resource.

1.4.3           Computed Property Value

When a property is "computed", its value is defined in terms of a computation based on the content and other properties of that resource, or even of some other resource.  When the semantics of a method is defined in this document, the effect of that method on non-computed properties will be specified; the effect of that method on computed properties will not be specified, but can be inferred from the computation defined for those properties.  A computed property is always a protected property.

1.4.4           Boolean Property Value

Some properties take a Boolean value of either "false" or "true".

1.4.5           DAV:href Property Value

The DAV:href XML element is defined in RFC 2518, Section 12.3. Whenever a DAV:href element in a property defined by this document contains a URL that identifies a version resource or a version history resource, that URL MUST be the stable URL for that resource.

1.5        DAV Namespace XML Elements in Request and Response Bodies

Although WebDAV request and response bodies can be extended by arbitrary XML elements, which can be ignored by the message recipient, an XML element in the DAV namespace MUST NOT be used in the request or response body of a versioning method unless that XML element is explicitly defined in an IETF RFC.

1.6        Method Preconditions and Postconditions

A "precondition" of a method describes the state on the server that must be true for that method to be performed.  A "postcondition" of a method describes the state on the server that must be true after that method has completed.  If a method precondition or postcondition for a request is not satisfied, the response status of the request MUST be either 403 (Forbidden) if the request should not be repeated because it will always fail, or 409 (Conflict) if it is expected that the user might be able to resolve the conflict and resubmit the request.

In order to allow better client handling of 403 and 409 responses, a distinct XML element type is associated with each method precondition and postcondition of a request.  When a particular precondition is not satisfied or a particular postcondition cannot be achieved, the appropriate XML element MUST be returned as the child of a top-level DAV:error element in the response body, unless otherwise negotiated by the request.  In a 207 Multi-Status response, the DAV:error element would appear in the appropriate DAV:responsedescription element.

1.6.1           Example - CHECKOUT request with DAV:must-be-checked-in response

>>REQUEST

 

  CHECKOUT /foo.html HTTP/1.1

  Host: www.webdav.org

  
>>RESPONSE

 

  HTTP/1.1 409 Conflict

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:error xmlns:D="DAV:">

    <D:must-be-checked-in/>

  </D:error>

 

In this example, the request to CHECKOUT /foo.html fails because /foo.html is not checked in.

1.7        Clarification of COPY Semantics with Overwrite:T

RFC 2518, Section 8.8.4 states:

"If a resource exists at the destination and the Overwrite header is "T" then prior to performing the copy the server MUST perform a DELETE with "Depth: infinity" on the destination resource."

The purpose of this sentence is to ensure that following a COPY, all destination resources have the same content and dead properties as the corresponding resources identified by the request-URL (where a resource with a given name relative to the Destination URL "corresponds" to a resource with the same name relative to the request-URL).  If at the time of the request, there already is a resource at the destination that has the same resource type as the corresponding resource at the request-URL, that resource MUST NOT be deleted, but MUST be updated to have the content and dead properties of its corresponding member.  If a client wishes all resources at the destination to be deleted prior to the COPY, it MUST explicitly issue a DELETE request.

The difference between updating a resource and replacing a resource with a new resource is especially important when resource history is being maintained (the former adds to an existing history, while the latter creates a new history).  In addition, locking and access control constraints might allow you to update a resource, but not allow you to delete it and create a new one in its place.

Note that this clarification does not apply to a MOVE request.  A MOVE request with Overwrite:T MUST perform the DELETE with "Depth:infinity" on the destination resource prior to performing the MOVE.

1.8        Versioning Methods and Write Locks

If a write-locked resource has a non-computed property defined by this document, the property value MUST NOT be changed by a request unless the appropriate lock token is included in the request.  Since every method introduced in this document other than REPORT modifies at least one property defined by this document, every versioning method other than REPORT is affected by a write lock. In particular, the method MUST fail with a 423 (Locked) status if the resource is write-locked and the appropriate token is not specified in an If request header.

2         Basic Versioning Features

Each basic versioning feature defines extensions to existing HTTP and WebDAV methods, as well as new resource types, live properties, and methods.

2.1        Basic Versioning Packages

Although a server MAY support any combination of versioning features, in order to minimize the complexity of a WebDAV basic versioning client, a WebDAV basic versioning server SHOULD support one of the following three "packages" (feature sets):

- Core-Versioning Package: version-control

- Basic-Server-Workspace Package: version-control, workspace, version-history, checkout-in-place

- Basic-Client-Workspace Package: version-control, working-resource, update, label

The core-versioning package supports linear versioning by both versioning-aware and versioning-unaware clients.  A versioning-aware client can use reports and properties to access previous versions of a version-controlled resource.

The basic workspace packages support parallel development of version-controlled resources.  Each client has its own configuration of the shared version-controlled resources, and can make changes to its configuration without disturbing that of another client.

In the basic-server-workspace package, all persistent state is maintained on the server.  Each client has its own workspace resource allocated on the server, where each workspace identifies a configuration of the shared version-controlled resources.  Each client makes changes to its workspace, and can transfer changes when appropriate from one workspace to another.  The server workspace package is appropriate for clients with no local persistent state, or for clients that wish to expose their working configurations to other clients.

In the basic-client-workspace package, each client maintains in local persistent storage the state for its configuration of the shared version-controlled resources.  When a client is ready to make its changes visible to other clients, it allocates a set of "working resources" on the server, updates the content and dead properties of these working resources, and then uses the set of working resources to update the version-controlled resources.  The working resources are used instead of directly updating the version-controlled resources so that sets of consistent updates can be prepared in parallel by multiple clients.  Also, a working resource allows a client to prepare a single update that requires multiple server requests (e.g. updating both the content and dead properties of a resource requires both a PUT and a PROPPATCH).  The client workspace package simplifies the server implementation by requiring each client to maintain its own namespace, but this requires that the clients have local persistent state, and does not allow clients to expose their working configurations to other clients.

A server that supports both basic workspace packages will interoperate with all basic versioning clients.

2.2        Basic Versioning Semantics

2.2.1           Creating a Version-Controlled Resource

In order to track the history of the content and dead properties of a versionable resource, a user can put the resource under version control with a VERSION-CONTROL request.  A VERSION-CONTROL request performs three distinct operations:

1) It creates a new "version history resource".  In basic versioning, a version history resource is not assigned a URL, and hence is not visible in the http scheme URL space.  However, when the version-history feature (see Section 5) is supported, this changes, and each version history resource is assigned a stable server-defined URL.

2) It creates a new "version resource" and adds it to the new version history resource.  The body and dead properties of the new version resource are a copy of those of the versionable resource.  The server assigns the new version resource a stable URL.

3) It converts the versionable resource into a "version-controlled resource".  The version-controlled resource continues to be identified by the same URL that identified it as a versionable resource.  As part of this conversion, it adds a DAV:checked-in property, whose value contains the URL of the new version resource.

Note that a versionable resource and a version-controlled resource are not new types of resources (i.e. they introduce no new DAV:resourcetype), but rather are any type of resource that supports the methods and live properties defined for them in this document, in addition to all the methods and live properties implied by their DAV:resourcetype.  For example, a collection (whose DAV:resourcetype includes DAV:collection) is a versionable resource if it supports the VERSION-CONTROL method, and is a version-controlled resource if it supports the version-controlled resource methods and live properties.

In the following example, foo.html is a versionable resource that is put under version control.  After the VERSION-CONTROL request succeeds, there are two additional resources: a new version history resource and a new version resource in that version history.  The versionable resource is converted into a version-controlled resource, whose DAV:checked-in property identifies the new version resource.  The content and dead properties of a resource are represented by the symbol appearing inside the box for that resource (e.g. "S1" in the following example). 

          ===VERSION-CONTROL==>

    

                    |                       +----+ version

                    |   version-            |    | history

       versionable  |   controlled          +----+ resource

       resource     |   resource              |

       /foo.html    |   /foo.html             |       

                    |                         v

         +----+     |     +----+ checked-in +----+ version

         | S1 |     |     | S1 |----------->| S1 | resource

         +----+     |     +----+            +----+ /his/73/ver/1

 

Thus, whereas before the VERSION-CONTROL request there was only one, non-version-controlled resource, after VERSION-CONTROL there are three separate, distinct resources, each containing its own state and properties: the version-controlled resource, the version resource, and the version history resource.  Since the version-controlled resource and the version resource are separate, distinct resources, when a method is applied to a version-controlled resource, it is only applied to that version-controlled resource, and is not applied to the version resource that is currently identified by the DAV:checked-in property of that version-controlled resource.  Although the content and dead properties of a checked-in version-controlled resource are required to be the same as those of its current DAV:checked-in version, its live properties may differ.  An implementation may optimize storage by retrieving the content and dead properties of a checked-in version-controlled resource from its current DAV:checked-in version rather than storing them in the version-controlled resource, but this is just an implementation optimization.

Normally, a resource is placed under version control with an explicit VERSION-CONTROL request.  A server MAY automatically place every new versionable resource under version control.  In this case, the resulting state on the server MUST be the same as if the client had explicitly applied a VERSION-CONTROL request to the versionable resource.

2.2.2           Modifying a Version-Controlled Resource

In order to use methods like PUT and PROPPATCH to directly modify the content or dead properties of a version-controlled resource, the version-controlled resource must first be checked out.  When the checked-out resource is checked in, a new version is created in the version history of that version-controlled resource.  The version that was checked out is remembered as the predecessor of the new version. 

The DAV:auto-version property (see Sections 3.2.2) of a checked-in version-controlled resource determines how it responds to a method that attempts to modify its content or dead properties.  Possible responses include:

- Fail the request.  The resource requires an explicit CHECKOUT request for it to be modified (see Sections 4 and 9.2.1).

- Automatically checkout the resource, perform the modification, and automatically checkin the resource.  This ensures that every state of the resource is tracked by the server, but can result in an excessive number of versions being created.

- Automatically checkout the resource, perform the modification, and then if the resource is not write-locked, automatically checkin the resource.  If the resource is write-locked, it remains checked-out until the write lock is removed (either explicitly through a subsequent UNLOCK request or implicitly through a time-out of the write-lock).  This helps a locking client avoid the proliferation of versions, while still allowing a non-locking client to update the resource.

- Automatically checkout the resource, perform the modification, and then leave the resource checked out.  If the resource is write-locked, it will be automatically checked in when the write-lock is removed, but an explicit CHECKIN operation (see Section 4.4) is required for a non-write-locked resource.  This minimizes the number of new versions that will be created by a versioning unaware client, but only a versioning aware client can create new versions of a non-write-locked resource.

- Fail the request unless the resource is write-locked.  If it is write-locked, automatically checkout the resource and perform the modification.  The resource is automatically checked in when the write-lock is removed.  This minimizes the number of new versions that will be created by a versioning unaware client, but never automatically checks out a resource that will not subsequently be automatically checked in.

The following diagram illustrates the effect of the checkout/checkin process on a version-controlled resource and its version history.  The symbol inside a box (S1, S2, S3) represents the current content and dead properties of the resource represented by that box.  The symbol next to a box (V1, V2, V3) represents the URL for that resource.

 

            ===checkout==>     ===PUT==>     ===checkin==>

 

 

         /foo.html (version-controlled resource)

 

          +----+    |    +----+    |    +----+    |    +----+

          | S2 |    |    | S2 |    |    | S3 |    |    | S3 |

          +----+    |    +----+    |    +----+    |    +----+

       Checked-In=V2|Checked-Out=V2|Checked-Out=V2|Checked-In=V3

 

 

         /his/73 (version history for /foo.html)

 

         +----+     |   +----+     |   +----+     |   +----+

         | S1 | V1  |   | S1 | V1  |   | S1 | V1  |   | S1 | V1

         +----+     |   +----+     |   +----+     |   +----+

            |       |      |       |      |       |      |

            |       |      |       |      |       |      |

         +----+     |   +----+     |   +----+     |   +----+

         | S2 | V2  |   | S2 | V2  |   | S2 | V2  |   | S2 | V2

         +----+     |   +----+     |   +----+     |   +----+

                    |              |              |      |       

                    |              |              |      |      

                    |              |              |   +----+    

                    |              |              |   | S3 | V3   

                    |              |              |   +----+    

 

Note that a version captures only a defined subset of the state of a resource.  In particular, a version of a basic resource captures its content and dead properties, but not its live properties.

2.2.3           Reporting

Some versioning information about a resource requires that parameters be specified along with that request for information.  Included in basic versioning is the required support for an extensible reporting mechanism, which includes a REPORT method as well as a live property for determining what reports are supported by a particular resource.  The REPORT method is required by versioning, but it can be used in non-versioning WebDAV extensions.

To allow a client to query the properties of all versions in the version history of a specified version-controlled resource, basic versioning provides the DAV:version-tree report (see Section 3.7).  A more powerful version history reporting mechanism is provided by applying the DAV:expand-property report (see Section 3.8) to a version history resource (see Section 5).

3         Version-Control Feature

The version-control feature provides support for putting a resource under version control creating an associated version-controlled resource and version history resource as described in Section 2.2.1. A server indicates that it supports the version-control feature by including the string "version-control" as a field in the DAV header in the response to an OPTIONS request.  The version-control feature MUST be supported if any other versioning feature is supported.

3.1        Additional Resource Properties

The version-control feature introduces the following REQUIRED properties for any WebDAV resource.

3.1.1           DAV:comment

This property is used to track a brief comment about a resource that is suitable for presentation to a user.  The DAV:comment of a version can be used to indicate why that version was created.

<!ELEMENT comment (#PCDATA)>

PCDATA value: string

3.1.2           DAV:creator-displayname

This property contains a description of the creator of the resource that is suitable for presentation to a user.  The DAV:creator-displayname of a version can be used to indicate who created that version.

<!ELEMENT creator-displayname (#PCDATA)>

PCDATA value: string

3.1.3           DAV:supported-method-set (protected)

This property identifies the methods that are supported by the resource.  A method is supported by a resource if there is some state of that resource for which an application of that method will successfully satisfy all postconditions of that method, including any additional postconditions added by the features supported by that resource.

<!ELEMENT supported-method-set (supported-method*)>

<!ELEMENT supported-method ANY>

<!ATTLIST supported-method name NMTOKEN #REQUIRED>

name value: a method name

3.1.4           DAV:supported-live-property-set (protected)

This property identifies the live properties that are supported by the resource.  A live property is supported by a resource if that property has the semantics defined for that property.  The value of this property MUST identify all live properties defined by this document that are supported by the resource, and SHOULD identify all live properties that are supported by the resource.

<!ELEMENT supported-live-property-set (supported-live-property*)>

<!ELEMENT supported-live-property prop>

<!ELEMENT prop ANY>

ANY value: a property element type

3.1.5           DAV:supported-report-set (protected)

This property identifies the reports that are supported by the resource.

<!ELEMENT supported-report-set (supported-report*)>

<!ELEMENT supported-report report>

<!ELEMENT report ANY>

ANY value: a report element type

3.2        Version-Controlled Resource Properties

The version-control feature introduces the following REQUIRED properties for a version-controlled resource.

3.2.1           DAV:checked-in (protected)

This property appears on a checked-in version-controlled resource, and identifies a version that has the same content and dead properties as the version-controlled resource.  This property is removed when the resource is checked out, and then added back (identifying a new version) when the resource is checked back in.

<!ELEMENT checked-in (href)>

 

3.2.2           DAV:auto-version

If the DAV:auto-version value is DAV:checkout-checkin, when a modification request (such as PUT/PROPPATCH) is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout and followed by a checkin operation.

If the DAV:auto-version value is DAV:checkout-unlocked-checkin, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation.  If the resource is not write-locked, the request is automatically followed by a checkin operation.

If the DAV:auto-version value is DAV:checkout, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation.

If the DAV:auto-version value is DAV:locked-checkout, when a modification request is applied to a write-locked checked-in version-controlled resource, the request is automatically preceded by a checkout operation.

If an update to a write-locked checked-in resource is automatically preceded by a checkout of that resource, the checkout is associated with the write-lock.  When this write lock is removed (e.g. from an UNLOCK or a lock timeout), if the resource has not yet been checked in, the removal of the write lock is automatically preceded by a checkin operation.

A server MAY refuse to allow the value of the DAV:auto-version property to be modified, or MAY only support values from a subset of the valid values.

<!ELEMENT auto-version

 (checkout-checkin | checkout-unlocked-checkin | checkout | locked-checkout)? >

<!ELEMENT checkout-checkin EMPTY>

<!ELEMENT checkout-unlocked-checkin EMPTY>

<!ELEMENT checkout EMPTY>

<!ELEMENT locked-checkout EMPTY>

3.3        Checked-Out Resource Properties

The version-control feature introduces the following REQUIRED properties for a checked-out resource.

3.3.1           DAV:checked-out (protected)

This property identifies the version that was identified by the DAV:checked-in property at the time the resource was checked out. This property is removed when the resource is checked in.

<!ELEMENT checked-out (href)>

 

3.3.2           DAV:predecessor-set

This property determines the DAV:predecessor-set property of the version that results from checking in this resource.

A server MAY reject attempts to modify the DAV:predecessor-set of a version-controlled resource.

<!ELEMENT predecessor-set (href+)>

3.4        Version Properties

The version-control feature introduces the following REQUIRED properties for a version.

3.4.1           DAV:predecessor-set (protected)

This property identifies each predecessor of this version.  Except for the root version, which has no predecessors, each version has at least one predecessor.

<!ELEMENT predecessor-set (href*)>

3.4.2           DAV:successor-set (computed)

This property identifies each version whose DAV:predecessor-set identifies this version.

<!ELEMENT successor-set (href*)>

3.4.3           DAV:checkout-set (computed)

This property identifies each checked-out resource whose DAV:checked-out property identifies this version.

<!ELEMENT checkout-set (href*)>

3.4.4           DAV:version-name (protected)

This property contains a server-defined string that is different for each version in a given version history.  This string is intended for display to a user, unlike the URL of a version, which is normally only used by a client and not displayed to a user.

<!ELEMENT version-name (#PCDATA)>

PCDATA value: string

3.5        VERSION-CONTROL Method

A VERSION-CONTROL request can be used to create a version-controlled resource at the request-URL.  It can be applied to a versionable resource or to a version-controlled resource.

If the request-URL identifies a versionable resource, a new version history resource is created, a new version is created whose content and dead properties are copied from the versionable resource, and the resource is given a DAV:checked-in property that is initialized to identify this new version.

If the request-URL identifies a version-controlled resource, the resource just remains under version-control.  This allows a client to be unaware of whether or not a server automatically puts a resource under version control when it is created.

If a VERSION-CONTROL request fails, the server state preceding the request MUST be restored.

Marshalling:

If a request body is included, it MUST be a DAV:version-control XML element.

<!ELEMENT version-control ANY>

 

If the request-URL identifies a versionable resource, the response to a successful request MUST include a Location header containing the URL for the new version created by the request.

If a response body for a successful request is included, it MUST be a DAV:version-control-response XML element.  Note that this document does not define any elements for the VERSION-CONTROL response body, but the DAV:version-control-response element is defined to ensure interoperability between future extensions that do define elements for the VERSION-CONTROL response body.

<!ELEMENT version-control-response ANY>

 

Postconditions:

(DAV:put-under-version-control): If the request-URL identified a versionable resource at the time of the request, the request MUST have created a new version history and MUST have created a new version resource in that version history.  The resource MUST have a DAV:checked-in property that identifies the new version.  The content, dead properties, and DAV:resourcetype of the new version MUST be the same as those of the resource.  Note that an implementation can choose to locate the version history and version resources anywhere that it wishes.  In particular, it could locate them on the same host and server as the version-controlled resource, on a different virtual host maintained by the same server, on the same host maintained by a different server, or on a different host maintained by a different server.

(DAV:must-not-change-existing-checked-in-out): If the request-URL identified a resource already under version control at the time of the request, the request MUST NOT change the DAV:checked-in or DAV:checked-out property of that version-controlled resource.

3.5.1           Example - VERSION-CONTROL

>>REQUEST

 

  VERSION-CONTROL /foo.html HTTP/1.1

  Host: www.webdav.org

  Content-Length: 0

  
>>RESPONSE

 

  HTTP/1.1 200 OK

 

In this example, /foo.html is put under version control.  A new version history is created for it, and a new version is created that has a copy of the content and dead properties of /foo.html.  The DAV:checked-in property of /foo.html identifies this new version.

3.6        REPORT Method

A REPORT request is an extensible mechanism for obtaining information about a resource.  Unlike a resource property, which has a single value, the value of a report can depend on additional information specified in the REPORT request body and in the REPORT request headers.

Marshalling:

The body of a REPORT request specifies which report is being requested, as well as any additional information that will be used to customize the report.

The request MAY include a Depth header.  If no Depth header is included, Depth:0 is assumed.

The response body for a successful request MUST contain the requested report.

If a Depth request header is included, the response MUST be a 207 Multi-Status.  The request MUST be applied separately to the collection itself and to all members of the collection that satisfy the Depth value.  The DAV:prop element of a DAV:response for a given resource MUST contain the requested report for that resource.  Note that using a DAV:prop element to contain reports is an extension of the definition of DAV:prop in RFC 2518, Section 12.11.

Preconditions:

(DAV:supported-report): The specified report MUST be supported by the resource identified by the request-URL.

(DAV:acceptable-depth): A server MAY reject a non-zero Depth request that would match more resources than the server is willing to handle in a single request.

Postconditions:

(DAV:no-modification): The REPORT method MUST NOT have changed the content or dead properties of any resource.

3.7        DAV:version-tree Report

The DAV:version-tree report describes the requested properties of all the versions in the version history of a version.  If the report is requested for a version-controlled resource, it is redirected to its DAV:checked-in or DAV:checked-out version.

The DAV:version-tree report MUST be supported by all version resources and all version-controlled resources.

Marshalling:

The request body MUST be a DAV:version-tree XML element.

<!ELEMENT version-tree ANY>

ANY value: a sequence of zero or more elements, with at most one DAV:prop element.

prop: see RFC 2518, Section 12.11

 

The response body for a successful request MUST be a DAV:multistatus XML element.

multistatus: see RFC 2518, Section 12.9

 

The response body for a successful DAV:version-tree REPORT request MUST include a DAV:response element for each version in the version history of the version identified by the request-URL.

3.7.1           Example - DAV:version-tree Report

The version history drawn below would produce the following version tree report.

    

           foo.html History

 

                +---+

                |   | V1

                +---+

               /     \

              /       \

          +---+       +---+

          |   | V2    |   | V2.1.1 

          +---+       +---+

 

 

>>REQUEST

 

  REPORT /foo.html HTTP/1.1

  Host: www.webdav.org

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:version-tree xmlns:D="DAV:">

    <D:prop>

      <D:version-name/>

      <D:creator-displayname/>

      <D:successor-set/>

    </D:prop>

  </D:version-tree>

 

>>RESPONSE

 

  HTTP/1.1 207 Multi-Status

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:multistatus xmlns:D="DAV:">

    <D:response>

      <D:href>http://repo.webdav.org/his/23/ver/V1</D:href>

      <D:propstat>

        <D:prop>

          <D:version-name>V1</D:version-name>

          <D:creator-displayname>Fred</D:creator-displayname>

          <D:successor-set>

            <D:href>http://repo.webdav.org/his/23/ver/V2</D:href>

            <D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>

          </D:successor-set>

        </D:prop>

        <D:status>HTTP/1.1 200 OK</D:status>

      </D:propstat>

    </D:response>

    <D:response>

      <D:href>http://repo.webdav.org/his/23/ver/V2</D:href>

      <D:propstat>

        <D:prop>

          <D:version-name>V2</D:version-name>

          <D:creator-displayname>Fred</D:creator-displayname>

          <D:successor-set/>

        </D:prop>

        <D:status>HTTP/1.1 200 OK</D:status>

      </D:propstat>

    </D:response>

    <D:response>

      <D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>

      <D:propstat>

        <D:prop>

          <D:version-name>V2.1.1</D:version-name>

          <D:creator-displayname>Sally</D:creator-displayname>

          <D:successor-set/>

        </D:prop>

        <D:status>HTTP/1.1 200 OK</D:status>

      </D:propstat>

    </D:response>

  </D:multistatus>

 

3.8        DAV:expand-property Report

Many property values are defined as a DAV:href, or a set of DAV:href elements.  The DAV:expand-property report provides a mechanism for retrieving in one request the properties from the resources identified by those DAV:href elements.  This report not only decreases the number of requests required, but also allows the server to minimize the number of separate read transactions required on the underlying versioning store.

The DAV:expand-property report SHOULD be supported by all resources that support the REPORT method.

Marshalling:

The request body MUST be a DAV:expand-property XML element.

<!ELEMENT expand-property (property*)>

<!ELEMENT property (property*)>

<!ATTLIST property name NMTOKEN #REQUIRED>

name value: a property element type

<!ATTLIST property namespace NMTOKEN "DAV:">

namespace value: an XML namespace

 

The response body for a successful request MUST be a DAV:multistatus XML element.

multistatus: see RFC 2518, Section 12.9

 

The properties reported in the DAV:prop elements of the DAV:multistatus element MUST be those identified by the DAV:property elements in the DAV:expand-property element.  If there are DAV:property elements nested within a DAV:property element, then every DAV:href in the value of the corresponding property is replaced by a DAV:response element whose DAV:prop elements report the values of the properties identified by the nested DAV:property elements.  The nested DAV:property elements can in turn include DAV:property elements, so that multiple levels of DAV:href expansion can be requested.

Note that a validating parser MUST be aware that the DAV:expand-property report effectively modifies the DTD of every property by replacing every occurrence of "href" in the DTD with "href | response".

3.8.1           Example - DAV:expand-property

This example describes how to query a version-controlled resource to determine the DAV:creator-display-name and DAV:activity-set of every version in the version history of that version-controlled resource.  This example assumes that the server supports the version-history feature (see Section 5).

>>REQUEST

 

  REPORT /foo.html HTTP/1.1

  Host: www.webdav.org

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:expand-property xmlns:D="DAV:">

    <D:property name="version-history">

      <D:property name="version-set">

        <D:property name="creator-displayname"/>

        <D:property name="activity-set"/>

      </D:property>

    </D:property>

  </D:expand-property>

 

>>RESPONSE

 

  HTTP/1.1 207 Multi-Status

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:multistatus xmlns:D="DAV:">

    <D:response>

      <D:href>http://www.webdav.org/foo.html</D:href>

      <D:propstat>

        <D:prop>

          <D:version-history>

            <D:response>

              <D:href>http://repo.webdav.org/his/23</D:href>

              <D:propstat>

                <D:prop>

                  <D:version-set>

                    <D:response>

                      <D:href>http://repo.webdav.org/his/23/ver/1</D:href>

                      <D:propstat>

                        <D:prop>

                          <D:creator-displayname>Fred</D:creator-displayname>

                          <D:activity-set> <D:href>

                            http://www.webdav.org/ws/dev/sally

                          </D:href> </D:activity-set> </D:prop>

                        <D:status>HTTP/1.1 200 OK</D:status>

                      </D:propstat> </D:response>

                    <D:response>

                      <D:href>http://repo.webdav.org/his/23/ver/2</D:href>

                      <D:propstat>

                        <D:prop>

                          <D:creator-displayname>Sally</D:creator-displayname>

                          <D:activity-set> <D:href>

                            http://repo.webdav.org/act/add-refresh-cmd

                          </D:href> </D:activity-set> </D:prop>

                        <D:status>HTTP/1.1 200 OK</D:status>

                      </D:propstat> </D:response>

                  </D:version-set> </D:prop>

                <D:status>HTTP/1.1 200 OK</D:status>

              </D:propstat> </D:response>

          </D:version-history> </D:prop>

        <D:status>HTTP/1.1 200 OK</D:status>

      </D:propstat> </D:response>

  </D:multistatus>

 

In this example, the DAV:creator-displayname and DAV:activity-set properties of the versions in the DAV:version-set of the DAV:version-history of http://www.webdav.org/foo.html are reported.

3.9        Additional OPTIONS Semantics

If the server supports the version-control feature, it MUST include "version-control" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods. 

3.10    Additional PUT Semantics

Additional Preconditions:

(DAV:cannot-modify-version-controlled-content): If the request-URL identifies a resource with a DAV:checked-in property, the request MUST fail unless DAV:auto-version semantics will automatically check out the resource.

(DAV:cannot-modify-version): If the request-URL identifies a version, the request MUST fail.

If the request creates a new resource that is automatically placed under version control, all preconditions for VERSION-CONTROL apply to the request.

Additional Postconditions:

(DAV:auto-checkout): If the resource was a checked-in version-controlled resource whose DAV:auto-version property indicates it should be automatically checked out but not automatically checked in for a modification request, then the server MUST have automatically checked out the resource prior to executing the request.  In particular, the value of the DAV:checked-out property of the resource MUST be that of the DAV:checked-in property prior to the request, the DAV:checked-in property MUST have been removed, and the DAV:predecessor-set property MUST be initialized to be the same as the DAV:checked-out property.  If any part of the checkout/update sequence failed, the status from the failed part of the request MUST be returned, and the server state preceding the request sequence MUST be restored.

(DAV:auto-checkout-checkin): If the resource was a checked-in version-controlled resource whose DAV:auto-version property indicates it should be automatically checked out and automatically checked in for a modification request, then the server MUST have automatically checked out the resource prior to executing the request and automatically checked it in after the request.  In particular, the DAV:checked-in property of the resource MUST identify a new version whose content and dead properties are the same as those of the resource.  The DAV:predecessor-set of the new version MUST identify the version identified by the DAV:checked-in property prior to the request.  If any part of the checkout/update/checkin sequence failed, the status from the failed part of the request MUST be returned, and the server state preceding the request sequence MUST be restored.

If the request creates a new resource, the new resource MAY have automatically been placed under version control, and all postconditions for VERSION-CONTROL apply to the request.

3.11    Additional PROPFIND Semantics

A DAV:allprop PROPFIND request SHOULD NOT return any of the properties defined by this document.  This allows a versioning server to perform efficiently when a naive client, which does not understand the cost of asking a server to compute all possible live properties, issues a DAV:allprop PROPFIND request.

Additional Preconditions:

(DAV:supported-live-property): If the request attempts to access a property defined by this document, the semantics of that property MUST be supported by the server.

3.12    Additional PROPPATCH Semantics

Additional Preconditions:

(DAV:cannot-modify-version-controlled-property): If the request attempts to modify a dead property, same semantics as PUT (see Section 3.10).

(DAV:cannot-modify-version): If the request attempts to modify a dead property, same semantics as PUT (see Section 3.10).

(DAV:cannot-modify-protected-property): An attempt to modify a property defined by this document as being protected for that kind of resource MUST fail.

(DAV:supported-live-property): An attempt to modify a property defined by this document whose semantics are not enforced by the server MUST fail.  This helps ensure that a client will be notified when it is trying to use a property whose semantics are not supported by the server.

Additional Postconditions:

(DAV:auto-checkout): If the request modified a dead property, same semantics as PUT (see Section 3.10).

(DAV:auto-checkout-checkin): If the request modified a dead property, same semantics as PUT (see Section 3.10).

3.13    Additional DELETE Semantics

Additional Preconditions:

(DAV:no-version-delete): A server MAY fail an attempt to DELETE a version.

Additional Postconditions:

(DAV:update-predecessor-set): If a version was deleted, the server MUST have replaced any reference to that version in a DAV:predecessor-set by a copy of the DAV:predecessor-set of the deleted version.

3.14    Additional COPY Semantics

Additional Preconditions:

If the request creates a new resource that is automatically placed under version control, all preconditions for VERSION-CONTROL apply to the request.

Additional Postconditions:

(DAV:must-not-copy-versioning-property): A property defined by this document MUST NOT have been copied to the new resource created by this request, but instead that property of the new resource MUST have the default initial value it would have had if the new resource had been created by a non-versioning method such as PUT or a MKCOL.

(DAV:auto-checkout): If the destination is a version-controlled resource, same semantics as PUT (see Section 3.10).

(DAV:auto-checkout-checkin): If the destination is a version-controlled resource, same semantics as PUT (see Section 3.10).

(DAV:copy-creates-new-resource): If the source of a COPY is a version-controlled resource or version, and if there is no resource at the destination of the COPY, then the COPY creates a new non-version-controlled resource at the destination of the COPY.  The new resource MAY automatically be put under version control, but the resulting version-controlled resource MUST be associated with a new version history created for that new version-controlled resource, and all postconditions for VERSION-CONTROL apply to the request.

3.15    Additional MOVE Semantics

Additional Preconditions:

(DAV:cannot-rename-version): If the request-URL identifies a version, the request MUST fail.

Additional Postconditions:

(DAV:preserve-versioning-properties): When a resource is moved from a source URL to a destination URL, a property defined by this document MUST have the same value at the destination URL as it had at the source URL.

3.16    Additional UNLOCK Semantics

Note that these semantics apply both to an explicit UNLOCK request, as well as to the removal of a lock because of a lock timeout.  If a precondition or postcondition cannot be satisfied, the lock timeout MUST NOT occur.

Additional Preconditions:

(DAV:version-history-is-tree): If the request-URL identifies a checked-out version-controlled resource that will be automatically checked in when the lock is removed, then the versions identified by the DAV:predecessor-set of the checked-out resource MUST be descendants of the root version of the version history for the DAV:checked-out version.

Additional Postconditions:

(DAV:auto-checkin): If the request-URL identified a checked-out version-controlled resource that had been automatically checked out because of its DAV:auto-version property, the request MUST have created a new version in the version history of the DAV:checked-out version.  The request MUST have allocated a URL for the version that MUST NOT have previously identified any other resource, and MUST NOT ever identify a resource other than this version.  The content, dead properties, DAV:resourcetype, and DAV:predecessor-set of the new version MUST be copied from the checked-out resource.  The DAV:version-name of the new version MUST be set to a server-defined value distinct from all other DAV:version-name values of other versions in the same version history.  The request MUST have removed the DAV:checked-out property of the version-controlled resource, and MUST have added a DAV:checked-in property that identifies the new version.

4         Checkout-In-Place Feature

With the version-control feature, WebDAV locking can be used to avoid the proliferation of versions that would result if every modification to a version-controlled resource produced a new version.  The checkout-in-place feature provides an alternative mechanism that allows a client to explicitly check out and check in a resource to create a new version.

4.1        Additional Version Properties

The checkout-in-place feature introduces the following REQUIRED properties for a version.

4.1.1           DAV:checkout-fork

This property controls the behavior of CHECKOUT when a version already is checked out or has a successor.  If the DAV:checkout-fork of a version is DAV:forbidden, a CHECKOUT request MUST fail if it would result in that version appearing in the DAV:predecessor-set or DAV:checked-out property of more than one version or checked-out resource.  If DAV:checkout-fork is DAV:discouraged, such a CHECKOUT request MUST fail unless DAV:fork-ok is specified in the CHECKOUT request body.

A server MAY reject attempts to modify the DAV:checkout-fork of a version.

<!ELEMENT checkout-fork ANY>

ANY value: A sequence of elements with at most one DAV:discouraged or DAV:forbidden element.

<!ELEMENT discouraged EMPTY>

<!ELEMENT forbidden EMPTY>

4.1.2           DAV:checkin-fork

This property controls the behavior of CHECKIN when a version already has a successor.  If the DAV:checkin-fork of a version is DAV:forbidden, a CHECKIN request MUST fail if it would result in that version appearing in the DAV:predecessor-set of more than one version.  If DAV:checkin-fork is DAV:discouraged, such a CHECKIN request MUST fail unless DAV:fork-ok is specified in the CHECKIN request body.

A server MAY reject attempts to modify the DAV:checkin-fork of a version.

<!ELEMENT checkin-fork ANY>

ANY value: A sequence of elements with at most one DAV:discouraged or DAV:forbidden element.

<!ELEMENT discouraged EMPTY>

<!ELEMENT forbidden EMPTY>

4.2        Checked-Out Resource Properties

The checkout-in-place feature introduces the following REQUIRED properties for a checked-out resource.

4.2.1           DAV:checkout-fork

This property determines the DAV:checkout-fork property of the version that results from checking in this resource.

4.2.2           DAV:checkin-fork

This property determines the DAV:checkin-fork property of the version that results from checking in this resource.

4.3        CHECKOUT Method (applied to a version-controlled resource)

A CHECKOUT request can be applied to a checked-in version-controlled resource to allow modifications to the content and dead properties of that version-controlled resource.

If a CHECKOUT request fails, the server state preceding the request MUST be restored.

Marshalling:

If a request body is included, it MUST be a DAV:checkout XML element.

<!ELEMENT checkout ANY>

ANY value: A sequence of elements with at most one DAV:fork-ok element.

 

<!ELEMENT fork-ok EMPTY>

 

If a response body for a successful request is included, it MUST be a DAV:checkout-response XML element.

<!ELEMENT checkout-response ANY>

 

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:must-be-checked-in): If a version-controlled resource is being checked out, it MUST have a non-empty DAV:checked-in property.

(DAV:checkout-of-version-with-descendant-is-forbidden): If the DAV:checkout-fork property of the version being checked out is DAV:forbidden, the request MUST fail if a version identifies that version in its DAV:predecessor-set.

(DAV:checkout-of-version-with-descendant-is-discouraged): If the DAV:checkout-fork property of the version being checked out is DAV:discouraged, the request MUST fail if a version identifies that version in its DAV:predecessor-set unless DAV:fork-ok is specified in the request body.

(DAV:checkout-of-checked-out-version-is-forbidden): If the DAV:checkout-fork property of the version being checked out is DAV:forbidden, the request MUST fail if a checked-out resource identifies that version in its DAV:checked-out property.

(DAV:checkout-of-checked-out-version-is-discouraged): If the DAV:checkout-fork property of the version being checked out is DAV:discouraged, the request MUST fail if a checked-out resource identifies that version in its DAV:checked-out property unless DAV:fork-ok is specified in the request body.

Postconditions:

(DAV:is-checked-out): The checked-out resource MUST have a DAV:checked-out property that identifies the DAV:checked-in version preceding the checkout.  The version-controlled resource MUST NOT have a DAV:checked-in property.

(DAV:initialize-predecessor-set): The DAV:predecessor-set property of the checked-out resource MUST be initialized to be the DAV:checked-out version.

4.3.1            Example - CHECKOUT of a version-controlled resource

>>REQUEST

 

  CHECKOUT /foo.html HTTP/1.1

  Host: www.webdav.org

  Content-Length: 0

 

>>RESPONSE

 

  HTTP/1.1 200 OK

  Cache-Control: no-cache

 

In this example, the version-controlled resource /foo.html is checked out.

4.4        CHECKIN Method (applied to a version-controlled resource)

A CHECKIN request can be applied to a checked-out version-controlled resource to produce a new version whose content and dead properties are copied from the checked-out resource.

If a CHECKIN request fails, the server state preceding the request MUST be restored.

Marshalling:

If a request body is included, it MUST be a DAV:checkin XML element.

<!ELEMENT checkin ANY>

ANY value: A sequence of elements with at most one DAV:keep-checked-out element and at most one DAV:fork-ok element.

 

<!ELEMENT keep-checked-out EMPTY>

<!ELEMENT fork-ok EMPTY>

 

If a response body for a successful request is included, it MUST be a DAV:checkin-response XML element.

<!ELEMENT checkin-response ANY>

 

The response to a successful request MUST include a Location header containing the URL for the new version created by the checkin.

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:must-be-checked-out): The request-URL MUST identify a resource with a non-empty DAV:checked-out property.

(DAV:version-history-is-tree) The versions identified by the DAV:predecessor-set of the checked-out resource MUST be descendants of the root version of the version history for the DAV:checked-out version.

(DAV:checkin-fork-forbidden): A CHECKIN request MUST fail if it would cause a version whose DAV:checkin-fork is DAV:forbidden to appear in the DAV:predecessor-set of more than one version.

(DAV:checkin-fork-discouraged): A CHECKIN request MUST fail if it would cause a version whose DAV:checkin-fork is DAV:discouraged to appear in the DAV:predecessor-set of more than one version, unless DAV:fork-ok is specified in the request body.

Postconditions:

(DAV:create-version): The request MUST have created a new version in the version history of the DAV:checked-out version.  The request MUST have allocated a distinct new URL for the new version, and that URL MUST NOT ever identify any resource other than that version. The URL for the new version MUST be returned in a Location response header.

(DAV:initialize-version-content-and-properties): The content, dead properties, DAV:resourcetype, and DAV:predecessor-set of the new version MUST be copied from the checked-out resource.  The DAV:version-name of the new version MUST be set to a server-defined value distinct from all other DAV:version-name values of other versions in the same version history.

(DAV:checked-in): If the request-URL identifies a version-controlled resource and DAV:keep-checked-out is not specified in the request body, the DAV:checked-out property of the version-controlled resource MUST have been removed and a DAV:checked-in property that identifies the new version MUST have been added.

(DAV:keep-checked-out): If DAV:keep-checked-out is specified in the request body, the DAV:checked-out property of the checked-out resource MUST have been updated to identify the new version.

4.4.1           Example - CHECKIN

>>REQUEST

 

  CHECKIN /foo.html HTTP/1.1

  Host: www.webdav.org

  Content-Length: 0

 

>>RESPONSE

 

  HTTP/1.1 201 Created

  Location: http://repo.webdav.org/his/23/ver/32

  Cache-Control: no-cache

 

In this example, version-controlled resource /foo.html is checked in, and a new version is created at http://repo.webdav.org/his/23/ver/32.

4.5        UNCHECKOUT Method

An UNCHECKOUT request can be applied to a checked-out version-controlled resource to cancel the CHECKOUT and restore the pre-CHECKOUT state of the version-controlled resource.

If an UNCHECKOUT request fails, the server MUST undo any partial effects of the UNCHECKOUT request.

Marshalling:

If a request body is included, it MUST be a DAV:uncheckout XML element.

<!ELEMENT uncheckout ANY>

 

If a response body for a successful request is included, it MUST be a DAV:uncheckout-response XML element.

<!ELEMENT uncheckout-response ANY>

 

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:must-be-checked-out-version-controlled-resource): The request-URL MUST identify a version-controlled resource with a non-empty DAV:checked-out property.

Postconditions:

(DAV:cancel-checked-out): The value of the DAV:checked-in property is that of the DAV:checked-out property prior to the request, and the DAV:checked-out property has been removed.

(DAV:restore-content-and-dead-properties): The content and dead properties of the version-controlled resource are copies of its DAV:checked-in version.

4.5.1           Example - UNCHECKOUT

>>REQUEST

 

  UNCHECKOUT /foo.html HTTP/1.1

  Host: www.webdav.org

  Content-Length: 0


>>RESPONSE

 

  HTTP/1.1 200 OK

  Cache-Control: no-cache

 

In this example, the content and dead properties of the version-controlled resource identified by http://www.webdav.org/foo.html are restored to their values preceding the most recent CHECKOUT of that version-controlled resource.

4.6        Additional OPTIONS Semantics

If a server supports the checkout-in-place feature, it MUST include "checkout-in-place" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods.

5         Version-History Feature

It is often useful to have access to a version history even after all version-controlled resources for that version history have been deleted.  A server can provide this functionality by supporting version history resources.  A version history resource is a resource that exists in a server defined namespace and therefore is unaffected by any deletion or movement of version-controlled resources.  A version history resource is an appropriate place to add a property that logically applies to all states of a resource.  The DAV:expand-property report (see Section 3.8) can be applied to the DAV:version-set of a version history resource to provide a variety of useful reports on all versions in that version history.

5.1        Version History Properties

The DAV:resourcetype of a version history MUST include DAV:version-history.

The version-history feature introduces the following REQUIRED properties for a version history.

5.1.1           DAV:version-set (protected)

This property identifies each version of this version history.

<!ELEMENT version-set (href+)>

5.1.2           DAV:root-version (computed)

This property identifies the root version of this version history.

<!ELEMENT root-version (href)>

5.2        Additional Version-Controlled Resource Properties

The version-history feature introduces the following REQUIRED property for a version-controlled resource.

5.2.1           DAV:version-history (computed)

This property identifies the version history resource for the DAV:checked-in or DAV:checked-out version of this version-controlled resource.

<!ELEMENT version-history (href)>

5.3        Additional Version Properties

The version-history feature introduces the following REQUIRED property for a version.

5.3.1           DAV:version-history (computed)

This property identifies the version history that contains this version.

<!ELEMENT version-history (href)>

5.4        DAV:locate-by-history Report

Many properties identify a version from some version history.  It is often useful to be able to efficiently locate a version-controlled resource for that version history.  The DAV:locate-by-history report can be applied to a collection to locate the collection member that is a version-controlled resource for a specified version history resource.

Marshalling:

The request body MUST be a DAV:locate-by-history XML element.

<!ELEMENT locate-by-history (version-history-set, prop)>

<!ELEMENT version-history-set (href+)>

prop: see RFC 2518, Section 12.11

 

The response body for a successful request MUST be a DAV:multistatus XML element containing every version-controlled resource that is a member of the collection identified by the request-URL or the collection itself, and whose DAV:version-history property identifies one of the version history resources identified by the request body.  The DAV:prop element in the request body identifies which properties should be reported in the DAV:prop elements in the response body.

Preconditions:

(DAV:must-be-version-history): Each member of the DAV:version-history-set element in the request body MUST identify a version history resource.

5.4.1           Example - DAV:locate-by-history Report

>>REQUEST

 

  REPORT /ws/public HTTP/1.1

  Host: www.webdav.org

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:locate-by-history xmlns:D="DAV:">

    <D:version-history-set>

      <D:href>http://repo.webdav.org/his/23</D:href>

      <D:href>http://repo.webdav.org/his/84</D:href>

      <D:href>http://repo.webdav.org/his/129</D:href>

    </D:version-history-set>

    <D:prop>

      <D:version-history/>

    </D:prop>

  </D:locate-by-history>

 

>>RESPONSE

 

  HTTP/1.1 207 Multi-Status

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:multistatus xmlns:D="DAV:">

    <D:response>

      <D:href>http://www.webdav.org/ws/public/x/test.html</D:href>

      <D:propstat>

        <D:prop>

          <D:version-history>

            <D:href>http://repo.webdav.org/his/23</D:href>

          </D:version-history>

        </D:prop>

        <D:status>HTTP/1.1 200 OK</D:status>

      </D:propstat>

    </D:response>

  </D:multistatus>

 

In this example, there is only one version-controlled member of /ws/public that is a version-controlled resource for one of the three specified version history resources.  In particular, /ws/public/x/test.html is the version-controlled resource for http://repo.webdav.org/his/23.

5.5        Additional OPTIONS Semantics

If the server supports the version-history feature, it MUST include "version-history" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods.

5.6        Additional DELETE Semantics

Additional Postconditions:

(DAV:delete-version-set): If the request deleted a version history, the request MUST have deleted all versions in the DAV:version-set of that version history, and MUST have satisfied the postconditions for version deletion (see Section 3.13).

(DAV:version-history-has-root): If the request deleted the root version of a version history, the request MUST have updated the DAV:root-version of the version history to refer to another version that is an ancestor of all other remaining versions in that version history.  A result of this postcondition is that every version history will have at least one version, and the only way to delete all versions is to delete the version history resource.

5.7        Additional COPY Semantics

Additional Preconditions:

(DAV:cannot-copy-history): If the request-URL identifies a version history, the request MUST fail.  In order to create another version history whose versions have the same content and dead properties, the appropriate sequence of VERSION-CONTROL, CHECKOUT, PUT, PROPPATCH, and CHECKIN requests must be made.

5.8        Additional MOVE Semantics

Additional Preconditions:

(DAV:cannot-rename-history): If the request-URL identifies a version history, the request MUST fail.

5.9        Additional VERSION-CONTROL Semantics

Additional Postconditions:

(DAV:new-version-history): If the request created a new version history, the request MUST have allocated a new server-defined URL for that version history that MUST NOT have previously identified any other resource, and MUST NOT ever identify a resource other than this version history.

5.10    Additional CHECKIN Semantics

Additional Postconditions:

(DAV:add-to-history): A URL for the new version resource MUST have been added to the DAV:version-set of the version history of the DAV:checked-out version.

5.11    Additional Resource Properties (NOTE: Move up to 5.1 on final editing pass)

The version-history feature introduces the following REQUIRED property for resources that reside in a part of a server's namespace that supports version histories.

5.11.1       DAV:version-history-collection-set (protected)

The DAV:version-history-collection-set property identifies collections that may contain version histories.  An identified collection MAY be the root collection of a tree of collections, all of which may contain version histories.  Since different servers can control different parts of the URL namespace, different resources on the same host MAY have different DAV:version-history-collection-set values.  The identified collections MAY be located on different hosts from the resource.

<!ELEMENT version-history-collection-set (href+)>

6         Workspace Feature

In order to allow multiple users to work concurrently on adding versions to the same version history, it is necessary to allocate on the server multiple checked-out resources for the same version history.  Even if only one user is making changes to a resource, that user will sometimes wish to create a "private" version, and then to expose that version at a later time.  One way to provide this functionality depends on the client keeping track of its current set of checked-out resources.  This is the working-resource feature defined in Section 8.  The other way to provide this functionality avoids the need for persistent state on the client, and instead has the server maintain a human meaningful namespace for related sets of checked-out resources.  This is the workspace feature defined in this section.

The workspace feature introduces a "workspace resource".  A workspace resource is a collection whose members are related version-controlled and non-version-controlled resources.  Multiple workspaces may be used to expose different versions and configurations of a set of version-controlled resources concurrently.  In order to make changes to a version-controlled resource in one workspace visible in another workspace, that version-controlled resource must be checked in, and then the corresponding version-controlled resource in the other workspace can be updated to display the content and dead properties of the new version. 

In order to ensure unambiguous merging (see Section 11) and baselining (see Section 12) semantics, a workspace may contain at most one version-controlled resource for a given version history.  This is required for unambiguous merging because the MERGE method must identify which version-controlled resource is to be the merge target of a given version.  This is required for unambiguous baselining because a baseline can only select one version for a given version-controlled resource.

Initially, an empty workspace can be created.  Non-version-controlled resources can then be added to the workspace with standard WebDAV requests such as PUT and MKCOL.  Version-controlled resources can be added to the workspace with VERSION-CONTROL requests.  If the baseline feature is supported, collections in the workspace can be placed under baseline control, and then initialized by existing baselines.

6.1        Workspace Properties

The workspace feature introduces the following REQUIRED property for a workspace.

6.1.1           DAV:workspace-checkout-set (computed)

This property identifies each checked-out resource whose DAV:workspace property identifies this workspace.

<!ELEMENT workspace-checkout-set (href*)>

6.2        Additional Resource Properties

The workspace feature introduces the following REQUIRED property for a WebDAV resource.

6.2.1           DAV:workspace (protected)

The DAV:workspace property of a workspace resource MUST identify itself.  The DAV:workspace property of any other type of resource MUST be the same as the DAV:workspace of its parent collection.  If the resource is not a workspace and does not have a parent collection, then it MUST NOT have a DAV:workspace property.

<!ELEMENT workspace (href)>

 

6.2.2           DAV:workspace-collection-set (protected)  NOTE: Move up to 6.2.1 in final editing pass.

The DAV:workspace-collection-set property identifies collections that may contain workspaces.  An identified collection MAY be the root collection of a tree of collections, all of which may contain workspaces.  Since different servers can control different parts of the URL namespace, different resources on the same host MAY have different DAV:workspace-collection-set values.  The identified collections MAY be located on different hosts from the resource.

<!ELEMENT workspace-collection-set (href+)>

6.3        MKWORKSPACE Method

A MKWORKSPACE request creates a new workspace resource.  A server MAY restrict workspace creation to particular collections, but a client can determine the location of these collections from a DAV:workspace-collection-set property.

If a MKWORKSPACE request fails, the server state preceding the request MUST be restored.

Marshalling:

If a request body is included, it MUST be a DAV:mkworkspace XML element.

<!ELEMENT mkworkspace ANY>

 

If a response body for a successful request is included, it MUST be a DAV:mkworkspace-response XML element.

<!ELEMENT mkworkspace-response ANY>

 

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:resource-must-be-null): A resource MUST NOT exist at the request-URL.

(DAV:workspace-location-ok): The request-URL MUST identify a location where a workspace can be created.

Postconditions:

(DAV:initialize-workspace): A new workspace exists at the request-URL.  The DAV:resourcetype of the workspace MUST include DAV:collection.  The DAV:workspace of the workspace MUST identify the workspace.

6.3.1           Example - MKWORKSPACE

>>REQUEST

 

  MKWORKSPACE /ws/public HTTP/1.1

  Host: www.webdav.org

  Content-Length: 0

 

>>RESPONSE

 

  HTTP/1.1 201 Created

  Cache-Control: no-cache

 

In this example, a new workspace is created at http://www.webdav.org/ws/public.

6.4        Additional OPTIONS Semantics

If a server supports the workspace feature, it MUST include "workspace" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods.

If a server supports the workspace feature, it MUST also support the checkout-in-place feature and the version-history feature.

6.5        Additional DELETE Semantics

Additional Postconditions:

(DAV:delete-workspace-members): If a workspace is deleted, any resource that identifies that workspace in its DAV:workspace property MUST be deleted.

6.6        Additional MOVE Semantics

Additional Postconditions:

(DAV:workspace-member-moved): If the request-URL did not identify a workspace, the DAV:workspace of the destination MUST have been updated to have the same value as the DAV:workspace of the parent collection of the destination.

(DAV:workspace-moved): If the request-URL identified a workspace, any reference to that workspace in a DAV:workspace property MUST have been updated to refer to the new location of that workspace.

6.7        Additional VERSION-CONTROL Semantics

A VERSION-CONTROL request can be used to create a new version-controlled resource for an existing version history.  This allows the creation of version-controlled resources for the same version history in multiple workspaces.

Additional Marshalling:

<!ELEMENT version-control ANY>

ANY value: A sequence of elements with at most one DAV:version element.

 

<!ELEMENT version (href)>

 

If the request created a new version-controlled resource at the request-URL, the response status MUST be 201 (Created).

Additional Preconditions:

(DAV:cannot-add-to-existing-history): If the DAV:version-control request body element includes a DAV:version element, the request-URL MUST NOT identify a resource.

(DAV:must-be-version): The DAV:href of the DAV:version element MUST identify a version.

(DAV:one-version-controlled-resource-per-history-per-workspace): If the DAV:version-control request body specifies a version, and if the request-URL is a member of a workspace, then there MUST NOT already be a version-controlled member of that workspace whose DAV:checked-in or DAV:checked-out property identifies any version from the version history of the version specified in the request body.

Additional Postconditions:

(DAV:new-version-controlled-resource): If the request-URL did NOT identify a resource, a new version-controlled resource exists at the request-URL whose content and dead properties are initialized by those of the version in the request body, and whose DAV:checked-in property identifies that version.

6.7.1           Example - VERSION-CONTROL (using an existing version history)

>>REQUEST

 

  VERSION-CONTROL /ws/public/bar.html HTTP/1.1

  Host: www.webdav.org

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:version-control xmlns:D="DAV:">

    <D:version>

      <D:href>http://repo.webdav.org/his/12/ver/V3</D:href>

    </D:version>

  </D:version-control>

  
>>RESPONSE

 

  HTTP/1.1 201 Created

  Cache-Control: no-cache

 

In this example, a new version-controlled resource is created at /ws/public/bar.html.  The content and dead properties of the new version-controlled resource are initialized to be the same as those of the version identified by http://repo.webdav.org/his/12/ver/V3.

7         Update Feature

The update feature provides a mechanism for changing the state of a checked-in version-controlled resource to be that of another version from the version history of that resource.

7.1        UPDATE Method

The UPDATE method modifies the content and dead properties of a checked-in version-controlled resource (the "update target") to be those of a specified version (the "update source") from the version history of that version-controlled resource.

The response to an UPDATE request identifies the resources modified by the request, so that a client can efficiently update any cached state it is maintaining.  Extensions to the UPDATE method allow multiple resources to be modified from a single UPDATE request (see Section 12.13).

Marshalling:

The request body MUST be a DAV:update element.

<!ELEMENT update ANY>

ANY value: A sequence of elements with at most one DAV:version element and at most one DAV:prop element.

<!ELEMENT version (href)>

prop: see RFC 2518, Section 12.11

 

The response for a successful request MUST be a 207 Multi-Status, where the DAV:multistatus XML element in the response body  identifies all resources that have been modified by the request.

multistatus: see RFC 2518, Section 12.9

 

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:must-be-checked-in): The request-URL MUST identify a resource with a non-empty DAV:checked-in property.

Postconditions:

(DAV:update-content-and-properties): If the DAV:version element in the request body identified a version that is in the same version history as the DAV:checked-in version of a version-controlled resource identified by the request-URL, then the content and dead properties of that version-controlled resource MUST be the same as those of the version specified by the DAV:version element, and the DAV:checked-in property of the version-controlled resource MUST identify that version.  The request-URL MUST appear in a DAV:response element in the response body.

(DAV:report-properties): If DAV:prop is specified in the request body, the properties specified in the DAV:prop element MUST be reported in the DAV:response elements in the response body.

7.1.1            Example - UPDATE

>>REQUEST

 

  UPDATE /foo.html HTTP/1.1

  Host: www.webdav.org

  Content-type: text/xml; charset="utf-8"

  Content-Length: xxxx


  <?xml version="1.0" encoding="utf-8" ?>

  <D:update xmlns:D="DAV:">

    <D:version>

      <D:href>http://repo.webdav.org/his/23/ver/33</D:href>

    </D:version>

  </D:update>

 

>>RESPONSE

 

  HTTP/1.1 207 Multi-Status

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

  Cache-Control: no-cache

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:multistatus xmlns:D="DAV:">

    <D:response>

      <D:href>http://www.webdav.org/foo.html</D:href>

      <D:status>HTTP/1.1 200 OK</D:status>

    </D:response>

  </D:multistatus>

 

In this example, the content and dead properties of http://repo.webdav.org/his/23/ver/33 are copied to the version-controlled resource /foo.html, and the DAV:checked-in property of /foo.html is updated to refer to http://repo.webdav.org/his/23/ver/33.

7.2        Additional OPTIONS Semantics

If the server supports the update feature, it MUST include "update" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods.

8         Label Feature

A version "label" is a string that distinguishes one version in a version history from all other versions in that version history.  A label can automatically be assigned by a server, or it can be assigned by a client in order to provide a meaningful name for that version.  A given version label can be assigned to at most one version of a given version history, but client assigned labels can be reassigned to another version at any time.  Note that although a given label can be applied to at most one version from the same version history, the same label can be applied to versions from different version histories.

8.1        Additional Version Properties

The label feature introduces the following REQUIRED property for a version.

8.1.1           DAV:label-name-set (protected)

This property contains the labels that currently select this version.

<!ELEMENT label-name-set (label-name*)>

<!ELEMENT label-name (#PCDATA)>

PCDATA value: string

8.2        LABEL Method

A LABEL request can be applied to a version to modify the labels that select that version.  The case of a label name MUST be preserved when it is stored and retrieved.  When comparing two label names to decide if they match or not, a server SHOULD use a case-sensitive URL-escaped UTF-8 encoded comparison of the two label names.

If a LABEL request is applied to a checked in version-controlled resource, the operation MUST be applied to the DAV:checked-in version of that version-controlled resource.

Marshalling:

The request body MUST be a DAV:label element.

<!ELEMENT label ANY>

ANY value: A sequence of elements with at most one DAV:add, DAV:set, or DAV:remove element.

 

<!ELEMENT add (label-name)>

<!ELEMENT set (label-name)>

<!ELEMENT remove (label-name)>

<!ELEMENT label-name (#PCDATA)>

PCDATA value: string

 

The request MAY include a Depth header.  If no Depth header is included, Depth:0 is assumed.  Standard depth semantics apply, and the request is applied to the collection identified by the request-URL and to all members of the collection that satisfy the Depth value.  If a Depth header is included and the request fails on any resource, the response MUST be a 207 Multi-Status that identifies all resources for which the request has failed.

If a response body for a successful request is included, it MUST be a DAV:label-response XML element.

<!ELEMENT label-response ANY>

 

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:must-be-checked-in): The request-URL MUST identify a resource with a non-empty DAV:checked-in property.

(DAV:add-must-be-new-label): If DAV:add is specified in the request body, the specified label MUST NOT appear in the DAV:label-name-set of any version in the version history of that version-controlled resource.

(DAV:label-must-exist): If DAV:remove is specified in the request body, the specified label MUST appear in the DAV:label-name-set of that version.

Postconditions:

(DAV:add-or-set-label): If DAV:add or DAV:set is specified in the request body, the specified label MUST appear in the DAV:label-name-set of the specified version, and MUST NOT appear in the DAV:label-name-set of any other version in the version history of that version.

(DAV:remove-label): If DAV:remove is specified in the request body, the specified label MUST NOT appear in the DAV:label-name-set of any version in the version history of that version.

8.2.1            Example - Setting a label

>>REQUEST

 

  LABEL /foo.html HTTP/1.1

  Host: www.webdav.org

  Content-type: text/xml; charset="utf-8"

  Content-Length: xxxx


  <?xml version="1.0" encoding="utf-8" ?>

  <D:label xmlns:D="DAV:">
    <D:set>

      <D:label-name>default</D:label-name>

    </D:set>
  </D:label>

 

>>RESPONSE

 

  HTTP/1.1 200 OK

  Cache-Control: no-cache

 

In this example, the label "default" is applied to the DAV:checked-in version of /foo.html.

8.3        DAV:labeled-version Report

The DAV:labeled-version report describes the requested properties of the version with that label in a specified version history.  If the DAV:labeled-version report is applied to a version-controlled resource, it is applied to the DAV:version-history of that version-controlled resource.

Marshalling:

The request body MUST be a DAV:labeled-version XML element.

<!ELEMENT labeled-version ANY>

ANY value: a sequence of zero or more elements, with at most one DAV:prop element and with exactly one DAV:label-name element.

prop: see RFC 2518, Section 12.11

 

The response body for a successful Depth:0 request MUST be a DAV:labeled-version-report XML element.

<!ELEMENT labeled-version-report (href, prop)>

prop: see RFC 2518, Section 12.11

 

The DAV:href identifies the selected version, and the DAV:prop contains the requested properties of that version.

8.3.1           Example - DAV:labeled-version Report

>>REQUEST

 

  REPORT /folder/ HTTP/1.1

  Host: www.webdav.org

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

  Depth: 1

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:labeled-version xmlns:D="DAV:">

    <D:label-name>tested</D:label-name>

    <D:prop>

      <D:version-name/>

    </D:prop>

  </D:labeled-version>

 

>>RESPONSE

 

  HTTP/1.1 207 Multi-Status

  Content-Type: text/xml; charset="utf-8"

  Content-Length: xxxx

 

  <?xml version="1.0" encoding="utf-8" ?>

  <D:multistatus xmlns:D="DAV:">

    <D:response>

      <D:href>http://www.webdav.org/folder/</D:href>

      <D:propstat>

        <D:prop> <D:labeled-version-report>

          <D:href>http://repo.webdav.org/his/23/ver/V5</D:href>

          <D:prop>

            <D:version-name>V5</D:version-name>

          </D:prop>

          </D:labeled-version-report> </D:prop>

        <D:status>HTTP/1.1 200 OK</D:status>

      </D:propstat>

    </D:response>

    <D:response>

      <D:href>http://www.webdav.org/folder/foo.html</D:href>

      <D:propstat>

        <D:prop> <D:labeled-version-report>

          <D:href>http://repo.webdav.org/his/84/ver/V8</D:href>

          <D:prop>

            <D:version-name>V8</D:version-name>

          </D:prop>

        </D:labeled-version-report> </D:prop>

        <D:status>HTTP/1.1 200 OK</D:status>

      </D:propstat>

    </D:response>

  </D:multistatus>

 

8.4        Additional OPTIONS Semantics

If the server supports the label feature, it MUST include "label" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods.

8.5        Additional UPDATE Semantics

If the request body of an UPDATE request includes a DAV:label-name element, the update target is the resource identified by the request-URL, and the update source is the version selected by the specified label from the version history of the update target.

Additional Marshalling:

<!ELEMENT update ANY>

ANY value: A sequence of elements with at most one DAV:label-name or DAV:version element (but not both).

<!ELEMENT label-name (#PCDATA)>

PCDATA value: string

 

The request MAY include a Depth header.  If no Depth header is included, Depth:0 is assumed.  Standard depth semantics apply, and the request is applied to the collection identified by the request-URL and to all members of the collection that satisfy the Depth value.  If a Depth header is included and the request fails on any resource, the response MUST be a 207 Multi-Status that identifies all resources for which the request has failed.

Additional Preconditions:

(DAV:must-select-version-in-history): If the request includes a DAV:label-name element in the request body, the label MUST select a version in the version history of the version-controlled resource identified by the request-URL.

(DAV:depth-update): If the request includes a Depth header, standard depth semantics apply, and the request is applied to the collection identified by the request-URL and to all members of the collection that satisfy the Depth value.  The request MUST be applied to a collection before being applied to any members of that collection, since an update of a version-controlled collection might change the membership of that collection.

Additional Postconditions:

(DAV:apply-request-to-labeled-version): If a DAV:label-name element appears in the request body, the content and dead properties of the version-controlled resource must have been updated to be those of the version selected by that label.

9         Working-Resource Feature

The working-resource feature provides an alternative to the workspace feature for supporting parallel development.  Unlike the workspace feature, where the desired configuration of versions and checked-out resources is maintained on the server, the working-resource feature maintains the configuration on the client. This simplifies the server implementation, but does not allow a user to access the configuration from clients in different physical locations, such as from another office, from home, or while traveling.  Another difference is that the workspace feature isolates clients from a logical change that involves renaming shared resources, until that logical change is complete and tested; with the working resource feature, all clients use a common set of shared version-controlled resources and every client sees the result of a MOVE as soon as it occurs.

If a server supports the working-resource feature but not the checkout-in-place feature, a CHECKOUT request can only be used to create a working resource, and cannot be used to check out a version-controlled resource.  If a server supports the checkout-in-place feature, but not the working-resource feature, a CHECKOUT can only be used to change the state of a version-controlled resource from checked-in to checked-out.

9.1        Additional Version Properties

The working-resource feature introduces the following REQUIRED properties for a version.

9.1.1           DAV:checkout-fork

This property is defined in Section 4.1.1.

9.1.2           DAV:checkin-fork

This property is defined in Section 4.1.2.

9.2        Working Resource Properties

The working-resource feature introduces the following REQUIRED properties for a working resource.  Since a working resource is a checked-out resource, it also has any property defined in this document for a checked-out resource.

9.2.1           DAV:auto-update (protected)

This property identifies the version-controlled resource that will be updated when the working resource is checked in.

<!ELEMENT auto-update (href)>

9.2.2           DAV:checkout-fork

This property is defined in Section 4.2.1.

9.2.3           DAV:checkin-fork

This property is defined in Section 4.2.2.

9.3        CHECKOUT Method (applied to a version)

A CHECKOUT request can be applied to a version to create a new working resource.  The content and dead properties of the working resource are a copy of the version that was checked out.

Marshalling:

If a request body is included, it MUST be a DAV:checkout XML element.

<!ELEMENT checkout ANY>

ANY value: A sequence of elements with at most one DAV:apply-to-version and at most one DAV:fork-ok element.

 

<!ELEMENT apply-to-version EMPTY>

<!ELEMENT fork-ok EMPTY>

 

If a response body for a successful request is included, it MUST be a DAV:checkout-response XML element.

<!ELEMENT checkout-response ANY>

 

The response MUST include a Location header.

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:checkout-of-version-with-descendant-is-forbidden): See Section 4.3.

(DAV:checkout-of-version-with-descendant-is-discouraged): See Section 4.3.

(DAV:checkout-of-checked-out-version-is-forbidden): See Section 4.3.

(DAV:checkout-of-checked-out-version-is-discouraged): See Section 4.3.

Postconditions:

(DAV:create-working-resource): If the request-URL identified a version, the Location response header MUST contain the URL of a new working resource.  The DAV:checked-out property and DAV:predecessor-set property of the new working resource MUST identify the version that was checked out.  The content, dead properties, and DAV:resourcetype property of the working resource MUST be copied from the checked out version.  The DAV:auto-update property of the working resource MUST NOT exist.

(DAV:create-working-resource-from-checked-in-version): If the request-URL identified a version-controlled resource, and DAV:apply-to-version is specified in the request body, the CHECKOUT is applied to the DAV:checked-in version of the version-controlled resource, and not the version-controlled resource itself.  A new working resource is created and the version-controlled resource remains checked-in.  The DAV:auto-update property of the working resource MUST identify the version-controlled resource.

9.3.1            Example - CHECKOUT of a version

>>REQUEST

 

  CHECKOUT /his/12/ver/V3 HTTP/1.1

  Host: repo.webdav.org

  Content-Length: 0

  
>>RESPONSE

 

  HTTP/1.1 201 Created

  Location: http://repo.webdav.org/wr/157

  Cache-Control: no-cache

 

In this example, the version identified by http://repo.webdav.org/his/12/ver/V3 is checked out, and the new working resource is located at http://repo.webdav.org/wr/157.

9.4        CHECKIN Method (applied to a working resource)

A CHECKIN request can be applied to a working resource to produce a new version whose content and dead properties are a copy of those of the working resource.  If the DAV:auto-update property of the working resource was set because the working resource was created by applying a CHECKOUT with the DAV:apply-to-version flag to a version-controlled resource, the CHECKIN request will also update the content and dead properties of that version-controlled resource to be those of the new version.

Marshalling:

If a request body is included, it MUST be a DAV:checkin XML element.

<!ELEMENT checkin ANY>

ANY value: A sequence of elements with at most one DAV:fork-ok element.

 

<!ELEMENT fork-ok EMPTY>

 

If a response body for a successful request is included, it MUST be a DAV:checkin-response XML element.

<!ELEMENT checkin-response ANY>

 

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:must-be-checked-out): See Section 4.4.

(DAV:version-history-is-tree) See Section 4.4.

(DAV:checkin-fork-forbidden): See Section 4.4.

(DAV:checkin-fork-discouraged): See Section 4.4.

(DAV:no-overwrite-by-auto-update): If the DAV:auto-update property for the checked-out resource identifies a version-controlled resource, at least one of the versions identified by the DAV:predecessor-set property of the checked-out resource MUST identify a version that is either the same as or a descendant of the version identified by the DAV:checked-in property of that version-controlled resource.

Postconditions:

(DAV:create-version): See Section 4.4.

(DAV:initialize-version-content-and-properties): See Section 4.4.

(DAV:auto-update): If the DAV:auto-update property of the checked-out resource identified a version-controlled resource, an UPDATE request with the new version MUST have been applied to that version-controlled resource.

(DAV:delete-working-resource): If the request-URL identifies a working resource and if DAV:keep-checked-out is not specified in the request body, the working resource is deleted.

9.4.1           Example - CHECKIN of a working resource

>>REQUEST

 

  CHECKIN /wr/157 HTTP/1.1

  Host: repo.webdav.org

  Content-Length: 0

 

>>RESPONSE

 

  HTTP/1.1 201 Created

  Location: http://repo.webdav.org/his/23/ver/15

  Cache-Control: no-cache

 

In this example, the working resource /wr/157 checked in, and a new version is created at http://repo.webdav.org/his/23/ver/15.

9.5        Additional OPTIONS Semantics

If the server supports the working-resource feature, it MUST include "working-resource" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods.

9.6        Additional COPY Semantics

Additional Postconditions:

(DAV:copy-creates-new-resource): The result of copying a working resource is a new non-version-controlled resource at the destination of the COPY.  The new resource MAY automatically be put under version control, but the resulting version-controlled resource MUST be associated with a new version history created for that new version-controlled resource. 

9.7        Additional MOVE Semantics

Additional Preconditions:

(DAV:cannot-rename-working-resource): If the request-URL identifies a working resource, the request MUST fail.

Additional Postconditions:

(DAV:update-auto-update): If the request-URL identified a version-controlled resource, any DAV:auto-update properties that identified that version-controlled resource MUST have been updated to contain the new location of that version-controlled resource.

10    Advanced Versioning Features

Advanced versioning addresses the problems of parallel development and configuration management of multiple sets of interrelated resources.  Traditionally, artifacts of software development, including requirements, design documents, code, and test cases, have been a focus of configuration management.  Web sites, comprising multiple inter-linked resources (HTML, graphics, sound, CGI, and others), are another class of complex information artifacts that benefit from the application of configuration management.  The advanced versioning capabilities for coordinating concurrent change provide the infrastructure for efficient and controlled management of large evolving web sites.

10.1    Advanced Versioning Packages

Although a server MAY support any combination of advanced versioning features, in order to minimize the complexity of a WebDAV advanced versioning client, a WebDAV advanced versioning server SHOULD support one of the following packages:

Advanced-Server-Workspace Package: basic-server-workspace package plus all advanced features

Advanced-Client-Workspace Package: basic-client-workspace package plus all advanced features

The advanced-server-workspace package supports advanced versioning capabilities for a client with no persistent state.  The advanced-client-workspace package supports advanced versioning capabilities for a client that maintains configuration state on the client.  A server that supports both advanced workspace packages will interoperate with all versioning clients.

10.2    Advanced Versioning Terms

The following additional terms are used by the advanced versioning features.

Collection

A "collection" is a resource whose state consists of not only content and properties, but also a set of named "bindings", where a binding identifies what RFC 2518 calls an "internal member" of the collection.  Note that a binding is not a resource, but rather is a part of the state of a collection that defines a mapping from a binding name (a URL segment) to a resource (an internal member of the collection).

Collection Version Resource

A "collection version resource", or simply "collection version", captures the dead properties of a version-controlled collection, as well as the names of its version-controlled bindings (see Section 14).  A version-controlled binding is a binding to a version-controlled resource.  If the checkout-in-place feature is supported, a collection version can be created by checking out and then checking in a version-controlled collection.  If the working-resource feature is supported, a collection version can be created by checking out a collection version (to create a "working collection") and then checking in the working collection.

Configuration

A "configuration" is a set of resources that consists of a root collection and all members (not just internal members) of that root collection that are not members of another configuration.  The root collection is called the "configuration root", and the members of this set are called the "members of the configuration".  Note that a collection (which is a single resource) is very different from a configuration (which is a set of resources).

Baseline Resource

A "baseline resource", or simply "baseline", of a collection is a version of the configuration that is rooted at that collection (see Section 12).  In particular, a baseline captures the DAV:checked-in version of every version-controlled member of that configuration.  Note that a collection version (which captures the state of a single resource) is very different from a collection baseline (which captures the state of a set of resources).

Baseline-Controlled Collection

A "baseline-controlled collection" is a collection from which baselines can be created (see Section 12).

Version-Controlled Configuration Resource

A "version-controlled configuration resource", or simply "version-controlled configuration", is a special kind of version-controlled resource that is associated with a baseline-controlled collection, and is used to create and access baselines of that collection (see Section 12).  When a collection is both version-controlled and baseline-controlled, a client can create a new version of the collection by checking out and checking in that collection, and it can create a new baseline of that collection by checking out and checking in the version-controlled configuration of that collection.

Activity Resource

An "activity resource", or simply "activity", is a resource that selects a set of versions that correspond to a single logical change, where the versions selected from a given version history form a single line of descent through that version history (see Section 13).

11    Merge Feature

When a user wants to accept the changes (new versions) created by someone else, it is important not just to update the version-controlled resources in the user's workspace with those new versions, since this could result in "backing out" changes the user has made to those version-controlled resources.  Instead, the versions created in another workspace should be "merged" into the user's version-controlled resources.

The version history of a version-controlled resource provides the information needed to determine the result of the merge.  In particular, the merge should select whichever version is later in the line of descent from the root version.  In case the versions to be merged are on different lines of descent (neither version is a descendant of the other), neither version should be selected, but instead, a new version should be created that contains the logical merge of the content and dead properties of those versions.  The MERGE request can be used to check out each version-controlled resource that requires such a merge, and set the DAV:merge-set property of each checked-out resource to identify the version to be merged.  The user is responsible for modifying the content and dead properties of the checked-out resource so that it represents the logical merge of that version, and then adding that version to the DAV:predecessor-set of the checked-out resource.

If the server is capable of automatically performing the merge, it MAY update the content, dead properties, and DAV:predecessor-set of the checked-out resource itself.  Before checking in the automatically merged resource, the user is responsible for verifying that the automatic merge is correct.

11.1    Additional Checked-Out Resource Properties

The merge feature introduces the following REQUIRED properties for a checked-out resource.

11.1.1       DAV:merge-set

This property identifies each version that is to be merged into this checked-out resource.

<!ELEMENT merge-set (href*)>

11.1.2       DAV:auto-merge-set

This property identifies each version that the server has merged into this checked-out resource.  The client should confirm that the merge has been performed correctly before moving a URL from the DAV:auto-merge-set to the DAV:predecessor-set of a checked-out resource.

<!ELEMENT auto-merge-set (href*)>

11.2    MERGE Method

The MERGE method performs the logical merge of a specified version (the "merge source") into a specified version-controlled resource (the "merge target").  If the merge source is neither an ancestor nor a descendant of the DAV:checked-in or DAV:checked-out version of the merge target, the MERGE checks out the merge target (if it is not already checked out) and adds the URL of the merge source to the DAV:merge-set of the merge target.  It is then the client's responsibility to update the content and dead properties of the checked-out merge target so that it reflects the logical merge of the merge source into the current state of the merge target.  The client indicates that it has completed the update of the merge target, by deleting the merge source URL from the DAV:merge-set of the checked-out merge target, and adding it to the DAV:predecessor-set.  As an error check for a client forgetting to complete a merge, the server MUST fail an attempt to CHECKIN a version-controlled resource with a non-empty DAV:merge-set.

When a server has the ability to automatically update the content and dead properties of the merge target to reflect the logical merge of the merge source, it may do so unless DAV:no-auto-merge is specified in the MERGE request body.  In order to notify the client that a merge source has been automatically merged, the MERGE request MUST add the URL of the auto-merged source to the DAV:auto-merge-set property of the merge target, and not to the DAV:merge-set property.  The client indicates that it has verified that the auto-merge is valid, by deleting the merge source URL from the DAV:auto-merge-set, and adding it to the DAV:predecessor-set.

Multiple merge sources can be specified in a single MERGE request.  The set of merge sources for a MERGE request is determined from the DAV:source element of the MERGE request body as follows:

- If DAV:source identifies a version, that version is a merge source.

- If DAV:source identifies a version-controlled resource, the DAV:checked-in version of that version-controlled resource is a merge source.

- If DAV:source identifies a collection, the DAV:checked-in version of each version-controlled resource that is a member of that collection is a merge source.

The request-URL identifies the set of possible merge targets.  If the request-URL identifies a collection, any member of the configuration rooted at the request-URL is a possible merge target.  The merge target of a particular merge source is the version-controlled or checked-out resource whose DAV:checked-in or DAV:checked-out version is from the same version history as the merge source.  If a merge source has no merge target, that merge source is ignored.

The response to a MERGE request identifies the resources that a client must modify to complete the merge. It also identifies the resources modified by the request, so that a client can efficiently update any cached state it is maintaining.

Marshalling:

The request body MUST be a DAV:merge element.

The set of merge sources is determined by the DAV:source element in the request body.

<!ELEMENT merge ANY>

ANY value: A sequence of elements with one DAV:source element, at most one DAV:no-auto-merge element, at most one DAV:no-checkout element, at most one DAV:prop element, and any legal set of elements that can occur in a DAV:checkout element.

<!ELEMENT source (href)>

<!ELEMENT no-auto-merge EMPTY>

<!ELEMENT no-checkout EMPTY>

prop: see RFC 2518, Section 12.11

 

The response for a successful request MUST be a 207 Multi-Status, where the DAV:multistatus XML element in the response body  identifies all resources that have been modified by the request.

multistatus: see RFC 2518, Section 12.9

 

The response MUST include a Cache-Control:no-cache header.

Preconditions:

(DAV:cannot-merge-checked-out-resource): The DAV:source element MUST NOT identify a checked-out resource.  If the DAV:source element identifies a collection, the collection MUST NOT have a member that is a checked-out resource.

(DAV:checkout-not-allowed): If DAV:no-checkout is specified in the request body, it MUST be possible to perform the merge without checking out any of the merge targets.

All preconditions of the CHECKOUT operation apply to the checkouts performed by the request.

Postconditions:

(DAV:ancestor-version): If a merge target is a version-controlled or checked-out resource whose DAV:checked-in version or DAV:checked-out version is the merge source or is a descendant of the merge source, the merge target MUST NOT have been modified by the MERGE.

(DAV:descendant-version): If the merge target was a checked-in version-controlled resource whose DAV:checked-in version was an ancestor of the merge source, an UPDATE operation MUST have been applied to the merge target to set its content and dead properties to be those of the merge source.  If the UPDATE method is not supported, the merge target MUST have been checked out, the content and dead properties of the merge target MUST have been set to those of the merge source, and the merge source MUST have been added to the DAV:auto-merge-set of the merge target.  The merge target MUST appear in a DAV:response XML element in the response body.

(DAV:checked-out-for-merge): If the merge target was a checked-in version-controlled resource whose DAV:checked-in version was neither a descendant nor an ancestor of the merge source, a CHECKOUT MUST have been applied to the merge target.  All XML elements in the DAV:merge XML element that could appear in a DAV:checkout XML element MUST have been used as arguments to the CHECKOUT request.  The merge target MUST appear in a DAV:response XML element in the response body. 

(DAV:update-merge-set): If the DAV:checked-out version of the merge target is not equal to or a descendant of the merge source, the merge source MUST be added to either the DAV:merge-set or the DAV:auto-merge-set of the merge target.  The merge target MUST appear in a DAV:response XML element in the response body.  If a merge source has been added to the DAV:auto-merge-set, the content and dead properties of the merge target MUST have been modified by the server to reflect the result of a logical merge of the merge source and the merge target.  If a merge source has been added to the DAV:merge-set, the content and dead properties of the merge target MUST NOT have been modified by the server.  If DAV:no-auto-merge is specified in the request body, the merge source MUST NOT have been added to the DAV:auto-merge-set.

(DAV:report-properties): If DAV:prop is specified in the request body, the properties specified in the DAV:prop element MUST be reported in the DAV:response elements in the response body.

11.2.1         Example - MERGE

>>REQUEST

 

  MERGE /ws/public HTTP/1.1

  Host: www.webdav.org

  Content-type: text/xml; charset="utf-8"

  Content-Length: xxxx


  <?xml version="1.0" encoding="utf-8" ?>

  <D:merge xmlns:D="DAV:">

    <D:source>

      <D:href>http://www.webdav.org/ws/dev/sally</D:href>

    </D:source>

  </D:merge>

 </