tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search

RFC 3253

 Errata 
Proposed STD
Pages: 118
Top     in Index     Prev     Next
in Group Index     No Prev: Lowest Number in Group     No Next: Highest Number in Group     Group: DELTAV

Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)

Part 1 of 4, p. 1 to 20
None       Next RFC Part

 


Top       ToC       Page 1 
Network Working Group                                           G. Clemm
Request for Comments: 3253                             Rational Software
Category: Standards Track                                      J. Amsden
                                                              T. Ellison
                                                                     IBM
                                                                C. Kaler
                                                               Microsoft
                                                            J. Whitehead
                                                         U.C. Santa Cruz
                                                              March 2002


                    Versioning Extensions to WebDAV
               (Web Distributed Authoring and Versioning)

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2002).  All Rights Reserved.

Abstract

   This document specifies a set of methods, headers, and resource types
   that define the WebDAV (Web Distributed Authoring and Versioning)
   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....................................................  6
   1.1 Relationship to WebDAV........................................  7
   1.2 Notational Conventions........................................  8
   1.3 Terms.........................................................  8
   1.4 Property Values............................................... 11
    1.4.1 Initial Property Value..................................... 11

Top      ToC       Page 2 
    1.4.2 Protected Property Value................................... 12
    1.4.3 Computed Property Value.................................... 12
    1.4.4 Boolean Property Value..................................... 12
    1.4.5 DAV:href Property Value.................................... 12
   1.5 DAV Namespace XML Elements.................................... 12
   1.6 Method Preconditions and Postconditions....................... 12
    1.6.1 Example - CHECKOUT request................................. 13
   1.7 Clarification of COPY Semantics with Overwrite:T.............. 13
   1.8 Versioning Methods and Write Locks............................ 14
   2 Basic Versioning Features....................................... 14
   2.1 Basic Versioning Packages..................................... 14
   2.2 Basic Versioning Semantics.................................... 16
    2.2.1 Creating a Version-Controlled Resource..................... 16
    2.2.2 Modifying a Version-Controlled Resource.................... 17
    2.2.3 Reporting.................................................. 19
   3 Version-Control Feature......................................... 20
   3.1 Additional Resource Properties................................ 20
    3.1.1 DAV:comment................................................ 20
    3.1.2 DAV:creator-displayname.................................... 20
    3.1.3 DAV:supported-method-set (protected)....................... 20
    3.1.4 DAV:supported-live-property-set (protected)................ 21
    3.1.5 DAV:supported-report-set (protected)....................... 21
   3.2 Version-Controlled Resource Properties........................ 21
    3.2.1 DAV:checked-in (protected)................................. 21
    3.2.2 DAV:auto-version........................................... 22
   3.3 Checked-Out Resource Properties............................... 22
    3.3.1 DAV:checked-out (protected)................................ 23
    3.3.2 DAV:predecessor-set........................................ 23
   3.4 Version Properties............................................ 23
    3.4.1 DAV:predecessor-set (protected)............................ 23
    3.4.2 DAV:successor-set (computed)............................... 23
    3.4.3 DAV:checkout-set (computed)................................ 23
    3.4.4 DAV:version-name (protected)............................... 24
   3.5 VERSION-CONTROL Method........................................ 24
    3.5.1 Example - VERSION-CONTROL.................................. 25
   3.6 REPORT Method................................................. 25
   3.7 DAV:version-tree Report....................................... 26
    3.7.1 Example - DAV:version-tree Report.......................... 27
   3.8 DAV:expand-property Report.................................... 29
    3.8.1 Example - DAV:expand-property.............................. 30
   3.9 Additional OPTIONS Semantics.................................. 31
   3.10 Additional PUT Semantics..................................... 31
   3.11 Additional PROPFIND Semantics................................ 32
   3.12 Additional PROPPATCH Semantics............................... 33
   3.13 Additional DELETE Semantics.................................. 33
   3.14 Additional COPY Semantics.................................... 34
   3.15 Additional MOVE Semantics.................................... 34
   3.16 Additional UNLOCK Semantics.................................. 35

