Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3253

Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)

Pages: 118
Proposed Standard
Errata
Part 2 of 4 – Pages 20 to 51
First   Prev   Next

Top   ToC   RFC3253 - Page 20   prevText

3 Version-Control Feature

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

3.1 Additional Resource Properties

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

3.1.1 DAV:comment

This property is used to track a brief comment about a resource that is suitable for presentation to a user. The DAV:comment of a version can be used to indicate why that version was created. <!ELEMENT comment (#PCDATA)> PCDATA value: string

3.1.2 DAV:creator-displayname

This property contains a description of the creator of the resource that is suitable for presentation to a user. The DAV:creator- displayname of a version can be used to indicate who created that version. <!ELEMENT creator-displayname (#PCDATA)> PCDATA value: string

3.1.3 DAV:supported-method-set (protected)

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

   <!ELEMENT supported-method-set (supported-method*)>
   <!ELEMENT supported-method ANY>
   <!ATTLIST supported-method name NMTOKEN #REQUIRED>
   name value: a method name

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

This property identifies the live properties that are supported by the resource. A live property is supported by a resource if that property has the semantics defined for that property. The value of this property MUST identify all live properties defined by this document that are supported by the resource, and SHOULD identify all live properties that are supported by the resource. <!ELEMENT supported-live-property-set (supported-live-property*)> <!ELEMENT supported-live-property name> <!ELEMENT prop ANY> ANY value: a property element type

3.1.5 DAV:supported-report-set (protected)

This property identifies the reports that are supported by the resource. <!ELEMENT supported-report-set (supported-report*)> <!ELEMENT supported-report report> <!ELEMENT report ANY> ANY value: a report element type

3.2 Version-Controlled Resource Properties

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

3.2.1 DAV:checked-in (protected)

This property appears on a checked-in version-controlled resource, and identifies a version that has the same content and dead properties as the version-controlled resource. This property is removed when the resource is checked out, and then added back (identifying a new version) when the resource is checked back in. <!ELEMENT checked-in (href)>
Top   ToC   RFC3253 - Page 22

3.2.2 DAV:auto-version

If the DAV:auto-version value is DAV:checkout-checkin, when a modification request (such as PUT/PROPPATCH) is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout and followed by a checkin operation. If the DAV:auto-version value is DAV:checkout-unlocked-checkin, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation. If the resource is not write-locked, the request is automatically followed by a checkin operation. If the DAV:auto-version value is DAV:checkout, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation. If the DAV:auto-version value is DAV:locked-checkout, when a modification request is applied to a write-locked checked-in version-controlled resource, the request is automatically preceded by a checkout operation. If an update to a write-locked checked-in resource is automatically preceded by a checkout of that resource, the checkout is associated with the write lock. When this write lock is removed (e.g. from an UNLOCK or a lock timeout), if the resource has not yet been checked in, the removal of the write lock is automatically preceded by a checkin operation. A server MAY refuse to allow the value of the DAV:auto-version property to be modified, or MAY only support values from a subset of the valid values. <!ELEMENT auto-version (checkout-checkin | checkout-unlocked-checkin | checkout | locked-checkout)? > <!ELEMENT checkout-checkin EMPTY> <!ELEMENT checkout-unlocked-checkin EMPTY> <!ELEMENT checkout EMPTY> <!ELEMENT locked-checkout EMPTY>

3.3 Checked-Out Resource Properties

The version-control feature introduces the following REQUIRED properties for a checked-out resource.
Top   ToC   RFC3253 - Page 23

3.3.1 DAV:checked-out (protected)

This property identifies the version that was identified by the DAV:checked-in property at the time the resource was checked out. This property is removed when the resource is checked in. <!ELEMENT checked-out (href)>

3.3.2 DAV:predecessor-set

This property determines the DAV:predecessor-set property of the version that results from checking in this resource. A server MAY reject attempts to modify the DAV:predecessor-set of a version-controlled resource. <!ELEMENT predecessor-set (href+)>

3.4 Version Properties

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

3.4.1 DAV:predecessor-set (protected)

This property identifies each predecessor of this version. Except for the root version, which has no predecessors, each version has at least one predecessor. <!ELEMENT predecessor-set (href*)>

3.4.2 DAV:successor-set (computed)

This property identifies each version whose DAV:predecessor-set identifies this version. <!ELEMENT successor-set (href*)>

3.4.3 DAV:checkout-set (computed)

This property identifies each checked-out resource whose DAV:checked-out property identifies this version. <!ELEMENT checkout-set (href*)>
Top   ToC   RFC3253 - Page 24

3.4.4 DAV:version-name (protected)

This property contains a server-defined string that is different for each version in a given version history. This string is intended for display for a user, unlike the URL of a version, which is normally only used by a client and not displayed for a user. <!ELEMENT version-name (#PCDATA)> PCDATA value: string

3.5 VERSION-CONTROL Method

A VERSION-CONTROL request can be used to create a version-controlled resource at the request-URL. It can be applied to a versionable resource or to a version-controlled resource. If the request-URL identifies a versionable resource, a new version history resource is created, a new version is created whose content and dead properties are copied from the versionable resource, and the resource is given a DAV:checked-in property that is initialized to identify this new version. If the request-URL identifies a version-controlled resource, the resource just remains under version-control. This allows a client to be unaware of whether or not a server automatically puts a resource under version control when it is created. If a VERSION-CONTROL request fails, the server state preceding the request MUST be restored. Marshalling: If a request body is included, it MUST be a DAV:version-control XML element. <!ELEMENT version-control ANY> If a response body for a successful request is included, it MUST be a DAV:version-control-response XML element. Note that this document does not define any elements for the VERSION-CONTROL response body, but the DAV:version-control-response element is defined to ensure interoperability between future extensions that do define elements for the VERSION-CONTROL response body. <!ELEMENT version-control-response ANY>
Top   ToC   RFC3253 - Page 25
   Postconditions:

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

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

3.5.1 Example - VERSION-CONTROL

>>REQUEST VERSION-CONTROL /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 200 OK In this example, /foo.html is put under version control. A new version history is created for it, and a new version is created that has a copy of the content and dead properties of /foo.html. The DAV:checked-in property of /foo.html identifies this new version.

3.6 REPORT Method

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

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

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

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

      If a Depth request header is included, the response MUST be a 207
      Multi-Status.  The request MUST be applied separately to the
      collection itself and to all members of the collection that
      satisfy the Depth value.  The DAV:prop element of a DAV:response
      for a given resource MUST contain the requested report for that
      resource.

   Preconditions:

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

   Postconditions:

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

3.7 DAV:version-tree Report

The DAV:version-tree report describes the requested properties of all the versions in the version history of a version. If the report is requested for a version-controlled resource, it is redirected to its DAV:checked-in or DAV:checked-out version. The DAV:version-tree report MUST be supported by all version resources and all version-controlled resources. Marshalling: The request body MUST be a DAV:version-tree XML element. <!ELEMENT version-tree ANY> ANY value: a sequence of zero or more elements, with at most one DAV:prop element. prop: see RFC 2518, Section 12.11
Top   ToC   RFC3253 - Page 27
      The response body for a successful request MUST be a
      DAV:multistatus XML element.

      multistatus: see RFC 2518, Section 12.9

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

3.7.1 Example - DAV:version-tree Report

The version history drawn below would produce the following version tree report. foo.html History +---+ | | V1 +---+ / \ / \ +---+ +---+ | | V2 | | V2.1.1 +---+ +---+ >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:version-tree xmlns:D="DAV:"> <D:prop> <D:version-name/> <D:creator-displayname/> <D:successor-set/> </D:prop> </D:version-tree>
Top   ToC   RFC3253 - Page 28
   >>RESPONSE

     HTTP/1.1 207 Multi-Status
     Content-Type: text/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:multistatus xmlns:D="DAV:">
       <D:response>
         <D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
         <D:propstat>
           <D:prop>
             <D:version-name>V1</D:version-name>
             <D:creator-displayname>Fred</D:creator-displayname>
             <D:successor-set>
               <D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
               <D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
             </D:successor-set>
           </D:prop>
           <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>
       </D:response>
       <D:response>
         <D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
         <D:propstat>
           <D:prop>
             <D:version-name>V2</D:version-name>
             <D:creator-displayname>Fred</D:creator-displayname>
             <D:successor-set/>
           </D:prop>
           <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>
       </D:response>
       <D:response>
         <D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
         <D:propstat>
           <D:prop>
             <D:version-name>V2.1.1</D:version-name>
             <D:creator-displayname>Sally</D:creator-displayname>
             <D:successor-set/>
           </D:prop>
           <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>
       </D:response>
     </D:multistatus>
Top   ToC   RFC3253 - Page 29

3.8 DAV:expand-property Report

Many property values are defined as a DAV:href, or a set of DAV:href elements. The DAV:expand-property report provides a mechanism for retrieving in one request the properties from the resources identified by those DAV:href elements. This report not only decreases the number of requests required, but also allows the server to minimize the number of separate read transactions required on the underlying versioning store. The DAV:expand-property report SHOULD be supported by all resources that support the REPORT method. Marshalling: The request body MUST be a DAV:expand-property XML element. <!ELEMENT expand-property (property*)> <!ELEMENT property (property*)> <!ATTLIST property name NMTOKEN #REQUIRED> name value: a property element type <!ATTLIST property namespace NMTOKEN "DAV:"> namespace value: an XML namespace The response body for a successful request MUST be a DAV:multistatus XML element. multistatus: see RFC 2518, Section 12.9 The properties reported in the DAV:prop elements of the DAV:multistatus element MUST be those identified by the DAV:property elements in the DAV:expand-property element. If there are DAV:property elements nested within a DAV:property element, then every DAV:href in the value of the corresponding property is replaced by a DAV:response element whose DAV:prop elements report the values of the properties identified by the nested DAV:property elements. The nested DAV:property elements can in turn contain DAV:property elements, so that multiple levels of DAV:href expansion can be requested. Note that a validating parser MUST be aware that the DAV:expand- property report effectively modifies the DTD of every property by replacing every occurrence of "href" in the DTD with "href | response".
Top   ToC   RFC3253 - Page 30

3.8.1 Example - DAV:expand-property

This example describes how to query a version-controlled resource to determine the DAV:creator-display-name and DAV:activity-set of every version in the version history of that version-controlled resource. This example assumes that the server supports the version-history feature (see Section 5). >>REQUEST REPORT /foo.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:expand-property xmlns:D="DAV:"> <D:property name="version-history"> <D:property name="version-set"> <D:property name="creator-displayname"/> <D:property name="activity-set"/> </D:property> </D:property> </D:expand-property> >>RESPONSE HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://www.webdav.org/foo.html</D:href> <D:propstat> <D:prop> <D:version-history> <D:response> <D:href>http://repo.webdav.org/his/23</D:href> <D:propstat> <D:prop> <D:version-set> <D:response> <D:href>http://repo.webdav.org/his/23/ver/1</D:href> <D:propstat> <D:prop> <D:creator-displayname>Fred</D:creator-displayname>
Top   ToC   RFC3253 - Page 31
                             <D:activity-set> <D:href>
                               http://www.webdav.org/ws/dev/sally
                             </D:href> </D:activity-set> </D:prop>
                           <D:status>HTTP/1.1 200 OK</D:status>
                         </D:propstat> </D:response>
                       <D:response>
   <D:href>http://repo.webdav.org/his/23/ver/2</D:href>
                         <D:propstat>
                           <D:prop>
   <D:creator-displayname>Sally</D:creator-displayname>
                             <D:activity-set>
   <D:href>http://repo.webdav.org/act/add-refresh-cmd</D:href>
                             </D:activity-set> </D:prop>
                           <D:status>HTTP/1.1 200 OK</D:status>
                         </D:propstat> </D:response>
                     </D:version-set> </D:prop>
                   <D:status>HTTP/1.1 200 OK</D:status>
                 </D:propstat> </D:response>
             </D:version-history> </D:prop>
           <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat> </D:response>
     </D:multistatus>

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

3.9 Additional OPTIONS Semantics

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

3.10 Additional PUT Semantics

Additional Preconditions: (DAV:cannot-modify-version-controlled-content): If the request-URL identifies a resource with a DAV:checked-in property, the request MUST fail unless DAV:auto-version semantics will automatically check out the resource. (DAV:cannot-modify-version): If the request-URL identifies a version, the request MUST fail.
Top   ToC   RFC3253 - Page 32
      If the request creates a new resource that is automatically placed
      under version control, all preconditions for VERSION-CONTROL apply
      to the request.

   Additional Postconditions:

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

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

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

3.11 Additional PROPFIND Semantics

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

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

3.12 Additional PROPPATCH Semantics

Additional Preconditions: (DAV:cannot-modify-version-controlled-property): If the request attempts to modify a dead property, same semantics as PUT (see Section 3.10). (DAV:cannot-modify-version): If the request attempts to modify a dead property, same semantics as PUT (see Section 3.10). (DAV:cannot-modify-protected-property): An attempt to modify a property that is defined by this document, as being protected for that kind of resource, MUST fail. (DAV:supported-live-property): An attempt to modify a property defined by this document, but whose semantics are not enforced by the server, MUST fail. This helps ensure that a client will be notified when it is trying to use a property whose semantics are not supported by the server. Additional Postconditions: (DAV:auto-checkout): If the request modified a dead property, same semantics as PUT (see Section 3.10). (DAV:auto-checkout-checkin): If the request modified a dead property, same semantics as PUT (see Section 3.10).

3.13 Additional DELETE Semantics

Additional Preconditions: (DAV:no-version-delete): A server MAY fail an attempt to DELETE a version. Additional Postconditions: (DAV:update-predecessor-set): If a version was deleted, the server MUST have replaced any reference to that version in a DAV:predecessor-set by a copy of the DAV:predecessor-set of the deleted version.
Top   ToC   RFC3253 - Page 34

3.14 Additional COPY Semantics

Additional Preconditions: If the request creates a new resource that is automatically placed under version control, all preconditions for VERSION-CONTROL apply to the request. Additional Postconditions: (DAV:must-not-copy-versioning-property): A property defined by this document MUST NOT have been copied to the new resource created by this request, but instead that property of the new resource MUST have the default initial value it would have had if the new resource had been created by a non-versioning method such as PUT or a MKCOL. (DAV:auto-checkout): If the destination is a version-controlled resource, same semantics as PUT (see Section 3.10). (DAV:auto-checkout-checkin): If the destination is a version- controlled resource, same semantics as PUT (see Section 3.10). (DAV:copy-creates-new-resource): If the source of a COPY is a version-controlled resource or version, and if there is no resource at the destination of the COPY, then the COPY creates a new non-version-controlled resource at the destination of the COPY. The new resource MAY automatically be put under version control, but the resulting version-controlled resource MUST be associated with a new version history created for that new version-controlled resource, and all postconditions for VERSION-CONTROL apply to the request.

3.15 Additional MOVE Semantics

Additional Preconditions: (DAV:cannot-rename-version): If the request-URL identifies a version, the request MUST fail. Additional Postconditions: (DAV:preserve-versioning-properties): When a resource is moved from a source URL to a destination URL, a property defined by this document MUST have the same value at the destination URL as it had at the source URL.
Top   ToC   RFC3253 - Page 35

3.16 Additional UNLOCK Semantics

Note that these semantics apply both to an explicit UNLOCK request, as well as to the removal of a lock because of a lock timeout. If a precondition or postcondition cannot be satisfied, the lock timeout MUST NOT occur. Additional Preconditions: (DAV:version-history-is-tree): If the request-URL identifies a checked-out version-controlled resource that will be automatically checked in when the lock is removed, then the versions identified by the DAV:predecessor-set of the checked-out resource MUST be descendants of the root version of the version history for the DAV:checked-out version. Additional Postconditions: (DAV:auto-checkin): If the request-URL identified a checked-out version-controlled resource that had been automatically checked out because of its DAV:auto-version property, the request MUST have created a new version in the version history of the DAV:checked-out version. The request MUST have allocated a URL for the version that MUST NOT have previously identified any other resource, and MUST NOT ever identify a resource other than this version. The content, dead properties, DAV:resourcetype, and DAV:predecessor-set of the new version MUST be copied from the checked-out resource. The DAV:version-name of the new version MUST be set to a server-defined value distinct from all other DAV:version-name values of other versions in the same version history. The request MUST have removed the DAV:checked-out property of the version-controlled resource, and MUST have added a DAV:checked-in property that identifies the new version.

4 CHECKOUT-IN-PLACE FEATURE

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

4.1 Additional Version Properties

The checkout-in-place feature introduces the following REQUIRED properties for a version.
Top   ToC   RFC3253 - Page 36

4.1.1 DAV:checkout-fork

This property controls the behavior of CHECKOUT when a version already is checked out or has a successor. If the DAV:checkout-fork of a version is DAV:forbidden, a CHECKOUT request MUST fail if it would result in that version appearing in the DAV:predecessor-set or DAV:checked-out property of more than one version or checked-out resource. If DAV:checkout-fork is DAV:discouraged, such a CHECKOUT request MUST fail unless DAV:fork-ok is specified in the CHECKOUT request body. A server MAY reject attempts to modify the DAV:checkout-fork of a version. <!ELEMENT checkout-fork ANY> ANY value: A sequence of elements with at most one DAV:discouraged or DAV:forbidden element. <!ELEMENT discouraged EMPTY> <!ELEMENT forbidden EMPTY>

4.1.2 DAV:checkin-fork

This property controls the behavior of CHECKIN when a version already has a successor. If the DAV:checkin-fork of a version is DAV:forbidden, a CHECKIN request MUST fail if it would result in that version appearing in the DAV:predecessor-set of more than one version. If DAV:checkin-fork is DAV:discouraged, such a CHECKIN request MUST fail unless DAV:fork-ok is specified in the CHECKIN request body. A server MAY reject attempts to modify the DAV:checkout-fork of a version. <!ELEMENT checkin-fork ANY> ANY value: A sequence of elements with at most one DAV:discouraged or DAV:forbidden element. <!ELEMENT discouraged EMPTY> <!ELEMENT forbidden EMPTY>

4.2 Checked-Out Resource Properties

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

4.2.1 DAV:checkout-fork

This property determines the DAV:checkout-fork property of the version that results from checking in this resource.
Top   ToC   RFC3253 - Page 37

4.2.2 DAV:checkin-fork

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

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

A CHECKOUT request can be applied to a checked-in version-controlled resource to allow modifications to the content and dead properties of that version-controlled resource. If a CHECKOUT request fails, the server state preceding the request MUST be restored. Marshalling: If a request body is included, it MUST be a DAV:checkout XML element. <!ELEMENT checkout ANY> ANY value: A sequence of elements with at most one DAV:fork-ok element. <!ELEMENT fork-ok EMPTY> If a response body for a successful request is included, it MUST be a DAV:checkout-response XML element. <!ELEMENT checkout-response ANY> The response MUST include a Cache-Control:no-cache header. Preconditions: (DAV:must-be-checked-in): If a version-controlled resource is being checked out, it MUST have a DAV:checked-in property. (DAV:checkout-of-version-with-descendant-is-forbidden): If the DAV:checkout-fork property of the version being checked out is DAV:forbidden, the request MUST fail if a version identifies that version in its DAV:predecessor-set. (DAV:checkout-of-version-with-descendant-is-discouraged): If the DAV:checkout-fork property of the version being checked out is DAV:discouraged, the request MUST fail if a version identifies that version in its DAV:predecessor-set unless DAV:fork-ok is specified in the request body.
Top   ToC   RFC3253 - Page 38
      (DAV:checkout-of-checked-out-version-is-forbidden): If the
      DAV:checkout-fork property of the version being checked out is
      DAV:forbidden, the request MUST fail if a checked-out resource
      identifies that version in its DAV:checked-out property.

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

   Postconditions:

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

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

4.3.1 Example - CHECKOUT of a version-controlled resource

>>REQUEST CHECKOUT /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 200 OK Cache-Control: no-cache In this example, the version-controlled resource /foo.html is checked out.

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

A CHECKIN request can be applied to a checked-out version-controlled resource to produce a new version whose content and dead properties are copied from the checked-out resource. If a CHECKIN request fails, the server state preceding the request MUST be restored.
Top   ToC   RFC3253 - Page 39
   Marshalling:

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

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

      <!ELEMENT keep-checked-out EMPTY>
      <!ELEMENT fork-ok EMPTY>

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

      <!ELEMENT checkin-response ANY>

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

   Preconditions:

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

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

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

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

   Postconditions:

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

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

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

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

4.4.1 Example - CHECKIN

>>REQUEST CHECKIN /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 201 Created Location: http://repo.webdav.org/his/23/ver/32 Cache-Control: no-cache In this example, version-controlled resource /foo.html is checked in, and a new version is created at http://repo.webdav.org/his/23/ver/32.

4.5 UNCHECKOUT Method

An UNCHECKOUT request can be applied to a checked-out version- controlled resource to cancel the CHECKOUT and restore the pre- CHECKOUT state of the version-controlled resource. If an UNCHECKOUT request fails, the server MUST undo any partial effects of the UNCHECKOUT request.
Top   ToC   RFC3253 - Page 41
   Marshalling:

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

      <!ELEMENT uncheckout ANY>

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

      <!ELEMENT uncheckout-response ANY>

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

   Preconditions:

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

   Postconditions:

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

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

4.5.1 Example - UNCHECKOUT

>>REQUEST UNCHECKOUT /foo.html HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 200 OK Cache-Control: no-cache In this example, the content and dead properties of the version- controlled resource identified by http://www.webdav.org/foo.html are restored to their values preceding the most recent CHECKOUT of that version-controlled resource.
Top   ToC   RFC3253 - Page 42

4.6 Additional OPTIONS Semantics

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

5 Version-History Feature

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

5.1 Version History Properties

The DAV:resourcetype of a version history MUST be DAV:version- history. The version-history feature introduces the following REQUIRED properties for a version history.

5.1.1 DAV:version-set (protected)

This property identifies each version of this version history. <!ELEMENT version-set (href+)>

5.1.2 DAV:root-version (computed)

This property identifies the root version of this version history. <!ELEMENT root-version (href)>

5.2 Additional Version-Controlled Resource Properties

The version-history feature introduces the following REQUIRED property for a version-controlled resource.
Top   ToC   RFC3253 - Page 43

5.2.1 DAV:version-history (computed)

This property identifies the version history resource for the DAV:checked-in or DAV:checked-out version of this version-controlled resource. <!ELEMENT version-history (href)>

5.3 Additional Version Properties

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

5.3.1 DAV:version-history (computed)

This property identifies the version history that contains this version. <!ELEMENT version-history (href)>

5.4 DAV:locate-by-history Report

Many properties identify a version from some version history. It is often useful to be able to efficiently locate a version-controlled resource for that version history. The DAV:locate-by-history report can be applied to a collection to locate the collection member that is a version-controlled resource for a specified version history resource. Marshalling: The request body MUST be a DAV:locate-by-history XML element. <!ELEMENT locate-by-history (version-history-set, prop)> <!ELEMENT version-history-set (href+)> prop: see RFC 2518, Section 12.11 The response body for a successful request MUST be a DAV:multistatus XML element containing every version-controlled resource that is a member of the collection identified by the request-URL, and whose DAV:version-history property identifies one of the version history resources identified by the request body. The DAV:prop element in the request body identifies which properties should be reported in the DAV:prop elements in the response body.
Top   ToC   RFC3253 - Page 44
   Preconditions:

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

5.4.1 Example - DAV:locate-by-history Report

>>REQUEST REPORT /ws/public HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:locate-by-history xmlns:D="DAV:"> <D:version-history-set> <D:href>http://repo.webdav.org/his/23</D:href> <D:href>http://repo.webdav.org/his/84</D:href> <D:href>http://repo.webdav.org/his/129</D:href> <D:version-history-set/> <D:prop> </D:version-history> </D:prop> </D:locate-by-history> >>RESPONSE HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://www.webdav.org/ws/public/x/test.html</D:href> <D:propstat> <D:prop> <D:version-history> <D:href>http://repo.webdav.org/his/23</D:href> </D:version-history> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> </D:multistatus>
Top   ToC   RFC3253 - Page 45
   In this example, there is only one version-controlled member of
   /ws/public that is a version-controlled resource for one of the three
   specified version history resources.  In particular,
   /ws/public/x/test.html is the version-controlled resource for
   http://repo.webdav.org/his/23.

5.5 Additional OPTIONS Semantics

If the server supports the version-history feature, it MUST include "version-history" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods. A DAV:version-history-collection-set element MAY be included in the request body to identify collections that may contain version history resources. Additional Marshalling: If an XML request body is included, it MUST be a DAV:options XML element. <!ELEMENT options ANY> ANY value: A sequence of elements with at most one DAV:version-history-collection-set element. If an XML response body for a successful request is included, it MUST be a DAV:options-response XML element. <!ELEMENT options-response ANY> ANY value: A sequence of elements with at most one DAV:version-history-collection-set element. <!ELEMENT version-history-collection-set (href*)> If DAV:version-history-collection-set is included in the request body, the response body for a successful request MUST contain a DAV:version-history-collection-set element identifying collections that may contain version histories. An identified collection MAY be the root collection of a tree of collections, all of which may contain version histories. Since different servers can control different parts of the URL namespace, different resources on the same host MAY have different DAV:version-history-collection-set values. The identified collections MAY be located on different hosts from the resource.
Top   ToC   RFC3253 - Page 46

5.6 Additional DELETE Semantics

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

5.7 Additional COPY Semantics

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

5.8 Additional MOVE Semantics

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

5.9 Additional VERSION-CONTROL Semantics

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

5.10 Additional CHECKIN Semantics

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

6 Workspace Feature

In order to allow multiple users to work concurrently on adding versions to the same version history, it is necessary to allocate on the server multiple checked-out resources for the same version history. Even if only one user is making changes to a resource, that user will sometimes wish to create a "private" version, and then to expose that version at a later time. One way to provide this functionality depends on the client keeping track of its current set of checked-out resources. This is the working-resource feature defined in Section 8. The other way to provide this functionality avoids the need for persistent state on the client, and instead has the server maintain a human meaningful namespace for related sets of checked-out resources. This is the workspace feature defined in this section. The workspace feature introduces a "workspace resource". A workspace resource is a collection whose members are related version-controlled and non-version-controlled resources. Multiple workspaces may be used to expose different versions and configurations of a set of version-controlled resources concurrently. In order to make changes to a version-controlled resource in one workspace visible in another workspace, that version-controlled resource must be checked in, and then the corresponding version-controlled resource in the other workspace can be updated to display the content and dead properties of the new version. In order to ensure unambiguous merging (see Section 11) and baselining (see Section 12) semantics, a workspace may contain at most one version-controlled resource for a given version history. This is required for unambiguous merging because the MERGE method must identify which version-controlled resource is to be the merge target of a given version. This is required for unambiguous baselining because a baseline can only select one version for a given version-controlled resource. Initially, an empty workspace can be created. Non-version-controlled resources can then be added to the workspace with standard WebDAV requests such as PUT and MKCOL. Version-controlled resources can be added to the workspace with VERSION-CONTROL requests. If the
Top   ToC   RFC3253 - Page 48
   baseline feature is supported, collections in the workspace can be
   placed under baseline control, and then initialized by existing
   baselines.

6.1 Workspace Properties

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

6.1.1 DAV:workspace-checkout-set (computed)

This property identifies each checked-out resource whose DAV:workspace property identifies this workspace. <!ELEMENT workspace-checkout-set (href*)>

6.2 Additional Resource Properties

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

6.2.1 DAV:workspace (protected)

The DAV:workspace property of a workspace resource MUST identify itself. The DAV:workspace property of any other type of resource MUST be the same as the DAV:workspace of its parent collection. <!ELEMENT workspace (href)>

6.3 MKWORKSPACE Method

A MKWORKSPACE request creates a new workspace resource. A server MAY restrict workspace creation to particular collections, but a client can determine the location of these collections from a DAV:workspace-collection-set OPTIONS request (see Section 6.4). If a MKWORKSPACE request fails, the server state preceding the request MUST be restored. Marshalling: If a request body is included, it MUST be a DAV:mkworkspace XML element. <!ELEMENT mkworkspace ANY> If a response body for a successful request is included, it MUST be a DAV:mkworkspace-response XML element.
Top   ToC   RFC3253 - Page 49
      <!ELEMENT mkworkspace-response ANY>

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

   Preconditions:

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

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

   Postconditions:

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

6.3.1 Example - MKWORKSPACE

>>REQUEST MKWORKSPACE /ws/public HTTP/1.1 Host: www.webdav.org Content-Length: 0 >>RESPONSE HTTP/1.1 201 Created Cache-Control: no-cache In this example, a new workspace is created at http://www.webdav.org/ws/public.

6.4 Additional OPTIONS Semantics

If a server supports the workspace feature, it MUST include "workspace" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods. If a server supports the workspace feature, it MUST also support the checkout-in-place feature and the version-history feature. A DAV:workspace-collection-set element MAY be included in the request body to identify collections that may contain workspace resources.
Top   ToC   RFC3253 - Page 50
   Additional Marshalling:

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

      <!ELEMENT options ANY>
      ANY value: A sequence of elements with at most one
      DAV:workspace-collection-set element.

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

      <!ELEMENT options-response ANY>
      ANY value: A sequence of elements with at most one
      DAV:workspace-collection-set element.

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

      If DAV:workspace-collection-set is included in the request body,
      the response body for a successful request MUST contain a
      DAV:workspace-collection-set element identifying collections that
      may contain workspaces.  An identified collection MAY be the root
      collection of a tree of collections, all of which may contain
      workspaces.  Since different servers can control different parts
      of the URL namespace, different resources on the same host MAY
      have different DAV:workspace-collection-set values.  The
      identified collections MAY be located on different hosts from the
      resource.
Top   ToC   RFC3253 - Page 51

6.4.1 Example - OPTIONS

>>REQUEST OPTIONS /doc HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:options xmlns:D="DAV:"> <D:version-history-collection-set/> <D:workspace-collection-set/> </D:options> >>RESPONSE HTTP/1.1 200 OK DAV: 1 DAV: version-control,checkout-in-place,version-history,workspace Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:options-response xmlns:D="DAV:"> <D:version-history-collection-set> <D:href>http://repo.webdav.org/his</D:href> </D:version-history-collection-set> <D:workspace-collection-set> <D:href>http://www.webdav.org/public/ws</D:href> <D:href>http://www.webdav.org/private/ws</D:href> </D:workspace-collection-set> </D:options-response> In this example, the server indicates that it provides Class 1 DAV support and basic-server-workspace versioning support. In addition, the server indicates the requested locations of the version history resources and the workspace resources.

6.5 Additional DELETE Semantics

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


(next page on part 3)

Next Section