Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3253

Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)

Pages: 118
Proposed Standard
Errata
Part 1 of 4 – Pages 1 to 20
None   None   Next

Top   ToC   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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   RFC3253 - 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 Section