Top      ToC       Page 3 
   4 Checkout-In-Place Feature....................................... 35
   4.1 Additional Version Properties................................. 35
    4.1.1 DAV:checkout-fork.......................................... 36
    4.1.2 DAV:checkin-fork........................................... 36
   4.2 Checked-Out Resource Properties............................... 36
    4.2.1 DAV:checkout-fork.......................................... 36
    4.2.2 DAV:checkin-fork........................................... 37
   4.3 CHECKOUT Method............................................... 37
    4.3.1 Example - CHECKOUT......................................... 38
   4.4 CHECKIN Method................................................ 38
    4.4.1 Example - CHECKIN.......................................... 40
   4.5 UNCHECKOUT Method............................................. 40
    4.5.1 Example - UNCHECKOUT....................................... 41
   4.6 Additional OPTIONS Semantics.................................. 42
   5 Version-History Feature......................................... 42
   5.1 Version History Properties.................................... 42
    5.1.1 DAV:version-set (protected)................................ 42
    5.1.2 DAV:root-version (computed)................................ 42
   5.2 Additional Version-Controlled Resource Properties............. 42
    5.2.1 DAV:version-history (computed)............................. 43
   5.3 Additional Version Properties................................. 43
    5.3.1 DAV:version-history (computed)............................. 43
   5.4 DAV:locate-by-history Report.................................. 43
    5.4.1 Example - DAV:locate-by-history Report..................... 44
   5.5 Additional OPTIONS Semantics.................................. 45
   5.6 Additional DELETE Semantics................................... 46
   5.7 Additional COPY Semantics..................................... 46
   5.8 Additional MOVE Semantics..................................... 46
   5.9 Additional VERSION-CONTROL Semantics.......................... 46
   5.10 Additional CHECKIN Semantics................................. 47
   6 Workspace Feature............................................... 47
   6.1 Workspace Properties.......................................... 48
    6.1.1 DAV:workspace-checkout-set (computed)...................... 48
   6.2 Additional Resource Properties................................ 48
    6.2.1 DAV:workspace (protected).................................. 48
   6.3 MKWORKSPACE Method............................................ 48
    6.3.1 Example - MKWORKSPACE...................................... 49
   6.4 Additional OPTIONS Semantics.................................. 49
    6.4.1 Example - OPTIONS.......................................... 51
   6.5 Additional DELETE Semantics................................... 51
   6.6 Additional MOVE Semantics..................................... 52
   6.7 Additional VERSION-CONTROL Semantics.......................... 52
    6.7.1 Example - VERSION-CONTROL.................................. 53
   7 Update Feature.................................................. 53
   7.1 UPDATE Method................................................. 53
    7.1.1 Example - UPDATE........................................... 55
   7.2 Additional OPTIONS Semantics.................................. 55
   8 Label Feature................................................... 56

Top      ToC       Page 4 
   8.1 Additional Version Properties................................. 56
    8.1.1 DAV:label-name-set (protected)............................. 56
   8.2 LABEL Method.................................................. 56
    8.2.1 Example - Setting a label.................................. 58
   8.3 Label Header.................................................. 58
   8.4 Additional OPTIONS Semantics.................................. 59
   8.5 Additional GET Semantics...................................... 59
   8.6 Additional PROPFIND Semantics................................. 59
   8.7 Additional COPY Semantics..................................... 60
   8.8 Additional CHECKOUT Semantics................................. 60
   8.9 Additional UPDATE Semantics................................... 61
   9 Working-Resource Feature........................................ 62
   9.1 Additional Version Properties................................. 62
    9.1.1 DAV:checkout-fork.......................................... 62
    9.1.2 DAV:checkin-fork........................................... 63
   9.2 Working Resource Properties................................... 63
    9.2.1 DAV:auto-update (protected)................................ 63
    9.2.2 DAV:checkout-fork.......................................... 63
    9.2.3 DAV:checkin-fork........................................... 63
   9.3 CHECKOUT Method (applied to a version)........................ 63
    9.3.1 Example - CHECKOUT of a version............................ 65
   9.4 CHECKIN Method (applied to a working resource)................ 65
    9.4.1 Example - CHECKIN of a working resource.................... 66
   9.5 Additional OPTIONS Semantics.................................. 67
   9.6 Additional COPY Semantics..................................... 67
   9.7 Additional MOVE Semantics..................................... 67
   10  Advanced Versioning Features.................................. 67
   10.1 Advanced Versioning Packages................................. 68
   10.2 Advanced Versioning Terms.................................... 68
   11  MERGE Feature................................................. 70
   11.1 Additional Checked-Out Resource Properties................... 70
    11.1.1 DAV:merge-set............................................. 70
    11.1.2 DAV:auto-merge-set........................................ 71
   11.2 MERGE Method................................................. 71
    11.2.1 Example - MERGE........................................... 74
   11.3 DAV:merge-preview Report..................................... 75
    11.3.1 Example - DAV:merge-preview Report........................ 76
   11.4 Additional OPTIONS Semantics................................. 77
   11.5 Additional DELETE Semantics.................................. 77
   11.6 Additional CHECKIN Semantics................................. 77
   12  Baseline Feature.............................................. 77
   12.1 Version-Controlled Configuration Properties.................. 78
    12.1.1 DAV:baseline-controlled-collection (protected)............ 78
   12.2 Checked-Out Configuration Properties......................... 78
    12.2.1 DAV:subbaseline-set....................................... 78
   12.3 Baseline Properties.......................................... 78
    12.3.1 DAV:baseline-collection (protected)....................... 79
    12.3.2 DAV:subbaseline-set (protected)........................... 79

Top      ToC       Page 5 
   12.4 Additional Resource Properties............................... 79
    12.4.1 DAV:version-controlled-configuration (computed)........... 79
   12.5 Additional Workspace Properties.............................. 80
    12.5.1 DAV:baseline-controlled-collection-set (computed)......... 80
   12.6 BASELINE-CONTROL Method...................................... 80
    12.6.1 Example - BASELINE-CONTROL................................ 82
   12.7 DAV:compare-baseline Report.................................. 84
    12.7.1 Example - DAV:compare-baseline Report..................... 85
   12.8 Additional OPTIONS Semantics................................. 86
   12.9 Additional MKCOL Semantics................................... 86
   12.10 Additional COPY Semantics................................... 86
   12.11 Additional CHECKOUT Semantics............................... 86
   12.12 Additional CHECKIN Semantics................................ 86
   12.13 Additional UPDATE Semantics................................. 87
   12.14 Additional MERGE Semantics.................................. 89
   13  Activity Feature.............................................. 90
   13.1 Activity Properties.......................................... 91
    13.1.1 DAV:activity-version-set (computed)....................... 91
    13.1.2 DAV:activity-checkout-set (computed)...................... 92
    13.1.3 DAV:subactivity-set....................................... 92
    13.1.4 DAV:current-workspace-set (computed)...................... 92
   13.2 Additional Version Properties................................ 92
    13.2.1 DAV:activity-set.......................................... 93
   13.3 Additional Checked-Out Resource Properties................... 93
    13.3.1 DAV:unreserved............................................ 93
    13.3.2 DAV:activity-set.......................................... 93
   13.4 Additional Workspace Properties.............................. 93
    13.4.1 DAV:current-activity-set.................................. 94
   13.5 MKACTIVITY Method............................................ 94
    13.5.1 Example - MKACTIVITY...................................... 95
   13.6 DAV:latest-activity-version Report........................... 95
   13.7 Additional OPTIONS Semantics................................. 96
   13.8 Additional DELETE Semantics.................................. 96
   13.9 Additional MOVE Semantics.................................... 97
   13.10 Additional CHECKOUT Semantics............................... 97
    13.10.1 Example - CHECKOUT with an activity...................... 98
   13.11 Additional CHECKIN Semantics................................ 99
   13.12 Additional MERGE Semantics.................................. 99
   14  Version-Controlled-Collection Feature.........................100
   14.1 Version-Controlled Collection Properties.....................102
    14.1.1 DAV:eclipsed-set (computed)...............................102
   14.2 Collection Version Properties................................103
    14.2.1 DAV:version-controlled-binding-set (protected)............103
   14.3 Additional OPTIONS Semantics.................................103
   14.4 Additional DELETE Semantics..................................103
   14.5 Additional MKCOL Semantics...................................104
   14.6 Additional COPY Semantics....................................104
   14.7 Additional MOVE Semantics....................................104

Top      ToC       Page 6 
   14.8 Additional VERSION-CONTROL Semantics.........................104
   14.9 Additional CHECKOUT Semantics................................105
   14.10 Additional CHECKIN Semantics................................105
   14.11 Additional UPDATE and MERGE Semantics.......................106
   15  Internationalization Considerations...........................106
   16  Security Considerations.......................................107
   16.1 Auditing and Traceability....................................107
   16.2 Increased Need for Access Control............................108
   16.3 Security Through Obscurity...................................108
   16.4 Denial of Service............................................108
   17  IANA Considerations...........................................109
   18  Intellectual Property.........................................109
   19  Acknowledgements..............................................109
   20  References....................................................110
   Appendix A - Resource Classification..............................111
   A.1 DeltaV-Compliant Unmapped URL.................................111
   A.2 DeltaV-Compliant Resource.....................................111
   A.3 DeltaV-Compliant Collection...................................112
   A.4 Versionable Resource..........................................112
   A.5 Version-Controlled Resource...................................112
   A.6 Version.......................................................113
   A.7 Checked-In Version-Controlled Resource........................113
   A.8 Checked-Out Resource..........................................113
   A.9 Checked-Out Version-Controlled Resource.......................114
   A.10 Working Resource.............................................114
   A.11 Version History..............................................114
   A.12 Workspace....................................................115
   A.13 Activity.....................................................115
   A.14 Version-Controlled Collection................................115
   A.15 Collection Version...........................................115
   A.16 Version-Controlled Configuration.............................116
   A.17 Baseline.....................................................116
   A.18 Checked-Out Version-Controlled Configuration.................116
   Authors' Addresses................................................117
   Full Copyright Statement..........................................118

1  Introduction

   This document specifies a set of methods, headers, and properties
   that define the WebDAV (Web Distributed Authoring and Versioning)
   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:

Top      ToC       Page 7 
   -  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.

Top      ToC       Page 8 
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.

Top      ToC       Page 9 
   Checked-Out Resource

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

   Version Resource

      A "version resource", or simply "version", is a resource 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 server
      allocates a distinct new URL for each new version, and this URL
      will never be used to identify any resource other than that
      version.  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 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.

Top      ToC       Page 10 
   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.

Top      ToC       Page 11 
   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.

Top      ToC       Page 12 
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.

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 of the server that
   must be true for that method to be performed.  A "postcondition" of a
   method describes the state of the server that must be true after that
   method has been 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.

Top      ToC       Page 13 
   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

Top      ToC       Page 14 
   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

   A server MAY support any combination of versioning features.
   However, 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
   -  Basic-Client-Workspace Package: version-control, working-
      resource, update, label

Top      ToC       Page 15 
   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.

Top      ToC       Page 16 
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 new distinct and
      unique 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 new distinct and
      unique 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 they 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 is 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.

Top      ToC       Page 17 
   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

Top      ToC       Page 18 
   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.

Top      ToC       Page 19 
   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.

Top      ToC       Page 20 
   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).



(page 20 continued on part 2)

Next RFC Part