Vendor the RFCs the server implements
Six specs govern the wire format, and checking any claim about it meant re-downloading them. 708K of Standards Track text, unmodified. Assisted-by: Claude Opus 5 via Claude Code
diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md
new file mode 100644
index 0000000..0ba215d
--- /dev/null
+++ b/docs/rfcs/README.md
@@ -0,0 +1,26 @@
+# Vendored RFCs
+
+The specifications this server implements, kept here so the code's
+citations can be checked offline and so section numbers stay pinned to
+the text they were verified against.
+
+`lib/pro_tacts/web.rb` cites these by number and section next to the
+handler that implements each one.
+
+| RFC | Title | What it governs here |
+| --- | --- | --- |
+| [4918](rfc4918.txt) | HTTP Extensions for Distributed Authoring (WebDAV) | PROPFIND, the Depth header, 207 multistatus bodies, `DAV:getetag` |
+| [6352](rfc6352.txt) | vCard Extensions to WebDAV (CardDAV) | Address book collections, `addressbook-home-set`, multiget, `address-data` |
+| [6578](rfc6578.txt) | Collection Synchronization for WebDAV | The `sync-collection` report and `sync-token` |
+| [6764](rfc6764.txt) | Locating Services for CalDAV and CardDAV | The `/.well-known/carddav` bootstrap and its redirect |
+| [5397](rfc5397.txt) | WebDAV Current Principal Extension | `current-user-principal` |
+| [3253](rfc3253.txt) | Versioning Extensions to WebDAV (DeltaV) | `supported-report-set` only; no versioning is implemented |
+
+One property the server sends has no RFC. `getctag` is an Apple
+CalendarServer extension in the `http://calendarserver.org/ns/`
+namespace, and it is served because macOS Contacts polls it. RFC 6578's
+`sync-token` is the standardized equivalent.
+
+Fetch a copy with `curl -O https://www.rfc-editor.org/rfc/rfc6352.txt`,
+substituting the number. These are the published Standards Track texts,
+unmodified.
diff --git a/docs/rfcs/rfc3253.txt b/docs/rfcs/rfc3253.txt
new file mode 100644
index 0000000..4e18dfd
--- /dev/null
+++ b/docs/rfcs/rfc3253.txt
@@ -0,0 +1,6611 @@
+
+
+
+
+
+
+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
+
+
+
+Clemm, et al. Standards Track [Page 1]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+Clemm, et al. Standards Track [Page 2]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+Clemm, et al. Standards Track [Page 3]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+Clemm, et al. Standards Track [Page 4]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+Clemm, et al. Standards Track [Page 5]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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:
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 6]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ - 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.
+
+
+
+
+Clemm, et al. Standards Track [Page 7]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+Clemm, et al. Standards Track [Page 8]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+Clemm, et al. Standards Track [Page 9]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 10]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+Clemm, et al. Standards Track [Page 11]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+Clemm, et al. Standards Track [Page 12]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+Clemm, et al. Standards Track [Page 13]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+
+
+Clemm, et al. Standards Track [Page 14]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 15]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+Clemm, et al. Standards Track [Page 16]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+Clemm, et al. Standards Track [Page 17]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 18]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+Clemm, et al. Standards Track [Page 19]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ To allow a client to query the properties of all versions in the
+ version history of a specified version-controlled resource, basic
+ versioning provides the DAV:version-tree report (see Section 3.7). A
+ more powerful version history reporting mechanism is provided by
+ applying the DAV:expand-property report (see Section 3.8) to a
+ version history resource (see Section 5).
+
+3 Version-Control Feature
+
+ The version-control feature provides support for putting a resource
+ under version control, creating an associated version-controlled
+ resource and version history resource as described in Section 2.2.1.
+ A server indicates that it supports the version-control feature by
+ including the string "version-control" as a field in the DAV header
+ in the response to an OPTIONS request. The version-control feature
+ MUST be supported if any other versioning feature is supported.
+
+3.1 Additional Resource Properties
+
+ The version-control feature introduces the following REQUIRED
+ properties for any WebDAV resource.
+
+3.1.1 DAV:comment
+
+ This property is used to track a brief comment about a resource that
+ is suitable for presentation to a user. The DAV:comment of a version
+ can be used to indicate why that version was created.
+
+ <!ELEMENT comment (#PCDATA)>
+ PCDATA value: string
+
+3.1.2 DAV:creator-displayname
+
+ This property contains a description of the creator of the resource
+ that is suitable for presentation to a user. The DAV:creator-
+ displayname of a version can be used to indicate who created that
+ version.
+
+ <!ELEMENT creator-displayname (#PCDATA)>
+ PCDATA value: string
+
+3.1.3 DAV:supported-method-set (protected)
+
+ This property identifies the methods that are supported by the
+ resource. A method is supported by a resource if there is some state
+ of that resource for which an application of that method will
+
+
+
+
+
+Clemm, et al. Standards Track [Page 20]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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)>
+
+
+
+
+Clemm, et al. Standards Track [Page 21]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 22]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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*)>
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 23]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 24]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 25]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+
+Clemm, et al. Standards Track [Page 26]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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>
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 27]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ >>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>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 28]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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".
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 29]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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>
+
+
+
+Clemm, et al. Standards Track [Page 30]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <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.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 31]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 32]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+Clemm, et al. Standards Track [Page 33]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 34]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+Clemm, et al. Standards Track [Page 35]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+Clemm, et al. Standards Track [Page 36]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+Clemm, et al. Standards Track [Page 37]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (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.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 38]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 39]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 40]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+Clemm, et al. Standards Track [Page 41]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 42]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 43]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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>
+
+
+
+
+Clemm, et al. Standards Track [Page 44]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 45]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 46]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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
+
+
+
+Clemm, et al. Standards Track [Page 47]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+Clemm, et al. Standards Track [Page 48]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!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.
+
+
+
+
+Clemm, et al. Standards Track [Page 49]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 50]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+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.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 51]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+6.6 Additional MOVE Semantics
+
+ Additional Postconditions:
+
+ (DAV:workspace-member-moved): If the request-URL did not identify
+ a workspace, the DAV:workspace of the destination MUST have been
+ updated to have the same value as the DAV:workspace of the parent
+ collection of the destination.
+
+ (DAV:workspace-moved): If the request-URL identified a workspace,
+ any reference to that workspace in a DAV:workspace property MUST
+ have been updated to refer to the new location of that workspace.
+
+6.7 Additional VERSION-CONTROL Semantics
+
+ A VERSION-CONTROL request can be used to create a new version-
+ controlled resource for an existing version history. This allows the
+ creation of version-controlled resources for the same version history
+ in multiple workspaces.
+
+ Additional Marshalling:
+
+ <!ELEMENT version-control ANY>
+ ANY value: A sequence of elements with at most one DAV:version
+ element.
+
+ <!ELEMENT version (href)>
+
+ Additional Preconditions:
+
+ (DAV:cannot-add-to-existing-history): If the DAV:version-control
+ request body element contains a DAV:version element, the request-
+ URL MUST NOT identify a resource.
+
+ (DAV:must-be-version): The DAV:href of the DAV:version element
+ MUST identify a version.
+
+ (DAV:one-version-controlled-resource-per-history-per-workspace):
+ If the DAV:version-control request body specifies a version, and
+ if the request-URL is a member of a workspace, then there MUST NOT
+ already be a version-controlled member of that workspace whose
+ DAV:checked-in or DAV:checked-out property identifies any version
+ from the version history of the version specified in the request
+ body.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 52]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Postconditions:
+
+ (DAV:new-version-controlled-resource): If the request-URL did NOT
+ identify a resource, a new version-controlled resource exists at
+ the request-URL whose content and dead properties are initialized
+ by those of the version in the request body, and whose
+ DAV:checked-in property identifies that version.
+
+6.7.1 Example - VERSION-CONTROL (using an existing version history)
+
+ >>REQUEST
+
+ VERSION-CONTROL /ws/public/bar.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:version-control xmlns:D="DAV:">
+ <D:version>
+ <D:href>http://repo.webdav.org/his/12/ver/V3</D:href>
+ </D:version>
+ </D:version-control>
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Cache-Control: no-cache
+
+ In this example, a new version-controlled resource is created at
+ /ws/public/bar.html. The content and dead properties of the new
+ version-controlled resource are initialized to be the same as those
+ of the version identified by http://repo.webdav.org/his/12/ver/V3.
+
+7 UPDATE Feature
+
+ The update feature provides a mechanism for changing the state of a
+ checked-in version-controlled resource to be that of another version
+ from the version history of that resource.
+
+7.1 UPDATE Method
+
+ The UPDATE method modifies the content and dead properties of a
+ checked-in version-controlled resource (the "update target") to be
+ those of a specified version (the "update source") from the version
+ history of that version-controlled resource.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 53]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The response to an UPDATE request identifies the resources modified
+ by the request, so that a client can efficiently update any cached
+ state it is maintaining. Extensions to the UPDATE method allow
+ multiple resources to be modified from a single UPDATE request (see
+ Section 12.13).
+
+ Marshalling:
+
+ The request body MUST be a DAV:update element.
+
+ <!ELEMENT update ANY>
+ ANY value: A sequence of elements with at most one DAV:version
+ element and at most one DAV:prop element.
+ <!ELEMENT version (href)>
+ prop: see RFC 2518, Section 12.11
+
+ The response for a successful request MUST be a 207 Multi-Status,
+ where the DAV:multistatus XML element in the response body
+ identifies all resources that have been modified by the request.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Postconditions:
+
+ (DAV:update-content-and-properties): If the DAV:version element in
+ the request body identified a version that is in the same version
+ history as the DAV:checked-in version of a version-controlled
+ resource identified by the request-URL, then the content and dead
+ properties of that version-controlled resource MUST be the same as
+ those of the version specified by the DAV:version element, and the
+ DAV:checked-in property of the version-controlled resource MUST
+ identify that version. The request-URL MUST appear in a
+ DAV:response element in the response body.
+
+ (DAV:report-properties): If DAV:prop is specified in the request
+ body, the properties specified in the DAV:prop element MUST be
+ reported in the DAV:response elements in the response body.
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 54]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+7.1.1 Example - UPDATE
+
+ >>REQUEST
+
+ UPDATE /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:update xmlns:D="DAV:">
+ <D:version>
+ <D:href>http://repo.webdav.org/his/23/ver/33</D:href>
+ </D:version>
+ </D:update>
+
+ >>RESPONSE
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Cache-Control: no-cache
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.webdav.org/foo.html</D:href>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:response>
+
+ In this example, the content and dead properties of
+ http://repo.webdav.org/his/23/ver/33 are copied to the version-
+ controlled resource /foo.html, and the DAV:checked-in property of
+ /foo.html is updated to refer to
+ http://repo.webdav.org/his/23/ver/33.
+
+7.2 Additional OPTIONS Semantics
+
+ If the server supports the update feature, it MUST include "update"
+ as a field in the DAV response header from an OPTIONS request on any
+ resource that supports any versioning properties, reports, or
+ methods.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 55]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+8 Label Feature
+
+ A version "label" is a string that distinguishes one version in a
+ version history from all other versions in that version history. A
+ label can automatically be assigned by a server, or it can be
+ assigned by a client in order to provide a meaningful name for that
+ version. A given version label can be assigned to at most one
+ version of a given version history, but client assigned labels can be
+ reassigned to another version at any time. Note that although a
+ given label can be applied to at most one version from the same
+ version history, the same label can be applied to versions from
+ different version histories.
+
+ For certain methods, if the request-URL identifies a version-
+ controlled resource, a label can be specified in a Label request
+ header (see Section 8.3) to cause the method to be applied to the
+ version selected by that label from the version history of that
+ version-controlled resource.
+
+8.1 Additional Version Properties
+
+ The label feature introduces the following REQUIRED property for a
+ version.
+
+8.1.1 DAV:label-name-set (protected)
+
+ This property contains the labels that currently select this version.
+
+ <!ELEMENT label-name-set (label-name*)>
+ <!ELEMENT label-name (#PCDATA)>
+ PCDATA value: string
+
+8.2 LABEL Method
+
+ A LABEL request can be applied to a version to modify the labels that
+ select that version. The case of a label name MUST be preserved when
+ it is stored and retrieved. When comparing two label names to decide
+ if they match or not, a server SHOULD use a case-sensitive URL-
+ escaped UTF-8 encoded comparison of the two label names.
+
+ If a LABEL request is applied to a checked in version-controlled
+ resource, the operation MUST be applied to the DAV:checked-in version
+ of that version-controlled resource.
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 56]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Marshalling:
+
+ The request body MUST be a DAV:label element.
+
+ <!ELEMENT label ANY>
+ ANY value: A sequence of elements with at most one DAV:add,
+ DAV:set, or DAV:remove element.
+
+ <!ELEMENT add (label-name)>
+ <!ELEMENT set (label-name)>
+ <!ELEMENT remove (label-name)>
+ <!ELEMENT label-name (#PCDATA)>
+ PCDATA value: string
+
+ The request MAY include a Label header.
+
+ The request MAY include a Depth header. If no Depth header is
+ included, Depth:0 is assumed. Standard depth semantics apply, and
+ the request is applied to the collection identified by the
+ request-URL and to all members of the collection that satisfy the
+ Depth value. If a Depth header is included and the request fails
+ on any resource, the response MUST be a 207 Multi-Status that
+ identifies all resources for which the request has failed.
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:label-response XML element.
+
+ <!ELEMENT label-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:must-be-checked-in): If the request-URL identifies a
+ version-controlled resource, the version-controlled resource MUST
+ be checked in.
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ (DAV:add-must-be-new-label): If DAV:add is specified in the
+ request body, the specified label MUST NOT appear in the
+ DAV:label-name-set of any version in the version history of that
+ version-controlled resource.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 57]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:label-must-exist): If DAV:remove is specified in the request
+ body, the specified label MUST appear in the DAV:label-name-set of
+ that version.
+
+ Postconditions:
+
+ (DAV:add-or-set-label): If DAV:add or DAV:set is specified in the
+ request body, the specified label MUST appear in the DAV:label-
+ name-set of the specified version, and MUST NOT appear in the
+ DAV:label-name-set of any other version in the version history of
+ that version.
+
+ (DAV:remove-label): If DAV:remove is specified in the request
+ body, the specified label MUST NOT appear in the DAV:label-name-
+ set of any version in the version history of that version.
+
+8.2.1 Example - Setting a label
+
+ >>REQUEST
+
+ LABEL /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:label xmlns:D="DAV:">
+ <D:set>
+ <D:label-name>default</D:label-name>
+ </D:set>
+ </D:label>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Cache-Control: no-cache
+
+ In this example, the label "default" is applied to the DAV:checked-in
+ version of /foo.html.
+
+8.3 Label Header
+
+ For certain methods (e.g. GET, PROPFIND), if the request-URL
+ identifies a version-controlled resource, a label can be specified in
+ a Label request header to cause the method to be applied to the
+ version selected by that label from the version history of that
+ version-controlled resource.
+
+
+
+
+Clemm, et al. Standards Track [Page 58]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The value of a label header is the name of a label, encoded using
+ URL-escaped UTF-8. For example, the label "release B.3" is
+ identified by the following header:
+
+ Label: release%20B.3
+
+ A Label header MUST have no effect on a request whose request-URL
+ does not identify a version-controlled resource. In particular, it
+ MUST have no effect on a request whose request-URL identifies a
+ version or a version history.
+
+ A server MUST return an HTTP-1.1 Vary header containing Label in a
+ successful response to a cacheable request (e.g., GET) that includes
+ a Label header.
+
+8.4 Additional OPTIONS Semantics
+
+ If the server supports the label feature, it MUST include "label" as
+ a field in the DAV response header from an OPTIONS request on any
+ resource that supports any versioning properties, reports, or
+ methods.
+
+8.5 Additional GET Semantics
+
+ Additional Marshalling:
+
+ The request MAY include a Label header.
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If the request-URL
+ identifies a version-controlled resource and a Label request
+ header is included, the response MUST contain the content of the
+ specified version rather than that of the version-controlled
+ resource.
+
+8.6 Additional PROPFIND Semantics
+
+ Additional Marshalling:
+
+ The request MAY include a Label header.
+
+
+
+Clemm, et al. Standards Track [Page 59]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If the request-URL
+ identifies a version-controlled resource and a Label request
+ header is included, the response MUST contain the properties of
+ the specified version rather than that of the version-controlled
+ resource.
+
+8.7 Additional COPY Semantics
+
+ Additional Marshalling:
+
+ The request MAY include a Label header.
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If the request-URL
+ identifies a version-controlled resource and a Label request
+ header is included, the request MUST have copied the properties
+ and content of the specified version rather than that of the
+ version-controlled resource.
+
+8.8 Additional CHECKOUT Semantics
+
+ If the server supports the working-resource option, a LABEL header
+ may be included to check out the version selected by the specified
+ label.
+
+ Additional Marshalling:
+
+ The request MAY include a Label header.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 60]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ (DAV:must-not-have-label-and-apply-to-version): If a Label request
+ header is included, the request body MUST NOT contain a
+ DAV:apply-to-version element.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If the request-URL
+ identifies a checked-in version-controlled resource, and a Label
+ request header is included, the CHECKOUT MUST have been applied to
+ the version selected by the specified label, and not to the
+ version-controlled resource itself.
+
+8.9 Additional UPDATE Semantics
+
+ If the request body of an UPDATE request contains a DAV:label-name
+ element, the update target is the resource identified by the
+ request-URL, and the update source is the version selected by the
+ specified label from the version history of the update target.
+
+ Additional Marshalling:
+
+ <!ELEMENT update ANY>
+ ANY value: A sequence of elements with at most one DAV:label-name
+ or DAV:version element (but not both).
+ <!ELEMENT label-name (#PCDATA)>
+ PCDATA value: string
+
+ The request MAY include a Depth header. If no Depth header is
+ included, Depth:0 is assumed. Standard depth semantics apply, and
+ the request is applied to the collection identified by the
+ request-URL and to all members of the collection that satisfy the
+ Depth value. If a Depth header is included and the request fails
+ on any resource, the response MUST be a 207 Multi-Status that
+ identifies all resources for which the request has failed.
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If the request includes a
+ DAV:label-name element in the request body, the label MUST select
+ a version in the version history of the version-controlled
+ resource identified by the request-URL.
+
+
+
+Clemm, et al. Standards Track [Page 61]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:depth-update): If the request includes a Depth header,
+ standard depth semantics apply, and the request is applied to the
+ collection identified by the request-URL and to all members of the
+ collection that satisfy the Depth value. The request MUST be
+ applied to a collection before being applied to any members of
+ that collection, since an update of a version-controlled
+ collection might change the membership of that collection.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If a DAV:label-name
+ element appears in the request body, the content and dead
+ properties of the version-controlled resource must have been
+ updated to be those of the version selected by that label.
+
+9 Working-Resource Feature
+
+ The working-resource feature provides an alternative to the workspace
+ feature for supporting parallel development. Unlike the workspace
+ feature, where the desired configuration of versions and checked-out
+ resources is maintained on the server, the working-resource feature
+ maintains the configuration on the client. This simplifies the
+ server implementation, but does not allow a user to access the
+ configuration from clients in different physical locations, such as
+ from another office, from home, or while traveling. Another
+ difference is that the workspace feature isolates clients from a
+ logical change that involves renaming shared resources, until that
+ logical change is complete and tested; with the working resource
+ feature, all clients use a common set of shared version-controlled
+ resources and every client sees the result of a MOVE as soon as it
+ occurs.
+
+ If a server supports the working-resource feature but not the
+ checkout-in-place feature, a CHECKOUT request can only be used to
+ create a working resource, and cannot be used to check out a
+ version-controlled resource. If a server supports the checkout-in-
+ place feature, but not the working-resource feature, a CHECKOUT can
+ only be used to change the state of a version-controlled resource
+ from checked-in to checked-out.
+
+9.1 Additional Version Properties
+
+ The working-resource feature introduces the following REQUIRED
+ properties for a version.
+
+9.1.1 DAV:checkout-fork
+
+ This property is defined in Section 4.1.1.
+
+
+
+Clemm, et al. Standards Track [Page 62]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+9.1.2 DAV:checkin-fork
+
+ This property is defined in Section 4.1.2.
+
+9.2 Working Resource Properties
+
+ The working-resource feature introduces the following REQUIRED
+ properties for a working resource. Since a working resource is a
+ checked-out resource, it also has any property defined in this
+ document for a checked-out resource.
+
+9.2.1 DAV:auto-update (protected)
+
+ This property identifies the version-controlled resource that will be
+ updated when the working resource is checked in.
+
+ <!ELEMENT auto-update (href)>
+
+9.2.2 DAV:checkout-fork
+
+ This property is defined in Section 4.2.1.
+
+9.2.3 DAV:checkin-fork
+
+ This property is defined in Section 4.2.2.
+
+9.3 CHECKOUT Method (applied to a version)
+
+ A CHECKOUT request can be applied to a version to create a new
+ working resource. The content and dead properties of the working
+ resource are a copy of the version that was checked out.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:checkout XML
+ element.
+
+ <!ELEMENT checkout ANY>
+
+ ANY value: A sequence of elements with at most one DAV:apply-to-
+ version and at most one DAV:fork-ok element.
+
+ <!ELEMENT apply-to-version EMPTY>
+ <!ELEMENT fork-ok EMPTY>
+
+ If a response body for a successful request is included,
+ it MUST be a DAV:checkout-response XML element.
+
+
+
+
+Clemm, et al. Standards Track [Page 63]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT checkout-response ANY>
+
+ The response MUST include a Location header.
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:checkout-of-version-with-descendant-is-forbidden): See
+ Section 4.3.
+
+ (DAV:checkout-of-version-with-descendant-is-discouraged): See
+ Section 4.3.
+
+ (DAV:checkout-of-checked-out-version-is-forbidden): See Section
+ 4.3.
+
+ (DAV:checkout-of-checked-out-version-is-discouraged): See Section
+ 4.3.
+
+ Postconditions:
+
+ (DAV:create-working-resource): If the request-URL identified a
+ version, the Location response header MUST contain the URL of a
+ new working resource. The DAV:checked-out property of the new
+ working resource MUST identify the version that was checked out.
+ The content and dead properties of the working resource MUST be
+ copies of the content and dead properties of the DAV:checked-out
+ version. The DAV:predecessor-set property of the working resource
+ MUST be initialized to be the version identified by the request-
+ URL. The DAV:auto-update property of the working resource MUST
+ NOT exist.
+
+ (DAV:create-working-resource-from-checked-in-version): If the
+ request-URL identified a version-controlled resource, and
+ DAV:apply-to-version is specified in the request body, the
+ CHECKOUT is applied to the DAV:checked-in version of the version-
+ controlled resource, and not the version-controlled resource
+ itself. A new working resource is created and the version-
+ controlled resource remains checked-in. The DAV:auto-update
+ property of the working resource MUST identify the version-
+ controlled resource.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 64]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+9.3.1 Example - CHECKOUT of a version
+
+ >>REQUEST
+
+ CHECKOUT /his/12/ver/V3 HTTP/1.1
+ Host: repo.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Location: http://repo.webdav.org/wr/157
+ Cache-Control: no-cache
+
+ In this example, the version identified by
+ http://repo.webdav.org/his/12/ver/V3 is checked out, and the new
+ working resource is located at http://repo.webdav.org/wr/157.
+
+9.4 CHECKIN Method (applied to a working resource)
+
+ A CHECKIN request can be applied to a working resource to produce a
+ new version whose content and dead properties are a copy of those of
+ the working resource. If the DAV:auto-update property of the working
+ resource was set because the working resource was created by applying
+ a CHECKOUT with the DAV:apply-to-version flag to a version-controlled
+ resource, the CHECKIN request will also update the content and dead
+ properties of that version-controlled resource to be those of the new
+ version.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:checkin XML
+ element.
+
+ <!ELEMENT checkin ANY>
+ ANY value: A sequence of elements with at most one DAV:fork-ok
+ element.
+
+ <!ELEMENT fork-ok EMPTY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:checkin-response XML element.
+
+ <!ELEMENT checkin-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 65]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Preconditions:
+
+ (DAV:must-be-checked-out): See Section 4.4.
+
+ (DAV:version-history-is-tree) See Section 4.4.
+
+ (DAV:checkin-fork-forbidden): See Section 4.4.
+
+ (DAV:checkin-fork-discouraged): See Section 4.4.
+
+ (DAV:no-overwrite-by-auto-update): If the DAV:auto-update property
+ for the checked-out resource identifies a version-controlled
+ resource, at least one of the versions identified by the
+ DAV:predecessor-set property of the checked-out resource MUST
+ identify a version that is either the same as or a descendant of
+ the version identified by the DAV:checked-in property of that
+ version-controlled resource.
+
+ Postconditions:
+
+ (DAV:create-version): See Section 4.4.
+
+ (DAV:initialize-version-content-and-properties): See Section 4.4.
+
+ (DAV:auto-update): If the DAV:auto-update property of the
+ checked-out resource identified a version-controlled resource, an
+ UPDATE request with the new version MUST have been applied to that
+ version-controlled resource.
+
+ (DAV:delete-working-resource): If the request-URL identifies a
+ working resource and if DAV:keep-checked-out is not specified in
+ the request body, the working resource is deleted.
+
+9.4.1 Example - CHECKIN of a working resource
+
+ >>REQUEST
+
+ CHECKIN /wr/157 HTTP/1.1
+ Host: repo.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Location: http://repo.webdav.org/his/23/ver/15
+ Cache-Control: no-cache
+
+
+
+
+
+Clemm, et al. Standards Track [Page 66]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, the working resource /wr/157 checked in, and a new
+ version is created at http://repo.webdav.org/his/23/ver/15.
+
+9.5 Additional OPTIONS Semantics
+
+ If the server supports the working-resource feature, it MUST include
+ "working-resource" as a field in the DAV response header from an
+ OPTIONS request on any resource that supports any versioning
+ properties, reports, or methods.
+
+9.6 Additional COPY Semantics
+
+ Additional Postconditions:
+
+ (DAV:copy-creates-new-resource): The result of copying a working
+ resource is a new non-version-controlled resource at the
+ destination of the COPY. The new resource MAY automatically be
+ put under version control, but the resulting version-controlled
+ resource MUST be associated with a new version history created for
+ that new version-controlled resource.
+
+9.7 Additional MOVE Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-rename-working-resource): If the request-URL
+ identifies a working resource, the request MUST fail.
+
+ Additional Postconditions:
+
+ (DAV:update-auto-update): If the request-URL identified a
+ version-controlled resource, any DAV:auto-update properties that
+ identified that version-controlled resource MUST have been updated
+ to contain the new location of that version-controlled resource.
+
+10 Advanced Versioning Features
+
+ Advanced versioning addresses the problems of parallel development
+ and configuration management of multiple sets of interrelated
+ resources. Traditionally, artifacts of software development,
+ including requirements, design documents, code, and test cases, have
+ been a focus of configuration management. Web sites, comprising
+ multiple inter-linked resources (HTML, graphics, sound, CGI, and
+ others), are another class of complex information artifacts that
+ benefit from the application of configuration management. The
+ advanced versioning capabilities for coordinating concurrent change
+ provide the infrastructure for efficient and controlled management of
+ large evolving web sites.
+
+
+
+Clemm, et al. Standards Track [Page 67]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+10.1 Advanced Versioning Packages
+
+ Although a server MAY support any combination of advanced versioning
+ features, in order to minimize the complexity of a WebDAV advanced
+ versioning client, a WebDAV advanced versioning server SHOULD support
+ one of the following packages:
+
+ Advanced-Server-Workspace Package: basic-server-workspace package
+ plus all advanced features
+
+ Advanced-Client-Workspace Package: basic-client-workspace package
+ plus all advanced features
+
+ The advanced-server-workspace package supports advanced versioning
+ capabilities for a client with no persistent state. The advanced-
+ client-workspace package supports advanced versioning capabilities
+ for a client that maintains configuration state on the client. A
+ server that supports both advanced workspace packages will
+ interoperate with all versioning clients.
+
+10.2 Advanced Versioning Terms
+
+ The following additional terms are used by the advanced versioning
+ features.
+
+ Collection
+
+ A "collection" is a resource whose state consists of not only
+ content and properties, but also a set of named "bindings", where
+ a binding identifies what RFC 2518 calls an "internal member" of
+ the collection. Note that a binding is not a resource, but rather
+ is a part of the state of a collection that defines a mapping from
+ a binding name (a URL segment) to a resource (an internal member
+ of the collection).
+
+ Collection Version Resource
+
+ A "collection version resource", or simply "collection version",
+ captures the dead properties of a version-controlled collection,
+ as well as the names of its version-controlled bindings (see
+ Section 14). A version-controlled binding is a binding to a
+ version-controlled resource. If the checkout-in-place feature is
+ supported, a collection version can be created by checking out and
+ then checking in a version-controlled collection. If the
+ working-resource feature is supported, a collection version can be
+ created by checking out a collection version (to create a "working
+ collection") and then checking in the working collection.
+
+
+
+
+Clemm, et al. Standards Track [Page 68]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Configuration
+
+ A "configuration" is a set of resources that consists of a root
+ collection and all members (not just internal members) of that
+ root collection that are not members of another configuration.
+ The root collection is called the "configuration root", and the
+ members of this set are called the "members of the configuration".
+ Note that a collection (which is a single resource) is very
+ different from a configuration (which is a set of resources).
+
+ Baseline Resource
+
+ A "baseline resource", or simply "baseline", of a collection is a
+ version of the configuration that is rooted at that collection
+ (see Section 12). In particular, a baseline captures the
+ DAV:checked-in version of every version-controlled member of that
+ configuration. Note that a collection version (which captures the
+ state of a single resource) is very different from a collection
+ baseline (which captures the state of a set of resources).
+
+ Baseline-Controlled Collection
+
+ A "baseline-controlled collection" is a collection from which
+ baselines can be created (see Section 12).
+
+ Version-Controlled Configuration Resource
+
+ A "version-controlled configuration resource", or simply
+ "version-controlled configuration", is a special kind of version-
+ controlled resource that is associated with a baseline-controlled
+ collection, and is used to create and access baselines of that
+ collection (see Section 12). When a collection is both version-
+ controlled and baseline-controlled, a client can create a new
+ version of the collection by checking out and checking in that
+ collection, and it can create a new baseline of that collection by
+ checking out and checking in the version-controlled configuration
+ of that collection.
+
+ Activity Resource
+
+ An "activity resource", or simply "activity", is a resource that
+ selects a set of versions that correspond to a single logical
+ change, where the versions selected from a given version history
+ form a single line of descent through that version history (see
+ Section 13).
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 69]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+11 Merge Feature
+
+ When a user wants to accept the changes (new versions) created by
+ someone else, it is important not just to update the version-
+ controlled resources in the user's workspace with those new versions,
+ since this could result in "backing out" changes the user has made to
+ those version-controlled resources. Instead, the versions created in
+ another workspace should be "merged" into the user's version-
+ controlled resources.
+
+ The version history of a version-controlled resource provides the
+ information needed to determine the result of the merge. In
+ particular, the merge should select whichever version is later in the
+ line of descent from the root version. In case the versions to be
+ merged are on different lines of descent (neither version is a
+ descendant of the other), neither version should be selected, but
+ instead, a new version should be created that contains the logical
+ merge of the content and dead properties of those versions. The
+ MERGE request can be used to check out each version-controlled
+ resource that requires such a merge, and set the DAV:merge-set
+ property of each checked-out resource to identify the version to be
+ merged. The user is responsible for modifying the content and dead
+ properties of the checked-out resource so that it represents the
+ logical merge of that version, and then adding that version to the
+ DAV:predecessor-set of the checked-out resource.
+
+ If the server is capable of automatically performing the merge, it
+ MAY update the content, dead properties, and DAV:predecessor-set of
+ the checked-out resource itself. Before checking in the
+ automatically merged resource, the user is responsible for verifying
+ that the automatic merge is correct.
+
+11.1 Additional Checked-Out Resource Properties
+
+ The merge feature introduces the following REQUIRED properties for a
+ checked-out resource.
+
+11.1.1 DAV:merge-set
+
+ This property identifies each version that is to be merged into this
+ checked-out resource.
+
+ <!ELEMENT merge-set (href*)>
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 70]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+11.1.2 DAV:auto-merge-set
+
+ This property identifies each version that the server has merged into
+ this checked-out resource. The client should confirm that the merge
+ has been performed correctly before moving a URL from the DAV:auto-
+ merge-set to the DAV:predecessor-set of a checked-out resource.
+
+ <!ELEMENT auto-merge-set (href*)>
+
+11.2 MERGE Method
+
+ The MERGE method performs the logical merge of a specified version
+ (the "merge source") into a specified version-controlled resource
+ (the "merge target"). If the merge source is neither an ancestor nor
+ a descendant of the DAV:checked-in or DAV:checked-out version of the
+ merge target, the MERGE checks out the merge target (if it is not
+ already checked out) and adds the URL of the merge source to the
+ DAV:merge-set of the merge target. It is then the client's
+ responsibility to update the content and dead properties of the
+ checked-out merge target so that it reflects the logical merge of the
+ merge source into the current state of the merge target. The client
+ indicates that it has completed the update of the merge target, by
+ deleting the merge source URL from the DAV:merge-set of the checked-
+ out merge target, and adding it to the DAV:predecessor-set. As an
+ error check for a client forgetting to complete a merge, the server
+ MUST fail an attempt to CHECKIN a version-controlled resource with a
+ non-empty DAV:merge-set.
+
+ When a server has the ability to automatically update the content and
+ dead properties of the merge target to reflect the logical merge of
+ the merge source, it may do so unless DAV:no-auto-merge is specified
+ in the MERGE request body. In order to notify the client that a
+ merge source has been automatically merged, the MERGE request MUST
+ add the URL of the auto-merged source to the DAV:auto-merge-set
+ property of the merge target, and not to the DAV:merge-set property.
+ The client indicates that it has verified that the auto-merge is
+ valid, by deleting the merge source URL from the DAV:auto-merge-set,
+ and adding it to the DAV:predecessor-set.
+
+ Multiple merge sources can be specified in a single MERGE request.
+ The set of merge sources for a MERGE request is determined from the
+ DAV:source element of the MERGE request body as follows:
+
+ - If DAV:source identifies a version, that version is a merge
+ source.
+ - If DAV:source identifies a version-controlled resource, the
+ DAV:checked-in version of that version-controlled resource is a
+ merge source.
+
+
+
+Clemm, et al. Standards Track [Page 71]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ - If DAV:source identifies a collection, the DAV:checked-in version
+ of each version-controlled resource that is a member of that
+ collection is a merge source.
+
+ The request-URL identifies the set of possible merge targets. If the
+ request-URL identifies a collection, any member of the configuration
+ rooted at the request-URL is a possible merge target. The merge
+ target of a particular merge source is the version-controlled or
+ checked-out resource whose DAV:checked-in or DAV:checked-out version
+ is from the same version history as the merge source. If a merge
+ source has no merge target, that merge source is ignored.
+
+ The MERGE response identifies the resources that a client must modify
+ to complete the merge. It also identifies the resources modified by
+ the request, so that a client can efficiently update any cached state
+ it is maintaining.
+
+ Marshalling:
+
+ The request body MUST be a DAV:merge element.
+
+ The set of merge sources is determined by the DAV:source element
+ in the request body.
+
+ <!ELEMENT merge ANY>
+ ANY value: A sequence of elements with one DAV:source element, at
+ most one DAV:no-auto-merge element, at most one DAV:no-checkout
+ element, at most one DAV:prop element, and any legal set of
+ elements that can occur in a DAV:checkout element.
+ <!ELEMENT source (href+)>
+ <!ELEMENT no-auto-merge EMPTY>
+ <!ELEMENT no-checkout EMPTY>
+ prop: see RFC 2518, Section 12.11
+
+ The response for a successful request MUST be a 207 Multi-Status,
+ where the DAV:multistatus XML element in the response body
+ identifies all resources that have been modified by the request.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The response to a successful request MUST include a Location
+ header containing the URL for the new version created by the
+ checkin.
+
+ The response MUST include a Cache-Control:no-cache header.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 72]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Preconditions:
+
+ (DAV:cannot-merge-checked-out-resource): The DAV:source element
+ MUST NOT identify a checked-out resource. If the DAV:source
+ element identifies a collection, the collection MUST NOT have a
+ member that is a checked-out resource.
+
+ (DAV:checkout-not-allowed): If DAV:no-checkout is specified in the
+ request body, it MUST be possible to perform the merge without
+ checking out any of the merge targets.
+
+ All preconditions of the CHECKOUT operation apply to the checkouts
+ performed by the request.
+
+ Postconditions:
+
+ (DAV:ancestor-version): If a merge target is a version-controlled
+ or checked-out resource whose DAV:checked-in version or
+ DAV:checked-out version is the merge source or is a descendant of
+ the merge source, the merge target MUST NOT have been modified by
+ the MERGE.
+
+ (DAV:descendant-version): If the merge target was a checked-in
+ version-controlled resource whose DAV:checked-in version was an
+ ancestor of the merge source, an UPDATE operation MUST have been
+ applied to the merge target to set its content and dead properties
+ to be those of the merge source. If the UPDATE method is not
+ supported, the merge target MUST have been checked out, the
+ content and dead properties of the merge target MUST have been set
+ to those of the merge source, and the merge source MUST have been
+ added to the DAV:auto-merge-set of the merge target. The merge
+ target MUST appear in a DAV:response XML element in the response
+ body.
+
+ (DAV:checked-out-for-merge): If the merge target was a checked-in
+ version-controlled resource whose DAV:checked-in version was
+ neither a descendant nor an ancestor of the merge source, a
+ CHECKOUT MUST have been applied to the merge target. All XML
+ elements in the DAV:merge XML element that could appear in a
+ DAV:checkout XML element MUST have been used as arguments to the
+ CHECKOUT request. The merge target MUST appear in a DAV:response
+ XML element in the response body.
+
+ (DAV:update-merge-set): If the DAV:checked-out version of the
+ merge target is neither equal to nor a descendant of the merge
+ source, the merge source MUST be added to either the DAV:merge-set
+ or the DAV:auto-merge-set of the merge target. The merge target
+ MUST appear in a DAV:response XML element in the response body.
+
+
+
+Clemm, et al. Standards Track [Page 73]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ If a merge source has been added to the DAV:auto-merge-set, the
+ content and dead properties of the merge target MUST have been
+ modified by the server to reflect the result of a logical merge of
+ the merge source and the merge target. If a merge source has been
+ added to the DAV:merge-set, the content and dead properties of the
+ merge target MUST NOT have been modified by the server. If
+ DAV:no-auto-merge is specified in the request body, the merge
+ source MUST NOT have been added to the DAV:auto-merge-set.
+
+ (DAV:report-properties): If DAV:prop is specified in the request
+ body, the properties specified in the DAV:prop element MUST be
+ reported in the DAV:response elements in the response body.
+
+11.2.1 Example - MERGE
+
+ >>REQUEST
+
+ MERGE /ws/public HTTP/1.1
+ Host: www.webdav.org
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:merge xmlns:D="DAV:">
+ <D:source>
+ <D:href>http://www.webdav.org/ws/dev/sally</D:href>
+ </D:source>
+ </D:merge>
+
+ >>RESPONSE
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Cache-Control: no-cache
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.webdav.org/ws/public/src/parse.c</D:href>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:response>
+ <D:response>
+ <D:href>http://www.webdav.org/ws/public/doc/parse.html</D:href>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+Clemm, et al. Standards Track [Page 74]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, the DAV:checked-in versions from the workspace
+ http://www.webdav.org/ws/dev/sally are merged into the version-
+ controlled resources in the workspace
+ http://www.webdav.org/ws/public. The resources
+ /ws/public/src/parse.c and /ws/public/doc/parse.html were modified by
+ the request.
+
+11.3 DAV:merge-preview Report
+
+ A merge preview describes the changes that would result if the
+ versions specified by the DAV:source element in the request body were
+ to be merged into the resource identified by the request-URL
+ (commonly, a collection).
+
+ Marshalling:
+
+ The request body MUST be a DAV:merge-preview XML element.
+
+ <!ELEMENT merge-preview (source)>
+ <!ELEMENT source (href)>
+
+ The response body for a successful request MUST be a
+ DAV:merge-preview-report XML element.
+
+ <!ELEMENT merge-preview-report
+ (update-preview | conflict-preview | ignore-preview)*>
+
+ A DAV:update-preview element identifies a merge target whose
+ DAV:checked-in property would change as a result of the MERGE, and
+ identifies the merge source for that merge target.
+
+ <!ELEMENT update-preview (target, version)>
+ <!ELEMENT target (href)>
+ <!ELEMENT version (href)>
+
+ A DAV:conflict-preview element identifies a merge target that
+ requires a merge.
+
+ <!ELEMENT conflict-preview (target, common-ancestor, version)>
+
+ A DAV:common-ancestor element identifies the version that is a
+ common ancestor of both the merge source and the DAV:checked-in or
+ DAV:checked-out version of the merge target.
+
+ <!ELEMENT common-ancestor (href)>
+
+ A DAV:ignore-preview element identifies a version that has no
+ merge target and therefore would be ignored by the merge.
+
+
+
+Clemm, et al. Standards Track [Page 75]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT ignore-preview (version)>
+
+11.3.1 Example - DAV:merge-preview 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:merge-preview xmlns:D="DAV:">
+ <D:source>
+ <D:href>http://www.webdav.org/ws/dev/fred</D:href>
+ </D:source>
+ </D:merge-preview>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:merge-preview-report xmlns:D="DAV:">
+ <D:conflict-preview>
+ <D:target>
+ <D:href>http://www.webdav.org/ws/public/foo.html</D:href>
+ </D:target>
+ <D:common-ancestor>
+ <D:href>http://repo.webdav.org/his/23/ver/18</D:href>
+ </D:common-ancestor>
+ <D:version>
+ <D:href>http://repo.webdav.org/his/23/ver/42</D:href>
+ </D:version>
+ </D:conflict-preview>
+ <D:update-preview>
+ <D:target>
+ <D:href>http://www.webdav.org/ws/public/bar.html</D:href>
+ </D:target>
+ <D:version>
+ <D:href>http://www.repo/his/42/ver/3</D:href>
+ </D:version>
+ </D:update-preview>
+ </D:merge-preview-report>
+
+
+
+
+
+Clemm, et al. Standards Track [Page 76]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, the merge preview report indicates that version
+ /his/23/ver/42 would be merged in /ws/public/foo.html, and version
+ /his/42/ver/3 would update /ws/public/bar.html if the workspace
+ http://www.webdav.org/ws/dev/fred was merged into the workspace
+ http://www.webdav.org/ws/public.
+
+11.4 Additional OPTIONS Semantics
+
+ If the server supports the merge feature, it MUST include "merge" as
+ a field in the DAV response header from an OPTIONS request on any
+ resource that supports any versioning properties, reports, or
+ methods.
+
+11.5 Additional DELETE Semantics
+
+ Additional Postconditions:
+
+ (DAV:delete-version-reference): If a version is deleted, any
+ reference to that version in a DAV:merge-set or DAV:auto-merge-set
+ property MUST be removed.
+
+11.6 Additional CHECKIN Semantics
+
+ Additional Preconditions:
+
+ (DAV:merge-must-be-complete): The DAV:merge-set and DAV:auto-
+ merge-set of the checked-out resource MUST be empty or not exist.
+
+12 Baseline Feature
+
+ A configuration is a set of resources that consists of a root
+ collection and all members of that root collection except those
+ resources that are members of another configuration. A configuration
+ that contains a large number of resources can consume a large amount
+ of space on a server. This can make it prohibitively expensive to
+ remember the state of an existing configuration by creating a
+ Depth:infinity copy of its root collection.
+
+ A baseline is a version resource that captures the state of each
+ version-controlled member of a configuration. A baseline history is
+ a version history whose versions are baselines. New baselines are
+ created by checking out and then checking in a special kind of
+ version-controlled resource called a version-controlled
+ configuration.
+
+ A collection that is under baseline control is called a baseline-
+ controlled collection. In order to allow efficient baseline
+ implementation, the state of a baseline of a collection is limited to
+
+
+
+Clemm, et al. Standards Track [Page 77]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ be a set of versions and their names relative to the collection, and
+ the operations on a baseline are limited to the creation of a
+ baseline from a collection, and restoring or merging the baseline
+ back into a collection. A server MAY automatically put a collection
+ under baseline control when it is created, or a client can use the
+ BASELINE-CONTROL method to put a specified collection under baseline
+ control.
+
+ As a configuration gets large, it is often useful to break it up into
+ a set of smaller configurations that form the logical "components" of
+ that configuration. In order to capture the fact that a baseline of
+ a configuration is logically extended by a component configuration
+ baseline, the component configuration baseline is captured as a
+ "subbaseline" of the baseline.
+
+ The root collection of a configuration is unconstrained with respect
+ to its relationship to the root collection of any of its components.
+ In particular, the root collection of a configuration can have a
+ member that is the root collection of one of its components (e.g.,
+ configuration /sys/x can have a component /sys/x/foo), can be a
+ member of the root collection of one of its components (e.g.,
+ configuration /sys/y/z can have a component /sys/y), or neither
+ (e.g., configuration /sys/x can have a component /comp/bar).
+
+12.1 Version-Controlled Configuration Properties
+
+ Since a version-controlled configuration is a version-controlled
+ resource, it has all the properties of a version-controlled resource.
+ In addition, the baseline feature introduces the following REQUIRED
+ property for a version-controlled configuration.
+
+12.1.1 DAV:baseline-controlled-collection (protected)
+
+ This property identifies the collection that contains the version-
+ controlled resources whose DAV:checked-in versions are being tracked
+ by this version-controlled configuration. The DAV:version-
+ controlled-configuration of the DAV:baseline-controlled-collection of
+ a version-controlled configuration MUST identify that version-
+ controlled configuration.
+
+ <!ELEMENT baseline-controlled-collection (href)>
+
+12.2 Checked-Out Configuration Properties
+
+ Since a checked-out configuration is a checked-out resource, it has
+ all the properties of a checked-out resource. In addition, the
+ baseline feature introduces the following REQUIRED property for a
+ checked-out configuration.
+
+
+
+Clemm, et al. Standards Track [Page 78]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+12.2.1 DAV:subbaseline-set
+
+ This property determines the DAV:subbaseline-set property of the
+ baseline that results from checking in this resource.
+
+ A server MAY reject attempts to modify the DAV:subbaseline-set of a
+ checked-out configuration.
+
+ <!ELEMENT subbaseline-set (href*)>
+
+12.3 Baseline Properties
+
+ The DAV:resourcetype of a baseline MUST be DAV:baseline. Since a
+ baseline is a version resource, it has all the properties of a
+ version resource. In addition, the baseline feature introduces the
+ following REQUIRED properties for a baseline.
+
+12.3.1 DAV:baseline-collection (protected)
+
+ This property contains a server-defined URL for a collection, where
+ each member of this collection MUST either be a version-controlled
+ resource with the same DAV:checked-in version and relative name as a
+ version-controlled member of the baseline-controlled collection at
+ the time the baseline was created, or be a collection needed to
+ provide the relative name for a version-controlled resource.
+
+ <!ELEMENT baseline-collection (href)>
+
+12.3.2 DAV:subbaseline-set (protected)
+
+ The URLs in the DAV:subbaseline-set property MUST identify a set of
+ other baselines. The subbaselines of a baseline are the baselines
+ identified by its DAV:subbaseline-set and all subbaselines of the
+ baselines identified by its DAV:subbaseline-set.
+
+ <!ELEMENT subbaseline-set (href*)>
+
+12.4 Additional Resource Properties
+
+ The baseline feature introduces the following REQUIRED property for a
+ resource.
+
+12.4.1 DAV:version-controlled-configuration (computed)
+
+ If the resource is a member of a version-controlled configuration
+ (i.e. the resource is a collection under baseline control or is a
+ member of a collection under baseline control), this property
+ identifies that version-controlled configuration.
+
+
+
+Clemm, et al. Standards Track [Page 79]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT version-controlled-configuration (href)>
+
+12.5 Additional Workspace Properties
+
+ The baseline feature introduces the following REQUIRED property for a
+ workspace.
+
+12.5.1 DAV:baseline-controlled-collection-set (computed)
+
+ This property identifies each member of the workspace that is a
+ collection under baseline control (as well as the workspace itself,
+ if it is under baseline control).
+
+ <!ELEMENT baseline-controlled-collection-set (href*)>
+
+12.6 BASELINE-CONTROL Method
+
+ A collection can be placed under baseline control with a
+ BASELINE-CONTROL request. When a collection is placed under baseline
+ control, the DAV:version-controlled-configuration property of the
+ collection is set to identify a new version-controlled configuration.
+ This version-controlled configuration can be checked out and then
+ checked in to create a new baseline for that collection.
+
+ If a baseline is specified in the request body, the DAV:checked-in
+ version of the new version-controlled configuration will be that
+ baseline, and the collection is initialized to contain version-
+ controlled members whose DAV:checked-in versions and relative names
+ are determined by the specified baseline.
+
+ If no baseline is specified, a new baseline history is created
+ containing a baseline that captures the state of the version-
+ controlled members of the collection, and the DAV:checked-in version
+ of the version-controlled configuration will be that baseline.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:baseline-control
+ XML element.
+
+ <!ELEMENT baseline-control ANY>
+ ANY value: A sequence of elements with at most one DAV:baseline
+ element.
+
+ <!ELEMENT baseline (href)>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:baseline-control-response XML element.
+
+
+
+Clemm, et al. Standards Track [Page 80]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT baseline-control-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:version-controlled-configuration-must-not-exist): The
+ DAV:version-controlled-configuration property of the collection
+ identified by the request-URL MUST not exist.
+
+ (DAV:must-be-baseline): The DAV:href of the DAV:baseline element
+ in the request body MUST identify a baseline.
+
+ (DAV:must-have-no-version-controlled-members): If a DAV:baseline
+ element is specified in the request body, the collection
+ identified by the request-URL MUST have no version-controlled
+ members.
+
+ (DAV:one-baseline-controlled-collection-per-history-per-
+ workspace): If the request-URL identifies a workspace or a member
+ of a workspace, and if a baseline is specified in a DAV:baseline
+ element in the request body, then there MUST NOT be another
+ collection in that workspace whose DAV:version-controlled-
+ configuration property identifies a version-controlled
+ configuration for the baseline history of that baseline.
+
+ Postconditions:
+
+ (DAV:create-version-controlled-configuration): A new version-
+ controlled configuration is created, whose DAV:baseline-
+ controlled-collection property identifies the collection.
+
+ (DAV:reference-version-controlled-configuration): The
+ DAV:version-controlled-configuration of the collection identifies
+ the new version-controlled configuration.
+
+ (DAV:select-existing-baseline): If the request body specifies a
+ baseline, the DAV:checked-in property of the new version-
+ controlled configuration MUST have been set to identify this
+ baseline. A version-controlled member of the collection will be
+ created for each version in the baseline, where the version-
+ controlled member will have the content and dead properties of
+ that version, and will have the same name relative to the
+ collection as the corresponding version-controlled resource had
+ when the baseline was created. Any nested collections that are
+ needed to provide the appropriate name for a version-controlled
+ member will be created.
+
+
+
+
+Clemm, et al. Standards Track [Page 81]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:create-new-baseline): If no baseline is specified in the
+ request body, the request MUST have created a new baseline history
+ at a server-defined URL, and MUST have created a new baseline in
+ that baseline history. The DAV:baseline-collection of the new
+ baseline MUST identify a collection whose members have the same
+ relative name and DAV:checked-in version as the version-controlled
+ members of the request collection. The DAV:checked-in property of
+ the new version-controlled configuration MUST identify the new
+ baseline.
+
+12.6.1 Example - BASELINE-CONTROL
+
+ >>REQUEST
+
+ BASELINE-CONTROL /src 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:baseline-control xmlns:D="DAV:">
+ <D:href>http://www.webdav.org/repo/blh/13/ver/8</D:href>
+ </D:baseline-control>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Cache-Control: no-cache
+ Content-Length: 0
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 82]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, the collection /src is placed under baseline
+ control, and is populated with members from an existing baseline. A
+ new version-controlled configuration (/repo/vcc/128) is created and
+ associated with /src, and /src is initialized with version-controlled
+ members whose DAV:checked-in versions are those selected by the
+ DAV:baseline-collection (/repo/bc/15) of the specified baseline
+ (/repo/blh/13/ver/8). The following diagram illustrates the
+ resulting state on the server.
+
+ +-------------------------------------+
+ |Baseline-Controlled Collection |<------+
+ |/src | |
+ |-------------------------------------| |
+ |DAV:version-controlled-configuration +---+ |
+ +-------------------------------------+ | |
+ | |
+ | |
+ +-------------------------------------+ | |
+ |Version-Controlled Configuration |<--+ |
+ |/repo/vcc/128 | |
+ |-------------------------------------| |
+ |DAV:baseline-controlled-collection +-------+
+ |-------------------------------------|
+ |DAV:checked-in +-------+
+ +-------------------------------------+ |
+ |DAV:version-history +---+ |
+ +-------------------------------------+ | |
+ | |
+ | |
+ +------------------------+ | |
+ |Baseline History |<---------------+ |
+ |/repo/blh/13 | |
+ |------------------------+ |
+ |DAV:version-set +----------------+ |
+ +------------------------+ | | | | |
+ v | v v |
+ | |
+ +------------------------+ | |
+ |Baseline |<-------+-----------+
+ |/repo/blh/13/ver/8 |
+ |------------------------+ +--------------+
+ |DAV:baseline-collection +---->|Collection |
+ +------------------------+ |/repo/bc/15 |
+ +--------------+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 83]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In order to create new baselines of /src, /repo/vcc/128 can be
+ checked out, new versions can be created or selected by the version-
+ controlled members of /src, and then /repo/vcc/128 can be checked in
+ to capture the current state of those version-controlled members.
+
+12.7 DAV:compare-baseline Report
+
+ A DAV:compare-baseline report contains the differences between the
+ baseline identified by the request-URL (the "request baseline") and
+ the baseline specified in the request body (the "compare baseline").
+
+ Marshalling:
+
+ The request body MUST be a DAV:compare-baseline XML element.
+
+ <!ELEMENT compare-baseline (href)>
+
+ The response body for a successful request MUST be a DAV:compare-
+ baseline-report XML element.
+
+ <!ELEMENT compare-baseline-report
+ (added-version | deleted-version | changed-version)*>
+
+ A DAV:added-version element identifies a version that is the
+ DAV:checked-in version of a member of the DAV:baseline-collection
+ of the compare baseline, but no version in the version history of
+ that version is the DAV:checked-in version of a member of the
+ DAV:baseline-collection of the request baseline.
+
+ <!ELEMENT added-version (href)>
+
+ A DAV:deleted-version element identifies a version that is the
+ DAV:checked-in version of a member of the DAV:baseline-collection
+ of the request baseline, but no version in the version history of
+ that version is the DAV:checked-in version of a member of the
+ DAV:baseline-collection of the compare baseline.
+
+ <!ELEMENT deleted-version (href)>
+
+ A DAV:changed-version element identifies two different versions
+ from the same version history that are the DAV:checked-in version
+ of the DAV:baseline-collection of the request baseline and the
+ compare baseline, respectively.
+
+ <!ELEMENT changed-version (href, href)>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 84]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Preconditions:
+
+ (DAV:must-be-baseline): The DAV:href in the request body MUST
+ identify a baseline.
+
+ (DAV:baselines-from-same-history): A server MAY require that the
+ baselines being compared be from the same baseline history.
+
+12.7.1 Example - DAV:compare-baseline Report
+
+ >>REQUEST
+
+ REPORT /bl-his/12/bl/14 HTTP/1.1
+ Host: repo.webdav.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:compare-baseline xmlns:D="DAV:">
+ <D:href>http://repo.webdav.org/bl-his/12/bl/15</D:href>
+ </D:compare-baseline>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:compare-baseline-report xmlns:D="DAV:">
+ <D:added-version>
+ <D:href>http://repo.webdav.org/his/23/ver/8</D:href>
+ </D:added-version>
+ <D:changed-version>
+ <D:href>http://repo.webdav.org/his/29/ver/12</D:href>
+ <D:href>http://repo.webdav.org/his/29/ver/19</D:href>
+ </D:changed-version>
+ <D:deleted-version>
+ <D:href>http://repo.webdav.org/his/12/ver/4</D:href>
+ </D:deleted-version>
+ </D:compare-baseline-report>
+
+ In this example, the differences between baseline 14 and baseline 15
+ of http://repo.webdav.org/bl-his/12 are identified.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 85]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+12.8 Additional OPTIONS Semantics
+
+ If a server supports the baseline feature, it MUST include "baseline"
+ as a field in the DAV response header from an OPTIONS request on any
+ resource that supports any versioning properties, reports, or
+ methods.
+
+12.9 Additional MKCOL Semantics
+
+ Additional Postconditions:
+
+ If a server automatically puts a newly created collection under
+ baseline control, all postconditions for BASELINE-CONTROL apply to
+ the MKCOL.
+
+12.10 Additional COPY Semantics
+
+ Additional Postconditions:
+
+ If the request creates a new collection at the Destination, and a
+ server automatically puts a newly created collection under
+ baseline control, all postconditions for BASELINE-CONTROL apply to
+ the COPY.
+
+12.11 Additional CHECKOUT Semantics
+
+ Additional Preconditions:
+
+ (DAV:must-not-update-baseline-collection): If the request-URL
+ identifies a member of the configuration rooted at the
+ DAV:baseline-collection of a baseline, the request MUST fail.
+
+12.12 Additional CHECKIN Semantics
+
+ Additional Preconditions:
+
+ (DAV:no-checked-out-baseline-controlled-collection-members): If
+ the request-URL identifies a version-controlled configuration, all
+ version-controlled members of the DAV:baseline-controlled-
+ collection of the version-controlled configuration MUST be
+ checked-in.
+
+ (DAV:one-version-per-history-per-baseline): If the request-URL
+ identifies a version-controlled configuration, the set of versions
+ selected by that version-controlled configuration MUST contain at
+ most one version from any version history, where a version is
+ selected by a version-controlled configuration if the version is
+ identified by the DAV:checked-in property of any member of the
+
+
+
+Clemm, et al. Standards Track [Page 86]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ configuration rooted at the DAV:baseline-controlled collection of
+ that version-controlled configuration, or is identified by the
+ DAV:checked-in property of any member of the configuration rooted
+ at the DAV:baseline-collection of any subbaseline of that
+ version-controlled configuration.
+
+ (DAV:cannot-modify-version-controlled-configuration): If the
+ request-URL identifies a version-controlled member of a baseline-
+ controlled collection whose version-controlled configuration is
+ checked-in, the request MUST fail unless the DAV:auto-version
+ property of the version-controlled configuration will
+ automatically check out that version-controlled configuration when
+ it is modified.
+
+ Additional Postconditions:
+
+ (DAV:create-baseline-collection): If the request-URL identifies a
+ version-controlled configuration, the DAV:baseline-collection of
+ the new baseline identifies a collection whose members have the
+ same relative name and DAV:checked-in version as the members of
+ the DAV:baseline-controlled-collection of the version-controlled
+ configuration at the time of the request.
+
+ (DAV:modify-configuration): If the request-URL identifies a
+ version-controlled member of a baseline-controlled collection,
+ this is a modification to the version-controlled configuration of
+ that baseline-controlled collection, and standard auto-versioning
+ semantics apply.
+
+12.13 Additional UPDATE Semantics
+
+ Additional Preconditions:
+
+ (DAV:baseline-controlled-members-must-be-checked-in): If the
+ request-URL identifies a version-controlled configuration, then
+ all version-controlled members of the DAV:baseline-controlled-
+ collection of that version-controlled configuration MUST be
+ checked-in.
+
+ (DAV:must-not-update-baseline-collection): If the request-URL
+ identifies a member of the configuration rooted at the
+ DAV:baseline-collection of a baseline, the request MUST fail.
+
+ (DAV:cannot-modify-version-controlled-configuration): If the
+ request updates the DAV:checked-in property of any version-
+ controlled member of a baseline-controlled collection whose
+ version-controlled configuration is checked-in, the request MUST
+
+
+
+
+Clemm, et al. Standards Track [Page 87]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ fail unless the DAV:auto-version property of the version-
+ controlled configuration will automatically check out that
+ version-controlled configuration when it is modified.
+
+ Additional Postconditions:
+
+ (DAV:set-baseline-controlled-collection-members): If the request
+ updated the DAV:checked-in property of a version-controlled
+ configuration, then the version-controlled members of the
+ DAV:baseline-controlled-collection of that version-controlled
+ configuration MUST have been updated so that they have the same
+ relative name, content, and dead properties as the members of the
+ DAV:baseline-collection of the baseline. In particular:
+
+ - A version-controlled member for a given version history MUST
+ have been deleted if there is no version-controlled member for
+ that version history in the DAV:baseline-collection of the
+ baseline.
+ - A version-controlled member for a given version history MUST
+ have been renamed if its name relative to the baseline-
+ controlled collection is different from that of the version-
+ controlled member for that version history in the
+ DAV:baseline-collection of the baseline.
+ - A new version-controlled member MUST have been created for each
+ member of the DAV:baseline-collection of the baseline for which
+ there is no corresponding version-controlled member in the
+ baseline-controlled collection.
+ - An UPDATE request MUST have been applied to each version-
+ controlled member for a given version history whose
+ DAV:checked-in version is not the same as that of the version-
+ controlled member for that version history in the
+ DAV:baseline-collection of the baseline.
+
+ (DAV:update-subbaselines): If the request updated a version-
+ controlled configuration whose DAV:baseline-controlled-collection
+ contains a baseline-controlled member for one of the subbaselines
+ of the request baseline, then the DAV:checked-in property of the
+ version-controlled configuration of that baseline-controlled
+ member MUST have been updated to be that subbaseline. If the
+ request updated a version-controlled configuration whose
+ DAV:baseline-controlled-collection is a member of a workspace that
+ contains a baseline-controlled member for one of the subbaselines
+ of the request baseline, then the DAV:checked-in property of the
+ version-controlled configuration of that baseline-controlled
+ member MUST have been updated to be that subbaseline.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 88]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:modify-configuration): If the request updated the
+ DAV:checked-in property of any version-controlled member of a
+ baseline-controlled collection, and if this DAV:checked-in
+ property differs from the DAV:checked-in property of the
+ corresponding version-controlled member of the DAV:baseline-
+ collection of the DAV:checked-in baseline of the DAV:version-
+ controlled-configuration of the baseline-controlled collection,
+ then this is a modification to that version-controlled
+ configuration, and standard auto-versioning semantics apply.
+
+12.14 Additional MERGE Semantics
+
+ If the merge source is a baseline, the merge target is a version-
+ controlled configuration for the baseline history of that baseline,
+ where the baseline-controlled collection of that version-controlled
+ configuration is a member of the collection identified by the
+ request-URL.
+
+ Additional Preconditions:
+
+ (DAV:must-not-update-baseline-collection): Same semantics as
+ UPDATE (see Section 12.13).
+
+ (DAV:cannot-modify-version-controlled-configuration): Same
+ semantics as UPDATE (see Section 12.13).
+
+ Additional Postconditions:
+
+ (DAV:merge-baseline): If the merge target is a version-controlled
+ configuration whose DAV:checked-out baseline is not a descendant
+ of the merge baseline, then the merge baseline MUST have been
+ added to the DAV:auto-merge-set of a version-controlled
+ configuration. The DAV:checked-in version of each member of the
+ DAV:baseline-collection of that baseline MUST have been merged
+ into the DAV:baseline-controlled-collection of that version-
+ controlled configuration.
+
+ (DAV:merge-subbaselines): If the merge target is a version-
+ controlled configuration whose DAV:baseline-controlled-collection
+ contains a baseline-controlled member for one of the subbaselines
+ of the merge baseline, then that subbaseline MUST have been merged
+ into the version-controlled configuration of that baseline-
+ controlled member. If the merge target is a version-controlled
+ configuration whose DAV:baseline-controlled-collection is a member
+ of a workspace that contains a baseline-controlled member for one
+ of the subbaselines of the merge baseline, then that subbaseline
+ MUST have been merged into the version-controlled configuration of
+ that baseline-controlled member.
+
+
+
+Clemm, et al. Standards Track [Page 89]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:set-baseline-controlled-collection-members): Same semantics
+ as UPDATE (see Section 12.13).
+
+ (DAV:modify-configuration): Same semantics as UPDATE (see Section
+ 12.13).
+
+13 Activity Feature
+
+ An activity is a resource that selects a set of versions that are on
+ a single "line of descent", where a line of descent is a sequence of
+ versions connected by successor relationships. If an activity
+ selects versions from multiple version histories, the versions
+ selected in each version history must be on a single line of descent.
+
+ A common problem that motivates the use of activities is that it is
+ often desirable to perform several different logical changes in a
+ single workspace, and then selectively merge a subset of those
+ logical changes to other workspaces. An activity can be used to
+ represent a single logical change, where an activity tracks all the
+ resources that were modified to effect that single logical change.
+ When a version-controlled resource is checked out, the user specifies
+ which activity should be associated with a new version that will be
+ created when that version-controlled resource is checked in. It is
+ then possible to select a particular logical change for merging into
+ another workspace, by specifying the appropriate activity in a MERGE
+ request.
+
+ Another common problem is that although a version-controlled resource
+ may need to have multiple lines of descent, all work done by members
+ of a given team must be on a single line of descent (to avoid merging
+ between team members). An activity resource provides the mechanism
+ for addressing this problem. When a version-controlled resource is
+ checked out, a client can request that an existing activity be used
+ or that a new activity be created. Activity semantics then ensure
+ that all versions in a given version history that are associated with
+ an activity are on a single line of descent. If all members of a
+ team share a common activity (or sub-activities of a common
+ activity), then all changes made by members of that team will be on a
+ single line of descent.
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 90]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The following diagram illustrates activities. Version V5 is the
+ latest version of foo.html selected by activity Act-2, and version V8
+ is the latest version of bar.html selected by activity Act-2.
+
+ foo.html History bar.html History
+
+ +---+ +---+
+ Act-1| |V1 Act-1| |V6
+ +---+ +---+
+ | |
+ | |
+ +---+ +---+
+ Act-1| |V2 Act-2| |V7
+ +---+ +---+
+ / \ |
+ / \ |
+ +---+ +---+ +---+
+ Act-1| |V3 Act-2| |V4 Act-2| |V8
+ +---+ +---+ +---+
+ | |
+ | |
+ +---+ +---+
+ Act-2| |V5 Act-3| |V9
+ +---+ +---+
+
+ Activities appear under a variety of names in existing versioning
+ systems. When an activity is used to capture a logical change, it is
+ commonly called a "change set". When an activity is used to capture
+ a line of descent, it is commonly called a "branch". When a system
+ supports both branches and change sets, it is often useful to require
+ that a particular change set occur on a particular branch. This
+ relationship can be captured by making the change set activity be a
+ "subactivity" of the branch activity.
+
+13.1 Activity Properties
+
+ The DAV:resourcetype of an activity MUST be DAV:activity.
+
+ The activity feature introduces the following REQUIRED properties for
+ an activity.
+
+13.1.1 DAV:activity-version-set (computed)
+
+ This property identifies each version whose DAV:activity-set property
+ identifies this activity. Multiple versions of a single version
+ history can be selected by an activity's DAV:activity-version-set
+
+
+
+
+
+Clemm, et al. Standards Track [Page 91]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ property, but all DAV:activity-version-set versions from a given
+ version history must be on a single line of descent from the root
+ version of that version history.
+
+ <!ELEMENT activity-version-set (href*)>
+
+13.1.2 DAV:activity-checkout-set (computed)
+
+ This property identifies each checked-out resource whose
+ DAV:activity-set identifies this activity.
+
+ <!ELEMENT activity-checkout-set (href*)>
+
+13.1.3 DAV:subactivity-set
+
+ This property identifies each activity that forms a part of the
+ logical change being captured by this activity. An activity behaves
+ as if its DAV:activity-version-set is extended by the DAV:activity-
+ version-set of each activity identified in the DAV:subactivity-set.
+ In particular, the versions in this extended set MUST be on a single
+ line of descent, and when an activity selects a version for merging,
+ the latest version in this extended set is the one that will be
+ merged.
+
+ A server MAY reject attempts to modify the DAV:subactivity-set of an
+ activity.
+
+ <!ELEMENT subactivity-set (href*)>
+
+13.1.4 DAV:current-workspace-set (computed)
+
+ This property identifies each workspace whose DAV:current-activity-
+ set identifies this activity.
+
+ <!ELEMENT current-workspace-set (href*)>
+
+13.2 Additional Version Properties
+
+ The activity feature introduces the following REQUIRED property for a
+ version.
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 92]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.2.1 DAV:activity-set
+
+ This property identifies the activities that determine to which
+ logical changes this version contributes, and on which lines of
+ descent this version appears. A server MAY restrict the
+ DAV:activity-set to identify a single activity. A server MAY refuse
+ to allow the value of the DAV:activity-set property of a version to
+ be modified.
+
+ <!ELEMENT activity-set (href*)>
+
+13.3 Additional Checked-Out Resource Properties
+
+ The activity feature introduces the following REQUIRED properties for
+ a checked-out resource.
+
+13.3.1 DAV:unreserved
+
+ This property of a checked-out resource indicates whether the
+ DAV:activity-set of another checked-out resource associated with the
+ version history of this version-controlled resource can have an
+ activity that is in the DAV:activity-set property of this checked-out
+ resource.
+
+ A result of the requirement that an activity must form a single line
+ of descent through a given version history is that if multiple
+ checked-out resources for a given version history are checked out
+ unreserved into a single activity, only the first CHECKIN will
+ succeed. Before another of these checked-out resources can be
+ checked in, the user will first have to merge into that checked-out
+ resource the latest version selected by that activity from that
+ version history, and then modify the DAV:predecessor-set of that
+ checked-out resource to identify that version.
+
+ <!ELEMENT unreserved (#PCDATA)>
+ PCDATA value: boolean
+
+13.3.2 DAV:activity-set
+
+ This property of a checked-out resource determines the DAV:activity-
+ set property of the version that results from checking in this
+ resource.
+
+13.4 Additional Workspace Properties
+
+ The activity feature introduces the following REQUIRED property for a
+ workspace.
+
+
+
+
+Clemm, et al. Standards Track [Page 93]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.4.1 DAV:current-activity-set
+
+ This property identifies the activities that currently are being
+ performed in this workspace. When a member of this workspace is
+ checked out, if no activity is specified in the checkout request, the
+ DAV:current-activity-set will be used. This allows an activity-
+ unaware client to update a workspace in which activity tracking is
+ required. The DAV:current-activity-set MAY be restricted to identify
+ at most one activity.
+
+ <!ELEMENT current-activity-set (href*)>
+
+13.5 MKACTIVITY Method
+
+ A MKACTIVITY request creates a new activity resource. A server MAY
+ restrict activity creation to particular collections, but a client
+ can determine the location of these collections from a DAV:activity-
+ collection-set OPTIONS request.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:mkactivity XML
+ element.
+
+ <!ELEMENT mkactivity ANY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:mkactivity-response XML element.
+
+ <!ELEMENT mkactivity-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:activity-location-ok): The request-URL MUST identify a
+ location where an activity can be created.
+
+ Postconditions:
+
+ (DAV:initialize-activity): A new activity exists at the request-
+ URL. The DAV:resourcetype of the activity MUST be DAV:activity.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 94]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.5.1 Example - MKACTIVITY
+
+ >>REQUEST
+
+ MKACTIVITY /act/test-23 HTTP/1.1
+ Host: repo.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Cache-Control: no-cache
+
+ In this example, a new activity is created at
+ http://repo.webdav.org/act/test-23.
+
+13.6 DAV:latest-activity-version Report
+
+ The DAV:latest-activity-version report can be applied to a version
+ history to identify the latest version that is selected from that
+ version history by a given activity.
+
+ Marshalling:
+
+ The request body MUST be a DAV:latest-activity-version XML
+ element.
+
+ <!ELEMENT latest-activity-version (href)>
+
+ The response body for a successful request MUST be a DAV:latest-
+ activity-version-report XML element.
+
+ <!ELEMENT latest-activity-version-report (href)>
+
+ The DAV:href of the response body MUST identify the version of the
+ given version history that is a member of the DAV:activity-
+ version-set of the given activity and has no descendant that is a
+ member of the DAV:activity-version-set of that activity.
+
+ Preconditions:
+
+ (DAV:must-be-activity): The DAV:href in the request body MUST
+ identify an activity.
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 95]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.7 Additional OPTIONS Semantics
+
+ If the server supports the activity feature, it MUST include
+ "activity" 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:activity-collection-set element MAY be included in the request
+ body to identify collections that may contain activity 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:activity-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:activity-collection-set element.
+
+ <!ELEMENT activity-collection-set (href*)>
+
+ If DAV:activity-collection-set is included in the request body,
+ the response body for a successful request MUST contain a
+ DAV:activity-collection-set element identifying collections that
+ may contain activities. An identified collection MAY be the root
+ collection of a tree of collections, all of which may contain
+ activities. Since different servers can control different parts
+ of the URL namespace, different resources on the same host MAY
+ have different DAV:activity-collection-set values. The identified
+ collections MAY be located on different hosts from the resource.
+
+13.8 Additional DELETE Semantics
+
+ Additional Postconditions:
+
+ (DAV:delete-activity-reference): If an activity is deleted, any
+ reference to that activity in a DAV:activity-set,
+ DAV:subactivity-set, or DAV:current-activity-set MUST be removed.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 96]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.9 Additional MOVE Semantics
+
+ Additional Postconditions:
+
+ (DAV:update-checked-out-reference): If a checked-out resource is
+ moved, any reference to that resource in a DAV:activity-checkout-
+ set property MUST be updated to refer to the new location of that
+ resource.
+
+ (DAV:update-activity-reference): If the request-URL identifies an
+ activity, any reference to that activity in a DAV:activity-set,
+ DAV:subactivity-set, or DAV:current-activity-set MUST be updated
+ to refer to the new location of that activity.
+
+ (DAV:update-workspace-reference): If the request-URL identifies a
+ workspace, any reference to that workspace in a DAV:current-
+ workspace-set property MUST be updated to refer to the new
+ location of that workspace.
+
+13.10 Additional CHECKOUT Semantics
+
+ A CHECKOUT request MAY specify the DAV:activity-set for the checked-
+ out resource.
+
+ Additional Marshalling:
+
+ <!ELEMENT checkout ANY> ANY value: A sequence of elements with at
+ most one DAV:activity-set and at most one DAV:unreserved.
+
+ <!ELEMENT activity-set (href+ | new)>
+ <!ELEMENT new EMPTY>
+ <!ELEMENT unreserved EMPTY>
+
+ Additional Preconditions:
+
+ (DAV:one-checkout-per-activity-per-history): If there is a request
+ activity set, unless DAV:unreserved is specified, another checkout
+ from a version of that version history MUST NOT select an activity
+ in that activity set.
+
+ (DAV:linear-activity): If there is a request activity set, unless
+ DAV:unreserved is specified, the selected version MUST be a
+ descendant of all other versions of that version history that
+ select that activity.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 97]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Postconditions:
+
+ (DAV:initialize-activity-set): The DAV:activity-set of the
+ checked-out resource is set as follows:
+
+ - If DAV:new is specified as the DAV:activity-set in the request
+ body, then a new activity created by the server is used.
+ - Otherwise, if activities are specified in the request body,
+ then those activities are used.
+ - Otherwise, if the version-controlled resource is a member of a
+ workspace and the DAV:current-activity-set of the workspace is
+ set, then those activities are used.
+ - Otherwise, the DAV:activity-set of the DAV:checked-out version
+ is used.
+
+ (DAV:initialize-unreserved): If DAV:unreserved was specified in
+ the request body, then the DAV:unreserved property of the
+ checked-out resource MUST be "true".
+
+13.10.1 Example - CHECKOUT with an activity
+
+ >>REQUEST
+
+ CHECKOUT /ws/public/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:checkout xmlns:D="DAV:">
+ <D:activity-set>
+ <D:href>http://repo.webdav.org/act/fix-bug-23</D:href>
+ </D:activity-set>
+ </D:checkout>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Cache-Control: no-cache
+
+ In this example, the CHECKOUT is being performed in the
+ http://repo.webdav.org/act/fix-bug-23 activity.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 98]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.11 Additional CHECKIN Semantics
+
+ Additional Preconditions:
+
+ (DAV:linear-activity): Any version which is in the version history
+ of the checked-out resource and whose DAV:activity-set identifies
+ an activity from the DAV:activity-set of the checked-out resource
+ MUST be an ancestor of the checked-out resource.
+
+ (DAV:atomic-activity-checkin): If the request-URL identifies an
+ activity, the server MAY fail the request if any of the checked-
+ out resources in the DAV:activity-checkout-set of either that
+ activity or any subactivity of that activity cannot be checked in.
+
+ Additional Postconditions:
+
+ (DAV:initialize-activity-set): The DAV:activity-set of the new
+ version MUST have been initialized to be the same as the
+ DAV:activity-set of the checked-out resource.
+
+ (DAV:activity-checkin): If the request-URL identified an activity,
+ the server MUST have successfully applied the CHECKIN request to
+ each checked-out resource in the DAV:activity-checkout-set of both
+ that activity and any subactivity of that activity.
+
+13.12 Additional MERGE Semantics
+
+ If the DAV:source element of the request body identifies an activity,
+ then for each version history containing a version selected by that
+ activity, the latest version selected by that activity is a merge
+ source. Note that the versions selected by an activity are the
+ versions in its DAV:activity-version-set unioned with the versions
+ selected by the activities in its DAV:subactivity-set.
+
+ Additional Marshalling:
+
+ <!ELEMENT checkin-activity EMPTY>
+
+ Additional Postconditions:
+
+ (DAV:checkin-activity): If DAV:checkin-activity is specified in
+ the request body, and if the DAV:source element in the request
+ body identifies an activity, a CHECKIN request MUST have been
+ successfully applied to that activity before the merge sources
+ were determined.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 99]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+14 Version-Controlled-Collection Feature
+
+ As with any versionable resource, when a collection is put under
+ version control, a version history resource is created to contain
+ versions for that version-controlled collection. In order to
+ preserve standard versioning semantics (a version of a collection
+ should not be modifiable), a collection version only records
+ information about the version-controlled bindings of that collection.
+
+ In order to cleanly separate a modification to the namespace from a
+ modification to content or dead properties, a version of a collection
+ has no members, but instead records in its DAV:version-controlled-
+ binding-set property the binding name and version history resource of
+ each version-controlled internal member of that collection. If,
+ instead, a collection version contained bindings to other versions,
+ creating a new version of a resource would require creating a new
+ version of all the collection versions that contain that resource,
+ which would cause activities to become entangled. For example,
+ suppose a "feature-12" activity created a new version of /x/y/a.html.
+ If a collection version contained bindings to versions of its
+ members, a new version of /x/y would have to be created to contain
+ the new version of /x/y/a.html, and a new version of /x would have to
+ be created to contain the new version of /x/y. Now suppose a
+ "bugfix-47" activity created a new version of /x/z/b.html. Again, a
+ new version of /x/z and a new version of /x would have to be created
+ to contain the new version of /x/y/b.html. But now it is impossible
+ to merge just "bugfix-47" into another workspace without "feature-
+ 12", because the version of /x that contains the desired version of
+ /x/z/b.html also contains version of /x/y/a.html created for
+ "feature-12". If, instead, a collection version just records the
+ binding name and version history resource of each version-controlled
+ internal member, changing the version selected by a member of that
+ collection would not require a new version of the collection. The
+ new version is still in the same version history so no new collection
+ version is required, and "feature-12" and "bugfix-47" would not
+ become entangled.
+
+ In the following example, there are three version histories, named
+ VH14, VH19, and VH24, where VH14 contains versions of a collection.
+ The version-controlled collection /x has version V2 of version
+ history VH14 as its DAV:checked-in version. Since V2 has recorded
+ two version controlled bindings, one with binding name "a" to version
+ history VH19, and the other with binding name "b" to version history
+ VH24, /x MUST have two version-controlled bindings, one named "a" to
+ a version-controlled resource for history VH19, and the other named
+ "b" to a version-controlled resource for history VH24. The version-
+
+
+
+
+
+Clemm, et al. Standards Track [Page 100]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ controlled resource /x/a currently has V4 of VH19 as its
+ DAV:checked-in version, while /x/b has V8 of VH24 as its
+ DAV:checked-in version.
+
+ VH19
+ +---------+
+ | +---+ |
+ | | |V4 |
+ | +---+ |
+ | | |
+ | | |
+ | +---+ |
+ | | |V5 |
+ VH14 | +---+ |
+ +---------+ | | |
+ | +---+ | | | |
+ a +---+ | | |V1 | | +---+ |
+ ---->| |checked-in=V4 | +---+ | a | | |V6 |
+ / +---+ | | ------>| +---+ |
+ / | | / | +---------+
+ +---+ | +---+ |
+ /x | |checked-in=V2 | | |V2 |
+ +---+ | +---+ | VH24
+ \ | | \ | b +---------+
+ \ b +---+ | | ------>| +---+ |
+ ---->| |checked-in=V8 | +---+ | | | |V7 |
+ +---+ | | |V3 | | +---+ |
+ | +---+ | | | |
+ +---------+ | | |
+ | +---+ |
+ | | |V8 |
+ | +---+ |
+ | | |
+ | | |
+ | +---+ |
+ | | |V9 |
+ | +---+ |
+ +---------+
+
+ For any request (e.g., DELETE, MOVE, COPY) that modifies a version-
+ controlled binding of a checked-in version-controlled collection, the
+ request MUST fail unless the version-controlled collection has a
+ DAV:auto-version property that will automatically check out the
+ version-controlled collection when it is modified.
+
+ Although a collection version only records the version-controlled
+ bindings of a collection, a version-controlled collection MAY contain
+ both version-controlled and non-version-controlled bindings. Non-
+
+
+
+Clemm, et al. Standards Track [Page 101]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ version-controlled bindings are not under version control, and
+ therefore can be added or deleted without checking out the version-
+ controlled collection.
+
+ Note that a collection version captures only a defined subset of the
+ state of a collection. In particular, a version of a collection
+ captures its dead properties and its bindings to version-controlled
+ resources, but not its live properties or bindings to non-version-
+ controlled resources.
+
+ When a server supports the working-resource feature, a client can
+ check out a collection version to create a working collection.
+ Unlike a version-controlled collection, which contains bindings to
+ version-controlled resources and non-version-controlled resources, a
+ working collection contains bindings to version history resources and
+ non-version-controlled resources. In particular, a working
+ collection is initialized to contain bindings to the version history
+ resources specified by the DAV:version-controlled-binding-set of the
+ checked out collection version. The members of a working collection
+ can then be deleted or moved to another working collection. Non-
+ version-controlled resources can be added to a working collection
+ with methods such as PUT, COPY, and MKCOL. When a working collection
+ is checked in, a VERSION-CONTROL request is automatically applied to
+ every non-version-controlled member of the working collection, and
+ each non-version-controlled member is replaced by its newly created
+ version history. The DAV:version-controlled-binding-set of the new
+ version resulting from checking in a working collection contains the
+ binding name and version history URL for each member of the working
+ collection.
+
+14.1 Version-Controlled Collection Properties
+
+ A version-controlled collection has all the properties of a
+ collection and of a version-controlled resource. In addition, the
+ version-controlled-collection feature introduces the following
+ REQUIRED property for a version-controlled collection.
+
+14.1.1 DAV:eclipsed-set (computed)
+
+ This property identifies the non-version-controlled internal members
+ of the collection that currently are eclipsing a version-controlled
+ internal member of the collection.
+
+ !ELEMENT eclipsed-set (binding-name*)>
+ <!ELEMENT binding-name (#PCDATA)>
+ PCDATA value: URL segment
+
+
+
+
+
+Clemm, et al. Standards Track [Page 102]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ An UPDATE or MERGE request can give a version-controlled collection a
+ version-controlled internal member that has the same name as an
+ existing non-version-controlled internal member. In this case, the
+ non-version-controlled internal member takes precedence and is said
+ to "eclipse" the new versioned-controlled internal member. If the
+ non-version-controlled internal member is removed (e.g., by a DELETE
+ or MOVE), the version-controlled internal member is exposed.
+
+14.2 Collection Version Properties
+
+ A collection version has all the properties of a version. In
+ addition, the version-controlled-collection feature introduces the
+ following REQUIRED property for a collection version.
+
+14.2.1 DAV:version-controlled-binding-set (protected)
+
+ This property captures the name and version-history of each version-
+ controlled internal member of a collection.
+
+ <!ELEMENT version-controlled-binding-set
+ (version-controlled-binding*)>
+ <!ELEMENT version-controlled-binding
+ (binding-name, version-history)>
+ <!ELEMENT binding-name (#PCDATA)>
+ PCDATA value: URL segment
+ <!ELEMENT version-history (href)>
+
+14.3 Additional OPTIONS Semantics
+
+ If the server supports the version-controlled-collection feature, it
+ MUST include "version-controlled-collection" as a field in the DAV
+ response header from an OPTIONS request on any resource that supports
+ any versioning properties, reports, or methods.
+
+14.4 Additional DELETE Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-modify-checked-in-parent): If the request-URL
+ identifies a version-controlled resource, the DELETE MUST fail
+ when the collection containing the version-controlled resource is
+ a checked-in version-controlled collection, unless DAV:auto-
+ version semantics will automatically check out the version-
+ controlled collection.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 103]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+14.5 Additional MKCOL 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:
+
+ If the new collection is automatically put under version control,
+ all postconditions for VERSION-CONTROL apply to the request.
+
+14.6 Additional COPY Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-copy-collection-version): If the source of the request
+ is a collection version, the request MUST fail.
+
+14.7 Additional MOVE Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-modify-checked-in-parent): If the source of the
+ request is a version-controlled resource, the request MUST fail
+ when the collection containing the source is a checked-in
+ version-controlled collection, unless DAV:auto-version semantics
+ will automatically check out that version-controlled collection.
+
+ (DAV:cannot-modify-destination-checked-in-parent): If the source
+ of the request is a version-controlled resource, the request MUST
+ fail when the collection containing the destination is a checked-
+ in version-controlled collection, unless DAV:auto-version
+ semantics will automatically check out that version-controlled
+ collection.
+
+14.8 Additional VERSION-CONTROL Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-modify-checked-in-parent): If the parent of the
+ request-URL is a checked-in version-controlled collection, the
+ request MUST fail unless DAV:auto-version semantics will
+ automatically check out that version-controlled collection.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 104]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Postconditions:
+
+ (DAV:new-version-controlled-collection): If the request body
+ identified a collection version, the collection at the request-URL
+ MUST contain a version-controlled internal member for each
+ DAV:version-controlled-binding specified in the DAV:version-
+ controlled-binding-set of the collection version, where the name
+ and DAV:version-history of the internal member MUST be the
+ DAV:binding-name and the DAV:version-history specified by the
+ DAV:version-controlled-binding. If the internal member is a
+ member of a workspace, and there is another member of the
+ workspace for the same version history, those two members MUST
+ identify the same version-controlled resource; otherwise, a
+ VERSION-CONTROL request with a server selected version of the
+ version history MUST have been applied to the URL for that
+ internal member.
+
+14.9 Additional CHECKOUT Semantics
+
+ Additional Postconditions:
+
+ (DAV:initialize-version-history-bindings): If the request has been
+ applied to a collection version, the new working collection MUST
+ be initialized to contain a binding to each of the history
+ resources identified in the DAV:version-controlled-binding-set of
+ that collection version.
+
+14.10 Additional CHECKIN Semantics
+
+ Additional Postconditions:
+
+ (DAV:initialize-version-controlled-bindings): If the request-URL
+ identified a version-controlled collection, then the DAV:version-
+ controlled-binding-set of the new collection version MUST contain
+ a DAV:version-controlled-binding that identifies the binding name
+ and version history for each version-controlled binding of the
+ version- controlled collection.
+
+ (DAV:version-control-working-collection-members): If the request-
+ URL identified a working collection, a VERSION-CONTROL request
+ MUST have been automatically applied to every non-version-
+ controlled member of the working collection, and each non-
+ version-controlled member MUST have been replaced by its newly
+ created version history. If a working collection member was a
+ non-version-controlled collection, every member of the non-
+ version-controlled collection MUST have been placed under version
+
+
+
+
+
+Clemm, et al. Standards Track [Page 105]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ control before the non-version-controlled collection was placed
+ under version control. The DAV:version-controlled-binding-set of
+ the new collection version MUST contain a DAV:version-controlled-
+ binding that identifies the binding name and the version history
+ URL for each member of the working collection.
+
+14.11 Additional UPDATE and MERGE Semantics
+
+ Additional Postconditions:
+
+ (DAV:update-version-controlled-collection-members): If the request
+ modified the DAV:checked-in version of a version-controlled
+ collection, then the version-controlled members of that version-
+ controlled collection MUST have been updated. In particular:
+
+ - A version-controlled internal member MUST have been deleted if
+ its version history is not identified by the DAV:version-
+ controlled-binding-set of the new DAV:checked-in version.
+ - A version-controlled internal member for a given version
+ history MUST have been renamed if its binding name differs from
+ the DAV:binding-name for that version history in the
+ DAV:version-controlled-binding-set of the new DAV:checked-in
+ version.
+ - A new version-controlled internal member MUST have been created
+ when a version history is identified by the DAV:version-
+ controlled-binding-set of the DAV:checked-in version, but there
+ was no member of the version-controlled collection for that
+ version history. If a new version-controlled member is in a
+ workspace that already has a version-controlled resource for
+ that version history, then the new version-controlled member
+ MUST be just a binding (i.e., another name for) that existing
+ version-controlled resource. Otherwise, the content and dead
+ properties of the new version-controlled member MUST have been
+ initialized to be those of the version specified for that
+ version history by the request. If no version is specified for
+ that version history by the request, the version selected is
+ server defined.
+
+15 Internationalization Considerations
+
+ This specification has been designed to be compliant with the IETF
+ Policy on Character Sets and Languages [RFC2277]. Specifically,
+ where human-readable strings exist in the protocol, either their
+ charset is explicitly stated, or XML mechanisms are used to specify
+ the charset used. Additionally, these human-readable strings all
+ have the ability to express the natural language of the string.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 106]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Most of the human-readable strings in this protocol appear in
+ properties, such as DAV:creator-displayname. As defined by RFC 2518,
+ properties have their values marshaled as XML. XML has explicit
+ provisions for character set tagging and encoding, and requires that
+ XML processors read XML elements encoded, at minimum, using the UTF-8
+ [RFC2279] encoding of the ISO 10646 multilingual plane. The charset
+ parameter of the Content-Type header, together with the XML
+ "encoding" attribute, provide charset identification information for
+ MIME and XML processors. Proper use of the charset header with XML
+ is described in RFC 3023. XML also provides a language tagging
+ capability for specifying the language of the contents of a
+ particular XML element. XML uses either IANA registered language
+ tags (see RFC 3066) or ISO 639 language tags in the "xml:lang"
+ attribute of an XML element to identify the language of its content
+ and attributes.
+
+ DeltaV applications, since they build upon WebDAV, are subject to the
+ internationalization requirements specified in RFC 2518, Section 16.
+ In brief, these requirements mandate the use of XML character set
+ tagging, character set encoding, and language tagging capabilities.
+ Additionally, they strongly recommend reading RFC 3023 for
+ instruction on the use of MIME media types for XML transport and the
+ use of the charset header.
+
+ Within this specification, a label is a human-readable string that is
+ marshaled in the Label header and as XML in request entity bodies.
+ When used in the Label header, the value of the label is URL-escaped
+ and encoded using UTF-8.
+
+16 Security Considerations
+
+ All of the security considerations of WebDAV discussed in RFC 2518,
+ Section 17 also apply to WebDAV versioning. Some aspects of the
+ versioning protocol help address security risks introduced by WebDAV,
+ but other aspects can increase these security risks. These issues
+ are detailed below.
+
+16.1 Auditing and Traceability
+
+ WebDAV increases the ease with which a remote client can modify
+ resources on a web site, but this also increases the risk of
+ important information being overwritten and lost, either through user
+ error or user maliciousness. The use of WebDAV versioning can help
+ address this problem by guaranteeing that previous information is
+ saved in the form of immutable versions, and therefore is easily
+ available for retrieval or restoration. In addition, the version
+ history provides a log of when changes were made, and by whom. When
+ requests are appropriately authenticated, the history mechanism
+
+
+
+Clemm, et al. Standards Track [Page 107]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ provides a clear audit trail for changes to web resources. This can
+ often significantly improve the ability to identify the source of the
+ security problem, and thereby help guard against it in the future.
+
+16.2 Increased Need for Access Control
+
+ WebDAV versioning provides a variety of links between related pieces
+ of information. This can increase the risk that authentication or
+ authorization errors allow a client to locate sensitive information.
+ For example, if version history is not appropriately protected by
+ access control, a client can use the version history of a public
+ resource to identify later versions of that resource that the user
+ intended to keep private. This increases the need for reliable
+ authentication and accurate authorization.
+
+ A WebDAV versioning client should be designed to handle a mixture of
+ 200 (OK) and 403 (Forbidden) responses on attempts to access the
+ properties and reports that are supported by a resource. For
+ example, a particular user may be authorized to access the content
+ and dead properties of a version-controlled resource, but not be
+ authorized to access the DAV:checked-in, DAV:checked-out, or
+ DAV:version-history properties of that resource.
+
+16.3 Security Through Obscurity
+
+ While it is acknowledged that "obscurity" is not an effective means
+ of security, it is often a good technique to keep honest people
+ honest. Within this protocol, version URLs, version history URLs,
+ and working resource URLs are generated by the server and can be
+ properly obfuscated so as not to draw attention to them. For
+ example, a version of "http://foobar.com/reviews/salaries.html" might
+ be assigned a URL such as "http://foobar.com/repo/4934943".
+
+16.4 Denial of Service
+
+ The auto-versioning mechanism provided by WebDAV can result in a
+ large number of resources being created on the server, since each
+ update to a resource could potentially result in the creation of a
+ new version resource. This increases the risk of a denial of service
+ attack that exhausts the storage capability of a server. This risk
+ is especially significant because it can be an unintentional result
+ of something like an aggressive auto-save feature provided by an
+ editing client. A server can decrease this risk by using delta
+ storage techniques to minimize the cost of additional versions, and
+ by limiting auto-versioning to a locking client, and thereby
+ decreasing the number of inadvertent version creations.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 108]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+17 IANA Considerations
+
+ This document uses the namespace defined by RFC 2518 for XML
+ elements. All other IANA considerations from RFC 2518 are also
+ applicable to WebDAV Versioning.
+
+18 Intellectual Property
+
+ The following notice is copied from RFC 2026, Section 10.4, and
+ describes the position of the IETF concerning intellectual property
+ claims made against this document.
+
+ The IETF takes no position regarding the validity or scope of any
+ intellectual property or other rights that might be claimed to
+ pertain to the implementation or use other technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; neither does it represent that it
+ has made any effort to identify any such rights. Information on the
+ procedures of the IETF with respect to rights in standards-track and
+ standards-related documentation can be found in BCP-11. Copies of
+ claims of rights made available for publication and any assurances of
+ licenses to be made available, or the result of an attempt made to
+ obtain a general license or permission for the use of such
+ proprietary rights by implementers or users of this specification can
+ be obtained from the IETF Secretariat.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to practice
+ this standard. Please address the information to the IETF Executive
+ Director.
+
+19 Acknowledgements
+
+ This protocol is the collaborative product of the authors and the
+ rest of the DeltaV design team: Boris Bokowski, Bruce Cragun
+ (Novell), Jim Doubek (Macromedia), David Durand (INSO), Lisa
+ Dusseault (Xythos), Chuck Fay (FileNet), Yaron Goland, Mark Hale
+ (Interwoven), Henry Harbury (Merant), James Hunt, Jeff McAffer (OTI),
+ Peter Raymond (Merant), Juergen Reuter, Edgar Schwarz (Marconi), Eric
+ Sedlar (Oracle), Bradley Sergeant, Greg Stein, and John Vasta
+ (Rational). We would like to acknowledge the foundation laid for us
+ by the authors of the WebDAV and HTTP protocols upon which this
+ protocol is layered, and the invaluable feedback from the WebDAV and
+ DeltaV working groups.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 109]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+20 References
+
+ [ISO639] ISO, "Code for the representation of names of languages",
+ ISO 639:1988, 1998.
+
+ [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
+ 3", BCP 9, RFC 2026, October 1996.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
+ Languages", BCP 18, RFC 2277, January 1998.
+
+ [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
+ RFC 2279, January 1998.
+
+ [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
+ Resource Identifiers (URI): Generic Syntax", RFC 2396,
+ August 1998.
+
+ [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D.
+ Jensen, "HTTP Extensions for Distributed Authoring -
+ WEBDAV", RFC 2518, February 1999.
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter,
+ L., Leach, P. and T.Berners-Lee, "Hypertext Transfer
+ Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+ [RFC3023] Murata, M., St.Laurent, S. and D. Kohn, "XML Media Types",
+ RFC 3023, January 2001.
+
+ [RFC3066] Alvestrand, H., "Tags for the Identification of Languages",
+ BCP 47, RFC 3066, January 2001.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 110]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+Appendix A - Resource Classification
+
+ This document introduces several different kinds of versioning
+ resources, such as version-controlled resources, versions, checked-
+ out resources, and version history resources. As clients discover
+ resources on a server, they may find it useful to classify those
+ resources (for example, to make UI decisions on choice of icon and
+ menu options).
+
+ Clients should classify a resource by examining the values of the
+ DAV:supported-method-set (see Section 3.1.3) and DAV:supported-live-
+ property-set (see Section 3.1.4) properties of that resource.
+
+ The following list shows the supported live properties and methods
+ for each kind of versioning resource. Where an optional feature
+ introduces a new kind of versioning resource, that feature is noted
+ in parentheses following the name of that kind of versioning
+ resource. If a live property or method is optional for a kind of
+ versioning resource, the feature that introduces that live property
+ or method is noted in parentheses following the live property or
+ method name.
+
+A.1 DeltaV-Compliant Unmapped URL (a URL that identifies no resource)
+
+ Supported methods:
+
+ - PUT [RFC2616]
+ - MKCOL [RFC2518]
+ - MKACTIVITY (activity)
+ - VERSION-CONTROL (workspace)
+ - MKWORKSPACE (workspace)
+
+A.2 DeltaV-Compliant Resource
+
+ Supported live properties:
+
+ - DAV:comment
+ - DAV:creator-displayname
+ - DAV:supported-method-set
+ - DAV:supported-live-property-set
+ - DAV:supported-report-set
+ - all properties defined in WebDAV [RFC2518].
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 111]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Supported methods:
+
+ - REPORT
+ - all methods defined in WebDAV [RFC2518]
+ - all methods defined in HTTP/1.1 [RFC2616].
+
+A.3 DeltaV-Compliant Collection
+
+ Supported live properties:
+
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - BASELINE-CONTROL (baseline)
+ - all DeltaV-compliant resource methods.
+
+A.4 Versionable Resource
+
+ Supported live properties:
+
+ - DAV:workspace (workspace)
+ - DAV:version-controlled-configuration (baseline)
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - VERSION-CONTROL
+ - all DeltaV-compliant resource methods.
+
+A.5 Version-Controlled Resource
+
+ Supported live properties:
+
+ - DAV:auto-version
+ - DAV:version-history (version-history)
+ - DAV:workspace (workspace)
+ - DAV:version-controlled-configuration (baseline)
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - VERSION-CONTROL
+ - MERGE (merge)
+ - all DeltaV-compliant resource methods.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 112]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+A.6 Version
+
+ Supported live properties:
+
+ - DAV:predecessor-set
+ - DAV:successor-set
+ - DAV:checkout-set
+ - DAV:version-name
+ - DAV:checkout-fork (in-place-checkout or working resource)
+ - DAV:checkin-fork (in-place-checkout or working resource)
+ - DAV:version-history (version-history)
+ - DAV:label-name-set (label)
+ - DAV:activity-set (activity)
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - LABEL (label)
+ - CHECKOUT (working-resource)
+ - all DeltaV-compliant resource methods.
+
+A.7 Checked-In Version-Controlled Resource
+
+ Supported live properties:
+
+ - DAV:checked-in
+ - all version-controlled resource properties.
+
+ Supported methods:
+
+ - CHECKOUT (checkout-in-place)
+ - UPDATE (update)
+ - all version-controlled resource methods.
+
+A.8 Checked-Out Resource
+
+ Supported live properties:
+
+ - DAV:checked-out
+ - DAV:predecessor-set
+ - DAV:checkout-fork (in-place-checkout or working resource)
+ - DAV:checkin-fork (in-place-checkout or working resource)
+ - DAV:merge-set (merge)
+ - DAV:auto-merge-set (merge)
+ - DAV:unreserved (activity)
+ - DAV:activity-set (activity)
+
+
+
+
+
+Clemm, et al. Standards Track [Page 113]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Supported methods:
+
+ - CHECKIN (checkout-in-place or working-resource)
+ - all DeltaV-compliant resource methods.
+
+A.9 Checked-Out Version-Controlled Resource (checkout-in-place)
+
+ Supported live properties:
+
+ - all version-controlled resource properties.
+ - all checked-out resource properties.
+
+ Supported methods:
+
+ - UNCHECKOUT
+ - all version-controlled resource methods.
+ - all checked-out resource methods.
+
+A.10 Working Resource (working-resource)
+
+ Supported live properties:
+
+ - all DeltaV-compliant resource properties
+ - all checked-out resource properties
+ - DAV:auto-update.
+
+ Supported methods:
+
+ - all checked-out resource methods.
+
+A.11 Version History (version-history)
+
+ Supported live properties:
+
+ - DAV:version-set
+ - DAV:root-version
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - all DeltaV-compliant resource methods.
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 114]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+A.12 Workspace (workspace)
+
+ Supported live properties:
+
+ - DAV:workspace-checkout-set
+ - DAV:baseline-controlled-collection-set (baseline)
+ - DAV:current-activity-set (activity)
+ - all DeltaV-compliant collection properties.
+
+ Supported methods:
+
+ - all DeltaV-compliant collection methods.
+
+A.13 Activity (activity)
+
+ Supported live properties:
+
+ - DAV:activity-version-set
+ - DAV:activity-checkout-set
+ - DAV:subactivity-set
+ - DAV:current-workspace-set
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - all DeltaV-compliant resource methods.
+
+A.14 Version-Controlled Collection (version-controlled-collection)
+
+ Supported live properties:
+
+ - DAV:eclipsed-set
+ - all version-controlled resource properties.
+
+ Supported methods:
+
+ - all version-controlled resource methods.
+
+A.15 Collection Version (version-controlled-collection)
+
+ Supported live properties:
+
+ - DAV:version-controlled-binding-set
+ - all version properties.
+
+ Supported methods:
+
+ - all version methods.
+
+
+
+Clemm, et al. Standards Track [Page 115]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+A.16 Version-Controlled Configuration (baseline)
+
+ Supported live properties:
+
+ - DAV:baseline-controlled-collection
+ - all version-controlled resource properties.
+
+ Supported methods:
+
+ - all version-controlled resource methods.
+
+A.17 Baseline (baseline)
+
+ Supported live properties:
+
+ - DAV:baseline-collection
+ - DAV:subbaseline-set
+ - all version properties.
+
+ Supported methods:
+
+ - all version methods.
+
+A.18 Checked-Out Version-Controlled Configuration (baseline)
+
+ Supported live properties:
+
+ - DAV:subbaseline-set
+ - all version-controlled configuration properties.
+
+ Supported methods:
+
+ - all version-controlled configuration methods.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 116]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+Authors' Addresses
+
+ Geoffrey Clemm
+ Rational Software
+ 20 Maguire Road, Lexington, MA 02421
+
+ EMail: geoffrey.clemm@rational.com
+
+
+ Jim Amsden
+ IBM
+ 3039 Cornwallis, Research Triangle Park, NC 27709
+
+ EMail: jamsden@us.ibm.com
+
+
+ Tim Ellison
+ IBM
+ Hursley Park, Winchester, UK S021 2JN
+
+ EMail: tim_ellison@uk.ibm.com
+
+
+ Christopher Kaler
+ Microsoft
+ One Microsoft Way, Redmond, WA 90852
+
+ EMail: ckaler@microsoft.com
+
+
+ Jim Whitehead
+ UC Santa Cruz, Dept. of Computer Science
+ 1156 High Street, Santa Cruz, CA 95064
+
+ EMail: ejw@cse.ucsc.edu
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 117]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 118]
+
diff --git a/docs/rfcs/rfc4918.txt b/docs/rfcs/rfc4918.txt
new file mode 100644
index 0000000..4ef181b
--- /dev/null
+++ b/docs/rfcs/rfc4918.txt
@@ -0,0 +1,7115 @@
+
+
+
+
+
+
+Network Working Group L. Dusseault, Ed.
+Request for Comments: 4918 CommerceNet
+Obsoletes: 2518 June 2007
+Category: Standards Track
+
+
+ HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)
+
+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 IETF Trust (2007).
+
+Abstract
+
+ Web Distributed Authoring and Versioning (WebDAV) consists of a set
+ of methods, headers, and content-types ancillary to HTTP/1.1 for the
+ management of resource properties, creation and management of
+ resource collections, URL namespace manipulation, and resource
+ locking (collision avoidance).
+
+ RFC 2518 was published in February 1999, and this specification
+ obsoletes RFC 2518 with minor revisions mostly due to
+ interoperability experience.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 1]
+
+RFC 4918 WebDAV June 2007
+
+
+Table of Contents
+
+ 1. Introduction ....................................................7
+ 2. Notational Conventions ..........................................8
+ 3. Terminology .....................................................8
+ 4. Data Model for Resource Properties .............................10
+ 4.1. The Resource Property Model ...............................10
+ 4.2. Properties and HTTP Headers ...............................10
+ 4.3. Property Values ...........................................10
+ 4.3.1. Example - Property with Mixed Content ..............12
+ 4.4. Property Names ............................................14
+ 4.5. Source Resources and Output Resources .....................14
+ 5. Collections of Web Resources ...................................14
+ 5.1. HTTP URL Namespace Model ..................................15
+ 5.2. Collection Resources ......................................15
+ 6. Locking ........................................................17
+ 6.1. Lock Model ................................................18
+ 6.2. Exclusive vs. Shared Locks ................................19
+ 6.3. Required Support ..........................................20
+ 6.4. Lock Creator and Privileges ...............................20
+ 6.5. Lock Tokens ...............................................21
+ 6.6. Lock Timeout ..............................................21
+ 6.7. Lock Capability Discovery .................................22
+ 6.8. Active Lock Discovery .....................................22
+ 7. Write Lock .....................................................23
+ 7.1. Write Locks and Properties ................................24
+ 7.2. Avoiding Lost Updates .....................................24
+ 7.3. Write Locks and Unmapped URLs .............................25
+ 7.4. Write Locks and Collections ...............................26
+ 7.5. Write Locks and the If Request Header .....................28
+ 7.5.1. Example - Write Lock and COPY ......................28
+ 7.5.2. Example - Deleting a Member of a Locked
+ Collection .........................................29
+ 7.6. Write Locks and COPY/MOVE .................................30
+ 7.7. Refreshing Write Locks ....................................30
+ 8. General Request and Response Handling ..........................31
+ 8.1. Precedence in Error Handling ..............................31
+ 8.2. Use of XML ................................................31
+ 8.3. URL Handling ..............................................32
+ 8.3.1. Example - Correct URL Handling .....................32
+ 8.4. Required Bodies in Requests ...............................33
+ 8.5. HTTP Headers for Use in WebDAV ............................33
+ 8.6. ETag ......................................................33
+ 8.7. Including Error Response Bodies ...........................34
+ 8.8. Impact of Namespace Operations on Cache Validators ........34
+ 9. HTTP Methods for Distributed Authoring .........................35
+ 9.1. PROPFIND Method ...........................................35
+ 9.1.1. PROPFIND Status Codes ..............................37
+
+
+
+Dusseault Standards Track [Page 2]
+
+RFC 4918 WebDAV June 2007
+
+
+ 9.1.2. Status Codes for Use in 'propstat' Element .........37
+ 9.1.3. Example - Retrieving Named Properties ..............38
+ 9.1.4. Example - Using 'propname' to Retrieve All
+ Property Names .....................................39
+ 9.1.5. Example - Using So-called 'allprop' ................41
+ 9.1.6. Example - Using 'allprop' with 'include' ...........43
+ 9.2. PROPPATCH Method ..........................................44
+ 9.2.1. Status Codes for Use in 'propstat' Element .........44
+ 9.2.2. Example - PROPPATCH ................................45
+ 9.3. MKCOL Method ..............................................46
+ 9.3.1. MKCOL Status Codes .................................47
+ 9.3.2. Example - MKCOL ....................................47
+ 9.4. GET, HEAD for Collections .................................48
+ 9.5. POST for Collections ......................................48
+ 9.6. DELETE Requirements .......................................48
+ 9.6.1. DELETE for Collections .............................49
+ 9.6.2. Example - DELETE ...................................49
+ 9.7. PUT Requirements ..........................................50
+ 9.7.1. PUT for Non-Collection Resources ...................50
+ 9.7.2. PUT for Collections ................................51
+ 9.8. COPY Method ...............................................51
+ 9.8.1. COPY for Non-collection Resources ..................51
+ 9.8.2. COPY for Properties ................................52
+ 9.8.3. COPY for Collections ...............................52
+ 9.8.4. COPY and Overwriting Destination Resources .........53
+ 9.8.5. Status Codes .......................................54
+ 9.8.6. Example - COPY with Overwrite ......................55
+ 9.8.7. Example - COPY with No Overwrite ...................55
+ 9.8.8. Example - COPY of a Collection .....................56
+ 9.9. MOVE Method ...............................................56
+ 9.9.1. MOVE for Properties ................................57
+ 9.9.2. MOVE for Collections ...............................57
+ 9.9.3. MOVE and the Overwrite Header ......................58
+ 9.9.4. Status Codes .......................................59
+ 9.9.5. Example - MOVE of a Non-Collection .................60
+ 9.9.6. Example - MOVE of a Collection .....................60
+ 9.10. LOCK Method ..............................................61
+ 9.10.1. Creating a Lock on an Existing Resource ...........61
+ 9.10.2. Refreshing Locks ..................................62
+ 9.10.3. Depth and Locking .................................62
+ 9.10.4. Locking Unmapped URLs .............................63
+ 9.10.5. Lock Compatibility Table ..........................63
+ 9.10.6. LOCK Responses ....................................63
+ 9.10.7. Example - Simple Lock Request .....................64
+ 9.10.8. Example - Refreshing a Write Lock .................65
+ 9.10.9. Example - Multi-Resource Lock Request .............66
+ 9.11. UNLOCK Method ............................................68
+ 9.11.1. Status Codes ......................................68
+
+
+
+Dusseault Standards Track [Page 3]
+
+RFC 4918 WebDAV June 2007
+
+
+ 9.11.2. Example - UNLOCK ..................................69
+ 10. HTTP Headers for Distributed Authoring ........................69
+ 10.1. DAV Header ...............................................69
+ 10.2. Depth Header .............................................70
+ 10.3. Destination Header .......................................71
+ 10.4. If Header ................................................72
+ 10.4.1. Purpose ...........................................72
+ 10.4.2. Syntax ............................................72
+ 10.4.3. List Evaluation ...................................73
+ 10.4.4. Matching State Tokens and ETags ...................74
+ 10.4.5. If Header and Non-DAV-Aware Proxies ...............74
+ 10.4.6. Example - No-tag Production .......................75
+ 10.4.7. Example - Using "Not" with No-tag Production ......75
+ 10.4.8. Example - Causing a Condition to Always
+ Evaluate to True ..................................75
+ 10.4.9. Example - Tagged List If Header in COPY ...........76
+ 10.4.10. Example - Matching Lock Tokens with
+ Collection Locks .................................76
+ 10.4.11. Example - Matching ETags on Unmapped URLs ........76
+ 10.5. Lock-Token Header ........................................77
+ 10.6. Overwrite Header .........................................77
+ 10.7. Timeout Request Header ...................................78
+ 11. Status Code Extensions to HTTP/1.1 ............................78
+ 11.1. 207 Multi-Status .........................................78
+ 11.2. 422 Unprocessable Entity .................................78
+ 11.3. 423 Locked ...............................................78
+ 11.4. 424 Failed Dependency ....................................79
+ 11.5. 507 Insufficient Storage .................................79
+ 12. Use of HTTP Status Codes ......................................79
+ 12.1. 412 Precondition Failed ..................................79
+ 12.2. 414 Request-URI Too Long .................................79
+ 13. Multi-Status Response .........................................80
+ 13.1. Response Headers .........................................80
+ 13.2. Handling Redirected Child Resources ......................81
+ 13.3. Internal Status Codes ....................................81
+ 14. XML Element Definitions .......................................81
+ 14.1. activelock XML Element ...................................81
+ 14.2. allprop XML Element ......................................82
+ 14.3. collection XML Element ...................................82
+ 14.4. depth XML Element ........................................82
+ 14.5. error XML Element ........................................82
+ 14.6. exclusive XML Element ....................................83
+ 14.7. href XML Element .........................................83
+ 14.8. include XML Element ......................................83
+ 14.9. location XML Element .....................................83
+ 14.10. lockentry XML Element ...................................84
+ 14.11. lockinfo XML Element ....................................84
+ 14.12. lockroot XML Element ....................................84
+
+
+
+Dusseault Standards Track [Page 4]
+
+RFC 4918 WebDAV June 2007
+
+
+ 14.13. lockscope XML Element ...................................84
+ 14.14. locktoken XML Element ...................................85
+ 14.15. locktype XML Element ....................................85
+ 14.16. multistatus XML Element .................................85
+ 14.17. owner XML Element .......................................85
+ 14.18. prop XML Element ........................................86
+ 14.19. propertyupdate XML Element ..............................86
+ 14.20. propfind XML Element ....................................86
+ 14.21. propname XML Element ....................................87
+ 14.22. propstat XML Element ....................................87
+ 14.23. remove XML Element ......................................87
+ 14.24. response XML Element ....................................88
+ 14.25. responsedescription XML Element .........................88
+ 14.26. set XML Element .........................................88
+ 14.27. shared XML Element ......................................89
+ 14.28. status XML Element ......................................89
+ 14.29. timeout XML Element .....................................89
+ 14.30. write XML Element .......................................89
+ 15. DAV Properties ................................................90
+ 16. Precondition/Postcondition XML Elements .......................98
+ 17. XML Extensibility in DAV .....................................101
+ 18. DAV Compliance Classes .......................................103
+ 18.1. Class 1 .................................................103
+ 18.2. Class 2 .................................................103
+ 18.3. Class 3 .................................................103
+ 19. Internationalization Considerations ..........................104
+ 20. Security Considerations ......................................105
+ 20.1. Authentication of Clients ...............................105
+ 20.2. Denial of Service .......................................106
+ 20.3. Security through Obscurity ..............................106
+ 20.4. Privacy Issues Connected to Locks .......................106
+ 20.5. Privacy Issues Connected to Properties ..................107
+ 20.6. Implications of XML Entities ............................107
+ 20.7. Risks Connected with Lock Tokens ........................108
+ 20.8. Hosting Malicious Content ...............................108
+ 21. IANA Considerations ..........................................109
+ 21.1. New URI Schemes .........................................109
+ 21.2. XML Namespaces ..........................................109
+ 21.3. Message Header Fields ...................................109
+ 21.3.1. DAV ..............................................109
+ 21.3.2. Depth ............................................110
+ 21.3.3. Destination ......................................110
+ 21.3.4. If ...............................................110
+ 21.3.5. Lock-Token .......................................110
+ 21.3.6. Overwrite ........................................111
+ 21.3.7. Timeout ..........................................111
+ 21.4. HTTP Status Codes .......................................111
+ 22. Acknowledgements .............................................112
+
+
+
+Dusseault Standards Track [Page 5]
+
+RFC 4918 WebDAV June 2007
+
+
+ 23. Contributors to This Specification ...........................113
+ 24. Authors of RFC 2518 ..........................................113
+ 25. References ...................................................114
+ 25.1. Normative References.....................................114
+ 25.2. Informative References ..................................115
+ Appendix A. Notes on Processing XML Elements ....................117
+ A.1. Notes on Empty XML Elements ..............................117
+ A.2. Notes on Illegal XML Processing ..........................117
+ A.3. Example - XML Syntax Error ...............................117
+ A.4. Example - Unexpected XML Element .........................118
+ Appendix B. Notes on HTTP Client Compatibility ...................119
+ Appendix C. The 'opaquelocktoken' Scheme and URIs ................120
+ Appendix D. Lock-null Resources ..................................120
+ D.1. Guidance for Clients Using LOCK to Create Resources ......121
+ Appendix E. Guidance for Clients Desiring to Authenticate ........121
+ Appendix F. Summary of Changes from RFC 2518 .....................123
+ F.1. Changes for Both Client and Server Implementations .......123
+ F.2. Changes for Server Implementations .......................125
+ F.3. Other Changes ............................................126
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 6]
+
+RFC 4918 WebDAV June 2007
+
+
+1. Introduction
+
+ This document describes an extension to the HTTP/1.1 protocol that
+ allows clients to perform remote Web content authoring operations.
+ This extension provides a coherent set of methods, headers, request
+ entity body formats, and response entity body formats that provide
+ operations for:
+
+ Properties: The ability to create, remove, and query information
+ about Web pages, such as their authors, creation dates, etc.
+
+ Collections: The ability to create sets of documents and to retrieve
+ a hierarchical membership listing (like a directory listing in a file
+ system).
+
+ Locking: The ability to keep more than one person from working on a
+ document at the same time. This prevents the "lost update problem",
+ in which modifications are lost as first one author, then another,
+ writes changes without merging the other author's changes.
+
+ Namespace Operations: The ability to instruct the server to copy and
+ move Web resources, operations that change the mapping from URLs to
+ resources.
+
+ Requirements and rationale for these operations are described in a
+ companion document, "Requirements for a Distributed Authoring and
+ Versioning Protocol for the World Wide Web" [RFC2291].
+
+ This document does not specify the versioning operations suggested by
+ [RFC2291]. That work was done in a separate document, "Versioning
+ Extensions to WebDAV" [RFC3253].
+
+ The sections below provide a detailed introduction to various WebDAV
+ abstractions: resource properties (Section 4), collections of
+ resources (Section 5), locks (Section 6) in general, and write locks
+ (Section 7) specifically.
+
+ These abstractions are manipulated by the WebDAV-specific HTTP
+ methods (Section 9) and the extra HTTP headers (Section 10) used with
+ WebDAV methods. General considerations for handling HTTP requests
+ and responses in WebDAV are found in Section 8.
+
+ While the status codes provided by HTTP/1.1 are sufficient to
+ describe most error conditions encountered by WebDAV methods, there
+ are some errors that do not fall neatly into the existing categories.
+ This specification defines extra status codes developed for WebDAV
+ methods (Section 11) and describes existing HTTP status codes
+ (Section 12) as used in WebDAV. Since some WebDAV methods may
+
+
+
+Dusseault Standards Track [Page 7]
+
+RFC 4918 WebDAV June 2007
+
+
+ operate over many resources, the Multi-Status response (Section 13)
+ has been introduced to return status information for multiple
+ resources. Finally, this version of WebDAV introduces precondition
+ and postcondition (Section 16) XML elements in error response bodies.
+
+ WebDAV uses XML ([REC-XML]) for property names and some values, and
+ also uses XML to marshal complicated requests and responses. This
+ specification contains DTD and text definitions of all properties
+ (Section 15) and all other XML elements (Section 14) used in
+ marshalling. WebDAV includes a few special rules on extending WebDAV
+ XML marshalling in backwards-compatible ways (Section 17).
+
+ Finishing off the specification are sections on what it means for a
+ resource to be compliant with this specification (Section 18), on
+ internationalization support (Section 19), and on security
+ (Section 20).
+
+2. Notational Conventions
+
+ Since this document describes a set of extensions to the HTTP/1.1
+ protocol, the augmented BNF used herein to describe protocol elements
+ is exactly the same as described in Section 2.1 of [RFC2616],
+ including the rules about implied linear whitespace. Since this
+ augmented BNF uses the basic production rules provided in Section 2.2
+ of [RFC2616], these rules apply to this document as well. Note this
+ is not the standard BNF syntax used in other RFCs.
+
+ 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 [RFC2119].
+
+ Note that in natural language, a property like the "creationdate"
+ property in the "DAV:" XML namespace is sometimes referred to as
+ "DAV:creationdate" for brevity.
+
+3. Terminology
+
+ URI/URL - A Uniform Resource Identifier and Uniform Resource Locator,
+ respectively. These terms (and the distinction between them) are
+ defined in [RFC3986].
+
+ URI/URL Mapping - A relation between an absolute URI and a resource.
+ Since a resource can represent items that are not network
+ retrievable, as well as those that are, it is possible for a resource
+ to have zero, one, or many URI mappings. Mapping a resource to an
+ "http" scheme URI makes it possible to submit HTTP protocol requests
+ to the resource using the URI.
+
+
+
+
+Dusseault Standards Track [Page 8]
+
+RFC 4918 WebDAV June 2007
+
+
+ Path Segment - Informally, the characters found between slashes ("/")
+ in a URI. Formally, as defined in Section 3.3 of [RFC3986].
+
+ Collection - Informally, a resource that also acts as a container of
+ references to child resources. Formally, a resource that contains a
+ set of mappings between path segments and resources and meets the
+ requirements defined in Section 5.
+
+ Internal Member (of a Collection) - Informally, a child resource of a
+ collection. Formally, a resource referenced by a path segment
+ mapping contained in the collection.
+
+ Internal Member URL (of a Collection) - A URL of an internal member,
+ consisting of the URL of the collection (including trailing slash)
+ plus the path segment identifying the internal member.
+
+ Member (of a Collection) - Informally, a "descendant" of a
+ collection. Formally, an internal member of the collection, or,
+ recursively, a member of an internal member.
+
+ Member URL (of a Collection) - A URL that is either an internal
+ member URL of the collection itself, or is an internal member URL of
+ a member of that collection.
+
+ Property - A name/value pair that contains descriptive information
+ about a resource.
+
+ Live Property - A property whose semantics and syntax are enforced by
+ the server. For example, the live property DAV:getcontentlength has
+ its value, the length of the entity returned by a GET request,
+ automatically calculated by the server.
+
+ Dead Property - A property whose semantics and syntax are not
+ enforced by the server. The server only records the value of a dead
+ property; the client is responsible for maintaining the consistency
+ of the syntax and semantics of a dead property.
+
+ Principal - A distinct human or computational actor that initiates
+ access to network resources.
+
+ State Token - A URI that represents a state of a resource. Lock
+ tokens are the only state tokens defined in this specification.
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 9]
+
+RFC 4918 WebDAV June 2007
+
+
+4. Data Model for Resource Properties
+
+4.1. The Resource Property Model
+
+ Properties are pieces of data that describe the state of a resource.
+ Properties are data about data.
+
+ Properties are used in distributed authoring environments to provide
+ for efficient discovery and management of resources. For example, a
+ 'subject' property might allow for the indexing of all resources by
+ their subject, and an 'author' property might allow for the discovery
+ of what authors have written which documents.
+
+ The DAV property model consists of name/value pairs. The name of a
+ property identifies the property's syntax and semantics, and provides
+ an address by which to refer to its syntax and semantics.
+
+ There are two categories of properties: "live" and "dead". A live
+ property has its syntax and semantics enforced by the server. Live
+ properties include cases where a) the value of a property is
+ protected and maintained by the server, and b) the value of the
+ property is maintained by the client, but the server performs syntax
+ checking on submitted values. All instances of a given live property
+ MUST comply with the definition associated with that property name.
+ A dead property has its syntax and semantics enforced by the client;
+ the server merely records the value of the property verbatim.
+
+4.2. Properties and HTTP Headers
+
+ Properties already exist, in a limited sense, in HTTP message
+ headers. However, in distributed authoring environments, a
+ relatively large number of properties are needed to describe the
+ state of a resource, and setting/returning them all through HTTP
+ headers is inefficient. Thus, a mechanism is needed that allows a
+ principal to identify a set of properties in which the principal is
+ interested and to set or retrieve just those properties.
+
+4.3. Property Values
+
+ The value of a property is always a (well-formed) XML fragment.
+
+ XML has been chosen because it is a flexible, self-describing,
+ structured data format that supports rich schema definitions, and
+ because of its support for multiple character sets. XML's self-
+ describing nature allows any property's value to be extended by
+ adding elements. Clients will not break when they encounter
+ extensions because they will still have the data specified in the
+ original schema and MUST ignore elements they do not understand.
+
+
+
+Dusseault Standards Track [Page 10]
+
+RFC 4918 WebDAV June 2007
+
+
+ XML's support for multiple character sets allows any human-readable
+ property to be encoded and read in a character set familiar to the
+ user. XML's support for multiple human languages, using the "xml:
+ lang" attribute, handles cases where the same character set is
+ employed by multiple human languages. Note that xml:lang scope is
+ recursive, so an xml:lang attribute on any element containing a
+ property name element applies to the property value unless it has
+ been overridden by a more locally scoped attribute. Note that a
+ property only has one value, in one language (or language MAY be left
+ undefined); a property does not have multiple values in different
+ languages or a single value in multiple languages.
+
+ A property is always represented with an XML element consisting of
+ the property name, called the "property name element". The simplest
+ example is an empty property, which is different from a property that
+ does not exist:
+
+ <R:title xmlns:R="http://www.example.com/ns/"></R:title>
+
+ The value of the property appears inside the property name element.
+ The value may be any kind of well-formed XML content, including both
+ text-only and mixed content. Servers MUST preserve the following XML
+ Information Items (using the terminology from [REC-XML-INFOSET]) in
+ storage and transmission of dead properties:
+
+ For the property name Element Information Item itself:
+
+ [namespace name]
+
+ [local name]
+
+ [attributes] named "xml:lang" or any such attribute in scope
+
+ [children] of type element or character
+
+ On all Element Information Items in the property value:
+
+ [namespace name]
+
+ [local name]
+
+ [attributes]
+
+ [children] of type element or character
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 11]
+
+RFC 4918 WebDAV June 2007
+
+
+ On Attribute Information Items in the property value:
+
+ [namespace name]
+
+ [local name]
+
+ [normalized value]
+
+ On Character Information Items in the property value:
+
+ [character code]
+
+ Since prefixes are used in some XML vocabularies (XPath and XML
+ Schema, for example), servers SHOULD preserve, for any Information
+ Item in the value:
+
+ [prefix]
+
+ XML Infoset attributes not listed above MAY be preserved by the
+ server, but clients MUST NOT rely on them being preserved. The above
+ rules would also apply by default to live properties, unless defined
+ otherwise.
+
+ Servers MUST ignore the XML attribute xml:space if present and never
+ use it to change whitespace handling. Whitespace in property values
+ is significant.
+
+4.3.1. Example - Property with Mixed Content
+
+ Consider a dead property 'author' created by the client as follows:
+
+ <D:prop xml:lang="en" xmlns:D="DAV:">
+ <x:author xmlns:x='http://example.com/ns'>
+ <x:name>Jane Doe</x:name>
+ <!-- Jane's contact info -->
+ <x:uri type='email'
+ added='2005-11-26'>mailto:jane.doe@example.com</x:uri>
+ <x:uri type='web'
+ added='2005-11-27'>http://www.example.com</x:uri>
+ <x:notes xmlns:h='http://www.w3.org/1999/xhtml'>
+ Jane has been working way <h:em>too</h:em> long on the
+ long-awaited revision of <![CDATA[<RFC2518>]]>.
+ </x:notes>
+ </x:author>
+ </D:prop>
+
+
+
+
+
+
+Dusseault Standards Track [Page 12]
+
+RFC 4918 WebDAV June 2007
+
+
+ When this property is requested, a server might return:
+
+ <D:prop xmlns:D='DAV:'><author
+ xml:lang='en'
+ xmlns:x='http://example.com/ns'
+ xmlns='http://example.com/ns'
+ xmlns:h='http://www.w3.org/1999/xhtml'>
+ <x:name>Jane Doe</x:name>
+ <x:uri added="2005-11-26" type="email"
+ >mailto:jane.doe@example.com</x:uri>
+ <x:uri added="2005-11-27" type="web"
+ >http://www.example.com</x:uri>
+ <x:notes>
+ Jane has been working way <h:em>too</h:em> long on the
+ long-awaited revision of <RFC2518>.
+ </x:notes>
+ </author>
+ </D:prop>
+
+ Note in this example:
+
+ o The [prefix] for the property name itself was not preserved, being
+ non-significant, whereas all other [prefix] values have been
+ preserved,
+
+ o attribute values have been rewritten with double quotes instead of
+ single quotes (quoting style is not significant), and attribute
+ order has not been preserved,
+
+ o the xml:lang attribute has been returned on the property name
+ element itself (it was in scope when the property was set, but the
+ exact position in the response is not considered significant as
+ long as it is in scope),
+
+ o whitespace between tags has been preserved everywhere (whitespace
+ between attributes not so),
+
+ o CDATA encapsulation was replaced with character escaping (the
+ reverse would also be legal),
+
+ o the comment item was stripped (as would have been a processing
+ instruction item).
+
+ Implementation note: there are cases such as editing scenarios where
+ clients may require that XML content is preserved character by
+ character (such as attribute ordering or quoting style). In this
+ case, clients should consider using a text-only property value by
+ escaping all characters that have a special meaning in XML parsing.
+
+
+
+Dusseault Standards Track [Page 13]
+
+RFC 4918 WebDAV June 2007
+
+
+4.4. Property Names
+
+ A property name is a universally unique identifier that is associated
+ with a schema that provides information about the syntax and
+ semantics of the property.
+
+ Because a property's name is universally unique, clients can depend
+ upon consistent behavior for a particular property across multiple
+ resources, on the same and across different servers, so long as that
+ property is "live" on the resources in question, and the
+ implementation of the live property is faithful to its definition.
+
+ The XML namespace mechanism, which is based on URIs ([RFC3986]), is
+ used to name properties because it prevents namespace collisions and
+ provides for varying degrees of administrative control.
+
+ The property namespace is flat; that is, no hierarchy of properties
+ is explicitly recognized. Thus, if a property A and a property A/B
+ exist on a resource, there is no recognition of any relationship
+ between the two properties. It is expected that a separate
+ specification will eventually be produced that will address issues
+ relating to hierarchical properties.
+
+ Finally, it is not possible to define the same property twice on a
+ single resource, as this would cause a collision in the resource's
+ property namespace.
+
+4.5. Source Resources and Output Resources
+
+ Some HTTP resources are dynamically generated by the server. For
+ these resources, there presumably exists source code somewhere
+ governing how that resource is generated. The relationship of source
+ files to output HTTP resources may be one to one, one to many, many
+ to one, or many to many. There is no mechanism in HTTP to determine
+ whether a resource is even dynamic, let alone where its source files
+ exist or how to author them. Although this problem would usefully be
+ solved, interoperable WebDAV implementations have been widely
+ deployed without actually solving this problem, by dealing only with
+ static resources. Thus, the source vs. output problem is not solved
+ in this specification and has been deferred to a separate document.
+
+5. Collections of Web Resources
+
+ This section provides a description of a type of Web resource, the
+ collection, and discusses its interactions with the HTTP URL
+ namespace and with HTTP methods. The purpose of a collection
+ resource is to model collection-like objects (e.g., file system
+ directories) within a server's namespace.
+
+
+
+Dusseault Standards Track [Page 14]
+
+RFC 4918 WebDAV June 2007
+
+
+ All DAV-compliant resources MUST support the HTTP URL namespace model
+ specified herein.
+
+5.1. HTTP URL Namespace Model
+
+ The HTTP URL namespace is a hierarchical namespace where the
+ hierarchy is delimited with the "/" character.
+
+ An HTTP URL namespace is said to be consistent if it meets the
+ following conditions: for every URL in the HTTP hierarchy there
+ exists a collection that contains that URL as an internal member URL.
+ The root, or top-level collection of the namespace under
+ consideration, is exempt from the previous rule. The top-level
+ collection of the namespace under consideration is not necessarily
+ the collection identified by the absolute path '/' -- it may be
+ identified by one or more path segments (e.g., /servlets/webdav/...)
+
+ Neither HTTP/1.1 nor WebDAV requires that the entire HTTP URL
+ namespace be consistent -- a WebDAV-compatible resource may not have
+ a parent collection. However, certain WebDAV methods are prohibited
+ from producing results that cause namespace inconsistencies.
+
+ As is implicit in [RFC2616] and [RFC3986], any resource, including
+ collection resources, MAY be identified by more than one URI. For
+ example, a resource could be identified by multiple HTTP URLs.
+
+5.2. Collection Resources
+
+ Collection resources differ from other resources in that they also
+ act as containers. Some HTTP methods apply only to a collection, but
+ some apply to some or all of the resources inside the container
+ defined by the collection. When the scope of a method is not clear,
+ the client can specify what depth to apply. Depth can be either zero
+ levels (only the collection), one level (the collection and directly
+ contained resources), or infinite levels (the collection and all
+ contained resources recursively).
+
+ A collection's state consists of at least a set of mappings between
+ path segments and resources, and a set of properties on the
+ collection itself. In this document, a resource B will be said to be
+ contained in the collection resource A if there is a path segment
+ mapping that maps to B and that is contained in A. A collection MUST
+ contain at most one mapping for a given path segment, i.e., it is
+ illegal to have the same path segment mapped to more than one
+ resource.
+
+
+
+
+
+
+Dusseault Standards Track [Page 15]
+
+RFC 4918 WebDAV June 2007
+
+
+ Properties defined on collections behave exactly as do properties on
+ non-collection resources. A collection MAY have additional state
+ such as entity bodies returned by GET.
+
+ For all WebDAV-compliant resources A and B, identified by URLs "U"
+ and "V", respectively, such that "V" is equal to "U/SEGMENT", A MUST
+ be a collection that contains a mapping from "SEGMENT" to B. So, if
+ resource B with URL "http://example.com/bar/blah" is WebDAV compliant
+ and if resource A with URL "http://example.com/bar/" is WebDAV
+ compliant, then resource A must be a collection and must contain
+ exactly one mapping from "blah" to B.
+
+ Although commonly a mapping consists of a single segment and a
+ resource, in general, a mapping consists of a set of segments and a
+ resource. This allows a server to treat a set of segments as
+ equivalent (i.e., either all of the segments are mapped to the same
+ resource, or none of the segments are mapped to a resource). For
+ example, a server that performs case-folding on segments will treat
+ the segments "ab", "Ab", "aB", and "AB" as equivalent. A client can
+ then use any of these segments to identify the resource. Note that a
+ PROPFIND result will select one of these equivalent segments to
+ identify the mapping, so there will be one PROPFIND response element
+ per mapping, not one per segment in the mapping.
+
+ Collection resources MAY have mappings to non-WebDAV-compliant
+ resources in the HTTP URL namespace hierarchy but are not required to
+ do so. For example, if resource X with URL
+ "http://example.com/bar/blah" is not WebDAV compliant and resource A
+ with "URL http://example.com/bar/" identifies a WebDAV collection,
+ then A may or may not have a mapping from "blah" to X.
+
+ If a WebDAV-compliant resource has no WebDAV-compliant internal
+ members in the HTTP URL namespace hierarchy, then the WebDAV-
+ compliant resource is not required to be a collection.
+
+ There is a standing convention that when a collection is referred to
+ by its name without a trailing slash, the server MAY handle the
+ request as if the trailing slash were present. In this case, it
+ SHOULD return a Content-Location header in the response, pointing to
+ the URL ending with the "/". For example, if a client invokes a
+ method on http://example.com/blah (no trailing slash), the server may
+ respond as if the operation were invoked on http://example.com/blah/
+ (trailing slash), and should return a Content-Location header with
+ the value http://example.com/blah/. Wherever a server produces a URL
+ referring to a collection, the server SHOULD include the trailing
+ slash. In general, clients SHOULD use the trailing slash form of
+ collection names. If clients do not use the trailing slash form the
+ client needs to be prepared to see a redirect response. Clients will
+
+
+
+Dusseault Standards Track [Page 16]
+
+RFC 4918 WebDAV June 2007
+
+
+ find the DAV:resourcetype property more reliable than the URL to find
+ out if a resource is a collection.
+
+ Clients MUST be able to support the case where WebDAV resources are
+ contained inside non-WebDAV resources. For example, if an OPTIONS
+ response from "http://example.com/servlet/dav/collection" indicates
+ WebDAV support, the client cannot assume that
+ "http://example.com/servlet/dav/" or its parent necessarily are
+ WebDAV collections.
+
+ A typical scenario in which mapped URLs do not appear as members of
+ their parent collection is the case where a server allows links or
+ redirects to non-WebDAV resources. For instance, "/col/link" might
+ not appear as a member of "/col/", although the server would respond
+ with a 302 status to a GET request to "/col/link"; thus, the URL
+ "/col/link" would indeed be mapped. Similarly, a dynamically-
+ generated page might have a URL mapping from "/col/index.html", thus
+ this resource might respond with a 200 OK to a GET request yet not
+ appear as a member of "/col/".
+
+ Some mappings to even WebDAV-compliant resources might not appear in
+ the parent collection. An example for this case are servers that
+ support multiple alias URLs for each WebDAV-compliant resource. A
+ server may implement case-insensitive URLs, thus "/col/a" and
+ "/col/A" identify the same resource, yet only either "a" or "A" is
+ reported upon listing the members of "/col". In cases where a server
+ treats a set of segments as equivalent, the server MUST expose only
+ one preferred segment per mapping, consistently chosen, in PROPFIND
+ responses.
+
+6. Locking
+
+ The ability to lock a resource provides a mechanism for serializing
+ access to that resource. Using a lock, an authoring client can
+ provide a reasonable guarantee that another principal will not modify
+ a resource while it is being edited. In this way, a client can
+ prevent the "lost update" problem.
+
+ This specification allows locks to vary over two client-specified
+ parameters, the number of principals involved (exclusive vs. shared)
+ and the type of access to be granted. This document defines locking
+ for only one access type, write. However, the syntax is extensible,
+ and permits the eventual specification of locking for other access
+ types.
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 17]
+
+RFC 4918 WebDAV June 2007
+
+
+6.1. Lock Model
+
+ This section provides a concise model for how locking behaves. Later
+ sections will provide more detail on some of the concepts and refer
+ back to these model statements. Normative statements related to LOCK
+ and UNLOCK method handling can be found in the sections on those
+ methods, whereas normative statements that cover any method are
+ gathered here.
+
+ 1. A lock either directly or indirectly locks a resource.
+
+ 2. A resource becomes directly locked when a LOCK request to a URL
+ of that resource creates a new lock. The "lock-root" of the new
+ lock is that URL. If at the time of the request, the URL is not
+ mapped to a resource, a new empty resource is created and
+ directly locked.
+
+ 3. An exclusive lock (Section 6.2) conflicts with any other kind of
+ lock on the same resource, whether either lock is direct or
+ indirect. A server MUST NOT create conflicting locks on a
+ resource.
+
+ 4. For a collection that is locked with a depth-infinity lock L, all
+ member resources are indirectly locked. Changes in membership of
+ such a collection affect the set of indirectly locked resources:
+
+ * If a member resource is added to the collection, the new
+ member resource MUST NOT already have a conflicting lock,
+ because the new resource MUST become indirectly locked by L.
+
+ * If a member resource stops being a member of the collection,
+ then the resource MUST no longer be indirectly locked by L.
+
+ 5. Each lock is identified by a single globally unique lock token
+ (Section 6.5).
+
+ 6. An UNLOCK request deletes the lock with the specified lock token.
+ After a lock is deleted, no resource is locked by that lock.
+
+ 7. A lock token is "submitted" in a request when it appears in an
+ "If" header (Section 7, "Write Lock", discusses when token
+ submission is required for write locks).
+
+ 8. If a request causes the lock-root of any lock to become an
+ unmapped URL, then the lock MUST also be deleted by that request.
+
+
+
+
+
+
+Dusseault Standards Track [Page 18]
+
+RFC 4918 WebDAV June 2007
+
+
+6.2. Exclusive vs. Shared Locks
+
+ The most basic form of lock is an exclusive lock. Exclusive locks
+ avoid having to deal with content change conflicts, without requiring
+ any coordination other than the methods described in this
+ specification.
+
+ However, there are times when the goal of a lock is not to exclude
+ others from exercising an access right but rather to provide a
+ mechanism for principals to indicate that they intend to exercise
+ their access rights. Shared locks are provided for this case. A
+ shared lock allows multiple principals to receive a lock. Hence any
+ principal that has both access privileges and a valid lock can use
+ the locked resource.
+
+ With shared locks, there are two trust sets that affect a resource.
+ The first trust set is created by access permissions. Principals who
+ are trusted, for example, may have permission to write to the
+ resource. Among those who have access permission to write to the
+ resource, the set of principals who have taken out a shared lock also
+ must trust each other, creating a (typically) smaller trust set
+ within the access permission write set.
+
+ Starting with every possible principal on the Internet, in most
+ situations the vast majority of these principals will not have write
+ access to a given resource. Of the small number who do have write
+ access, some principals may decide to guarantee their edits are free
+ from overwrite conflicts by using exclusive write locks. Others may
+ decide they trust their collaborators will not overwrite their work
+ (the potential set of collaborators being the set of principals who
+ have write permission) and use a shared lock, which informs their
+ collaborators that a principal may be working on the resource.
+
+ The WebDAV extensions to HTTP do not need to provide all of the
+ communications paths necessary for principals to coordinate their
+ activities. When using shared locks, principals may use any out-of-
+ band communication channel to coordinate their work (e.g., face-to-
+ face interaction, written notes, post-it notes on the screen,
+ telephone conversation, email, etc.) The intent of a shared lock is
+ to let collaborators know who else may be working on a resource.
+
+ Shared locks are included because experience from Web-distributed
+ authoring systems has indicated that exclusive locks are often too
+ rigid. An exclusive lock is used to enforce a particular editing
+ process: take out an exclusive lock, read the resource, perform
+ edits, write the resource, release the lock. This editing process
+ has the problem that locks are not always properly released, for
+ example, when a program crashes or when a lock creator leaves without
+
+
+
+Dusseault Standards Track [Page 19]
+
+RFC 4918 WebDAV June 2007
+
+
+ unlocking a resource. While both timeouts (Section 6.6) and
+ administrative action can be used to remove an offending lock,
+ neither mechanism may be available when needed; the timeout may be
+ long or the administrator may not be available.
+
+ A successful request for a new shared lock MUST result in the
+ generation of a unique lock associated with the requesting principal.
+ Thus, if five principals have taken out shared write locks on the
+ same resource, there will be five locks and five lock tokens, one for
+ each principal.
+
+6.3. Required Support
+
+ A WebDAV-compliant resource is not required to support locking in any
+ form. If the resource does support locking, it may choose to support
+ any combination of exclusive and shared locks for any access types.
+
+ The reason for this flexibility is that locking policy strikes to the
+ very heart of the resource management and versioning systems employed
+ by various storage repositories. These repositories require control
+ over what sort of locking will be made available. For example, some
+ repositories only support shared write locks, while others only
+ provide support for exclusive write locks, while yet others use no
+ locking at all. As each system is sufficiently different to merit
+ exclusion of certain locking features, this specification leaves
+ locking as the sole axis of negotiation within WebDAV.
+
+6.4. Lock Creator and Privileges
+
+ The creator of a lock has special privileges to use the lock to
+ modify the resource. When a locked resource is modified, a server
+ MUST check that the authenticated principal matches the lock creator
+ (in addition to checking for valid lock token submission).
+
+ The server MAY allow privileged users other than the lock creator to
+ destroy a lock (for example, the resource owner or an administrator).
+ The 'unlock' privilege in [RFC3744] was defined to provide that
+ permission.
+
+ There is no requirement for servers to accept LOCK requests from all
+ users or from anonymous users.
+
+ Note that having a lock does not confer full privilege to modify the
+ locked resource. Write access and other privileges MUST be enforced
+ through normal privilege or authentication mechanisms, not based on
+ the possible obscurity of lock token values.
+
+
+
+
+
+Dusseault Standards Track [Page 20]
+
+RFC 4918 WebDAV June 2007
+
+
+6.5. Lock Tokens
+
+ A lock token is a type of state token that identifies a particular
+ lock. Each lock has exactly one unique lock token generated by the
+ server. Clients MUST NOT attempt to interpret lock tokens in any
+ way.
+
+ Lock token URIs MUST be unique across all resources for all time.
+ This uniqueness constraint allows lock tokens to be submitted across
+ resources and servers without fear of confusion. Since lock tokens
+ are unique, a client MAY submit a lock token in an If header on a
+ resource other than the one that returned it.
+
+ When a LOCK operation creates a new lock, the new lock token is
+ returned in the Lock-Token response header defined in Section 10.5,
+ and also in the body of the response.
+
+ Servers MAY make lock tokens publicly readable (e.g., in the DAV:
+ lockdiscovery property). One use case for making lock tokens
+ readable is so that a long-lived lock can be removed by the resource
+ owner (the client that obtained the lock might have crashed or
+ disconnected before cleaning up the lock). Except for the case of
+ using UNLOCK under user guidance, a client SHOULD NOT use a lock
+ token created by another client instance.
+
+ This specification encourages servers to create Universally Unique
+ Identifiers (UUIDs) for lock tokens, and to use the URI form defined
+ by "A Universally Unique Identifier (UUID) URN Namespace"
+ ([RFC4122]). However, servers are free to use any URI (e.g., from
+ another scheme) so long as it meets the uniqueness requirements. For
+ example, a valid lock token might be constructed using the
+ "opaquelocktoken" scheme defined in Appendix C.
+
+ Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
+
+6.6. Lock Timeout
+
+ A lock MAY have a limited lifetime. The lifetime is suggested by the
+ client when creating or refreshing the lock, but the server
+ ultimately chooses the timeout value. Timeout is measured in seconds
+ remaining until lock expiration.
+
+ The timeout counter MUST be restarted if a refresh lock request is
+ successful (see Section 9.10.2). The timeout counter SHOULD NOT be
+ restarted at any other time.
+
+ If the timeout expires, then the lock SHOULD be removed. In this
+ case the server SHOULD act as if an UNLOCK method was executed by the
+
+
+
+Dusseault Standards Track [Page 21]
+
+RFC 4918 WebDAV June 2007
+
+
+ server on the resource using the lock token of the timed-out lock,
+ performed with its override authority.
+
+ Servers are advised to pay close attention to the values submitted by
+ clients, as they will be indicative of the type of activity the
+ client intends to perform. For example, an applet running in a
+ browser may need to lock a resource, but because of the instability
+ of the environment within which the applet is running, the applet may
+ be turned off without warning. As a result, the applet is likely to
+ ask for a relatively small timeout value so that if the applet dies,
+ the lock can be quickly harvested. However, a document management
+ system is likely to ask for an extremely long timeout because its
+ user may be planning on going offline.
+
+ A client MUST NOT assume that just because the timeout has expired,
+ the lock has immediately been removed.
+
+ Likewise, a client MUST NOT assume that just because the timeout has
+ not expired, the lock still exists. Clients MUST assume that locks
+ can arbitrarily disappear at any time, regardless of the value given
+ in the Timeout header. The Timeout header only indicates the
+ behavior of the server if extraordinary circumstances do not occur.
+ For example, a sufficiently privileged user may remove a lock at any
+ time, or the system may crash in such a way that it loses the record
+ of the lock's existence.
+
+6.7. Lock Capability Discovery
+
+ Since server lock support is optional, a client trying to lock a
+ resource on a server can either try the lock and hope for the best,
+ or perform some form of discovery to determine what lock capabilities
+ the server supports. This is known as lock capability discovery. A
+ client can determine what lock types the server supports by
+ retrieving the DAV:supportedlock property.
+
+ Any DAV-compliant resource that supports the LOCK method MUST support
+ the DAV:supportedlock property.
+
+6.8. Active Lock Discovery
+
+ If another principal locks a resource that a principal wishes to
+ access, it is useful for the second principal to be able to find out
+ who the first principal is. For this purpose the DAV:lockdiscovery
+ property is provided. This property lists all outstanding locks,
+ describes their type, and MAY even provide the lock tokens.
+
+ Any DAV-compliant resource that supports the LOCK method MUST support
+ the DAV:lockdiscovery property.
+
+
+
+Dusseault Standards Track [Page 22]
+
+RFC 4918 WebDAV June 2007
+
+
+7. Write Lock
+
+ This section describes the semantics specific to the write lock type.
+ The write lock is a specific instance of a lock type, and is the only
+ lock type described in this specification.
+
+ An exclusive write lock protects a resource: it prevents changes by
+ any principal other than the lock creator and in any case where the
+ lock token is not submitted (e.g., by a client process other than the
+ one holding the lock).
+
+ Clients MUST submit a lock-token they are authorized to use in any
+ request that modifies a write-locked resource. The list of
+ modifications covered by a write-lock include:
+
+ 1. A change to any of the following aspects of any write-locked
+ resource:
+
+ * any variant,
+
+ * any dead property,
+
+ * any live property that is lockable (a live property is
+ lockable unless otherwise defined.)
+
+ 2. For collections, any modification of an internal member URI. An
+ internal member URI of a collection is considered to be modified
+ if it is added, removed, or identifies a different resource.
+ More discussion on write locks and collections is found in
+ Section 7.4.
+
+ 3. A modification of the mapping of the root of the write lock,
+ either to another resource or to no resource (e.g., DELETE).
+
+ Of the methods defined in HTTP and WebDAV, PUT, POST, PROPPATCH,
+ LOCK, UNLOCK, MOVE, COPY (for the destination resource), DELETE, and
+ MKCOL are affected by write locks. All other HTTP/WebDAV methods
+ defined so far -- GET in particular -- function independently of a
+ write lock.
+
+ The next few sections describe in more specific terms how write locks
+ interact with various operations.
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 23]
+
+RFC 4918 WebDAV June 2007
+
+
+7.1. Write Locks and Properties
+
+ While those without a write lock may not alter a property on a
+ resource it is still possible for the values of live properties to
+ change, even while locked, due to the requirements of their schemas.
+ Only dead properties and live properties defined as lockable are
+ guaranteed not to change while write locked.
+
+7.2. Avoiding Lost Updates
+
+ Although the write locks provide some help in preventing lost
+ updates, they cannot guarantee that updates will never be lost.
+ Consider the following scenario:
+
+ Two clients A and B are interested in editing the resource
+ 'index.html'. Client A is an HTTP client rather than a WebDAV
+ client, and so does not know how to perform locking.
+
+ Client A doesn't lock the document, but does a GET, and begins
+ editing.
+
+ Client B does LOCK, performs a GET and begins editing.
+
+ Client B finishes editing, performs a PUT, then an UNLOCK.
+
+ Client A performs a PUT, overwriting and losing all of B's changes.
+
+ There are several reasons why the WebDAV protocol itself cannot
+ prevent this situation. First, it cannot force all clients to use
+ locking because it must be compatible with HTTP clients that do not
+ comprehend locking. Second, it cannot require servers to support
+ locking because of the variety of repository implementations, some of
+ which rely on reservations and merging rather than on locking.
+ Finally, being stateless, it cannot enforce a sequence of operations
+ like LOCK / GET / PUT / UNLOCK.
+
+ WebDAV servers that support locking can reduce the likelihood that
+ clients will accidentally overwrite each other's changes by requiring
+ clients to lock resources before modifying them. Such servers would
+ effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying
+ resources.
+
+ WebDAV clients can be good citizens by using a lock / retrieve /
+ write /unlock sequence of operations (at least by default) whenever
+ they interact with a WebDAV server that supports locking.
+
+
+
+
+
+
+Dusseault Standards Track [Page 24]
+
+RFC 4918 WebDAV June 2007
+
+
+ HTTP 1.1 clients can be good citizens, avoiding overwriting other
+ clients' changes, by using entity tags in If-Match headers with any
+ requests that would modify resources.
+
+ Information managers may attempt to prevent overwrites by
+ implementing client-side procedures requiring locking before
+ modifying WebDAV resources.
+
+7.3. Write Locks and Unmapped URLs
+
+ WebDAV provides the ability to send a LOCK request to an unmapped URL
+ in order to reserve the name for use. This is a simple way to avoid
+ the lost-update problem on the creation of a new resource (another
+ way is to use If-None-Match header specified in Section 14.26 of
+ [RFC2616]). It has the side benefit of locking the new resource
+ immediately for use of the creator.
+
+ Note that the lost-update problem is not an issue for collections
+ because MKCOL can only be used to create a collection, not to
+ overwrite an existing collection. When trying to lock a collection
+ upon creation, clients can attempt to increase the likelihood of
+ getting the lock by pipelining the MKCOL and LOCK requests together
+ (but because this doesn't convert two separate operations into one
+ atomic operation, there's no guarantee this will work).
+
+ A successful lock request to an unmapped URL MUST result in the
+ creation of a locked (non-collection) resource with empty content.
+ Subsequently, a successful PUT request (with the correct lock token)
+ provides the content for the resource. Note that the LOCK request
+ has no mechanism for the client to provide Content-Type or Content-
+ Language, thus the server will use defaults or empty values and rely
+ on the subsequent PUT request for correct values.
+
+ A resource created with a LOCK is empty but otherwise behaves in
+ every way as a normal resource. It behaves the same way as a
+ resource created by a PUT request with an empty body (and where a
+ Content-Type and Content-Language was not specified), followed by a
+ LOCK request to the same resource. Following from this model, a
+ locked empty resource:
+
+ o Can be read, deleted, moved, and copied, and in all ways behaves
+ as a regular non-collection resource.
+
+ o Appears as a member of its parent collection.
+
+ o SHOULD NOT disappear when its lock goes away (clients must
+ therefore be responsible for cleaning up their own mess, as with
+ any other operation or any non-empty resource).
+
+
+
+Dusseault Standards Track [Page 25]
+
+RFC 4918 WebDAV June 2007
+
+
+ o MAY NOT have values for properties like DAV:getcontentlanguage
+ that haven't been specified yet by the client.
+
+ o Can be updated (have content added) with a PUT request.
+
+ o MUST NOT be converted into a collection. The server MUST fail a
+ MKCOL request (as it would with a MKCOL request to any existing
+ non-collection resource).
+
+ o MUST have defined values for DAV:lockdiscovery and DAV:
+ supportedlock properties.
+
+ o The response MUST indicate that a resource was created, by use of
+ the "201 Created" response code (a LOCK request to an existing
+ resource instead will result in 200 OK). The body must still
+ include the DAV:lockdiscovery property, as with a LOCK request to
+ an existing resource.
+
+ The client is expected to update the locked empty resource shortly
+ after locking it, using PUT and possibly PROPPATCH.
+
+ Alternatively and for backwards compatibility to [RFC2518], servers
+ MAY implement Lock-Null Resources (LNRs) instead (see definition in
+ Appendix D). Clients can easily interoperate both with servers that
+ support the old model LNRs and the recommended model of "locked empty
+ resources" by only attempting PUT after a LOCK to an unmapped URL,
+ not MKCOL or GET, and by not relying on specific properties of LNRs.
+
+7.4. Write Locks and Collections
+
+ There are two kinds of collection write locks. A depth-0 write lock
+ on a collection protects the collection properties plus the internal
+ member URLs of that one collection, while not protecting the content
+ or properties of member resources (if the collection itself has any
+ entity bodies, those are also protected). A depth-infinity write
+ lock on a collection provides the same protection on that collection
+ and also provides write lock protection on every member resource.
+
+ Expressed otherwise, a write lock of either kind protects any request
+ that would create a new resource in a write locked collection, any
+ request that would remove an internal member URL of a write locked
+ collection, and any request that would change the segment name of any
+ internal member.
+
+ Thus, a collection write lock protects all the following actions:
+
+ o DELETE a collection's direct internal member,
+
+
+
+
+Dusseault Standards Track [Page 26]
+
+RFC 4918 WebDAV June 2007
+
+
+ o MOVE an internal member out of the collection,
+
+ o MOVE an internal member into the collection,
+
+ o MOVE to rename an internal member within a collection,
+
+ o COPY an internal member into a collection, and
+
+ o PUT or MKCOL request that would create a new internal member.
+
+ The collection's lock token is required in addition to the lock token
+ on the internal member itself, if it is locked separately.
+
+ In addition, a depth-infinity lock affects all write operations to
+ all members of the locked collection. With a depth-infinity lock,
+ the resource identified by the root of the lock is directly locked,
+ and all its members are indirectly locked.
+
+ o Any new resource added as a descendant of a depth-infinity locked
+ collection becomes indirectly locked.
+
+ o Any indirectly locked resource moved out of the locked collection
+ into an unlocked collection is thereafter unlocked.
+
+ o Any indirectly locked resource moved out of a locked source
+ collection into a depth-infinity locked target collection remains
+ indirectly locked but is now protected by the lock on the target
+ collection (the target collection's lock token will thereafter be
+ required to make further changes).
+
+ If a depth-infinity write LOCK request is issued to a collection
+ containing member URLs identifying resources that are currently
+ locked in a manner that conflicts with the new lock (see Section 6.1,
+ point 3), the request MUST fail with a 423 (Locked) status code, and
+ the response SHOULD contain the 'no-conflicting-lock' precondition.
+
+ If a lock request causes the URL of a resource to be added as an
+ internal member URL of a depth-infinity locked collection, then the
+ new resource MUST be automatically protected by the lock. For
+ example, if the collection /a/b/ is write locked and the resource /c
+ is moved to /a/b/c, then resource /a/b/c will be added to the write
+ lock.
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 27]
+
+RFC 4918 WebDAV June 2007
+
+
+7.5. Write Locks and the If Request Header
+
+ A user agent has to demonstrate knowledge of a lock when requesting
+ an operation on a locked resource. Otherwise, the following scenario
+ might occur. In the scenario, program A, run by User A, takes out a
+ write lock on a resource. Program B, also run by User A, has no
+ knowledge of the lock taken out by program A, yet performs a PUT to
+ the locked resource. In this scenario, the PUT succeeds because
+ locks are associated with a principal, not a program, and thus
+ program B, because it is acting with principal A's credential, is
+ allowed to perform the PUT. However, had program B known about the
+ lock, it would not have overwritten the resource, preferring instead
+ to present a dialog box describing the conflict to the user. Due to
+ this scenario, a mechanism is needed to prevent different programs
+ from accidentally ignoring locks taken out by other programs with the
+ same authorization.
+
+ In order to prevent these collisions, a lock token MUST be submitted
+ by an authorized principal for all locked resources that a method may
+ change or the method MUST fail. A lock token is submitted when it
+ appears in an If header. For example, if a resource is to be moved
+ and both the source and destination are locked, then two lock tokens
+ must be submitted in the If header, one for the source and the other
+ for the destination.
+
+7.5.1. Example - Write Lock and COPY
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/users/f/fielding/index.html
+ If: <http://www.example.com/users/f/fielding/index.html>
+ (<urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>)
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+ In this example, even though both the source and destination are
+ locked, only one lock token must be submitted (the one for the lock
+ on the destination). This is because the source resource is not
+ modified by a COPY, and hence unaffected by the write lock. In this
+ example, user agent authentication has previously occurred via a
+ mechanism outside the scope of the HTTP protocol, in the underlying
+ transport layer.
+
+
+
+
+
+Dusseault Standards Track [Page 28]
+
+RFC 4918 WebDAV June 2007
+
+
+7.5.2. Example - Deleting a Member of a Locked Collection
+
+ Consider a collection "/locked" with an exclusive, depth-infinity
+ write lock, and an attempt to delete an internal member "/locked/
+ member":
+
+ >>Request
+
+ DELETE /locked/member HTTP/1.1
+ Host: example.com
+
+ >>Response
+
+ HTTP/1.1 423 Locked
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:lock-token-submitted>
+ <D:href>/locked/</D:href>
+ </D:lock-token-submitted>
+ </D:error>
+
+ Thus, the client would need to submit the lock token with the request
+ to make it succeed. To do that, various forms of the If header (see
+ Section 10.4) could be used.
+
+ "No-Tag-List" format:
+
+ If: (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
+
+ "Tagged-List" format, for "http://example.com/locked/":
+
+ If: <http://example.com/locked/>
+ (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
+
+ "Tagged-List" format, for "http://example.com/locked/member":
+
+ If: <http://example.com/locked/member>
+ (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
+
+ Note that, for the purpose of submitting the lock token, the actual
+ form doesn't matter; what's relevant is that the lock token appears
+ in the If header, and that the If header itself evaluates to true.
+
+
+
+
+
+
+Dusseault Standards Track [Page 29]
+
+RFC 4918 WebDAV June 2007
+
+
+7.6. Write Locks and COPY/MOVE
+
+ A COPY method invocation MUST NOT duplicate any write locks active on
+ the source. However, as previously noted, if the COPY copies the
+ resource into a collection that is locked with a depth-infinity lock,
+ then the resource will be added to the lock.
+
+ A successful MOVE request on a write locked resource MUST NOT move
+ the write lock with the resource. However, if there is an existing
+ lock at the destination, the server MUST add the moved resource to
+ the destination lock scope. For example, if the MOVE makes the
+ resource a child of a collection that has a depth-infinity lock, then
+ the resource will be added to that collection's lock. Additionally,
+ if a resource with a depth-infinity lock is moved to a destination
+ that is within the scope of the same lock (e.g., within the URL
+ namespace tree covered by the lock), the moved resource will again be
+ added to the lock. In both these examples, as specified in
+ Section 7.5, an If header must be submitted containing a lock token
+ for both the source and destination.
+
+7.7. Refreshing Write Locks
+
+ A client MUST NOT submit the same write lock request twice. Note
+ that a client is always aware it is resubmitting the same lock
+ request because it must include the lock token in the If header in
+ order to make the request for a resource that is already locked.
+
+ However, a client may submit a LOCK request with an If header but
+ without a body. A server receiving a LOCK request with no body MUST
+ NOT create a new lock -- this form of the LOCK request is only to be
+ used to "refresh" an existing lock (meaning, at minimum, that any
+ timers associated with the lock MUST be reset).
+
+ Clients may submit Timeout headers of arbitrary value with their lock
+ refresh requests. Servers, as always, may ignore Timeout headers
+ submitted by the client, and a server MAY refresh a lock with a
+ timeout period that is different than the previous timeout period
+ used for the lock, provided it advertises the new value in the LOCK
+ refresh response.
+
+ If an error is received in response to a refresh LOCK request, the
+ client MUST NOT assume that the lock was refreshed.
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 30]
+
+RFC 4918 WebDAV June 2007
+
+
+8. General Request and Response Handling
+
+8.1. Precedence in Error Handling
+
+ Servers MUST return authorization errors in preference to other
+ errors. This avoids leaking information about protected resources
+ (e.g., a client that finds that a hidden resource exists by seeing a
+ 423 Locked response to an anonymous request to the resource).
+
+8.2. Use of XML
+
+ In HTTP/1.1, method parameter information was exclusively encoded in
+ HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter
+ information either in an XML ([REC-XML]) request entity body, or in
+ an HTTP header. The use of XML to encode method parameters was
+ motivated by the ability to add extra XML elements to existing
+ structures, providing extensibility; and by XML's ability to encode
+ information in ISO 10646 character sets, providing
+ internationalization support.
+
+ In addition to encoding method parameters, XML is used in WebDAV to
+ encode the responses from methods, providing the extensibility and
+ internationalization advantages of XML for method output, as well as
+ input.
+
+ When XML is used for a request or response body, the Content-Type
+ type SHOULD be application/xml. Implementations MUST accept both
+ text/xml and application/xml in request and response bodies. Use of
+ text/xml is deprecated.
+
+ All DAV-compliant clients and resources MUST use XML parsers that are
+ compliant with [REC-XML] and [REC-XML-NAMES]. All XML used in either
+ requests or responses MUST be, at minimum, well formed and use
+ namespaces correctly. If a server receives XML that is not well-
+ formed, then the server MUST reject the entire request with a 400
+ (Bad Request). If a client receives XML that is not well-formed in a
+ response, then the client MUST NOT assume anything about the outcome
+ of the executed method and SHOULD treat the server as malfunctioning.
+
+ Note that processing XML submitted by an untrusted source may cause
+ risks connected to privacy, security, and service quality (see
+ Section 20). Servers MAY reject questionable requests (even though
+ they consist of well-formed XML), for instance, with a 400 (Bad
+ Request) status code and an optional response body explaining the
+ problem.
+
+
+
+
+
+
+Dusseault Standards Track [Page 31]
+
+RFC 4918 WebDAV June 2007
+
+
+8.3. URL Handling
+
+ URLs appear in many places in requests and responses.
+ Interoperability experience with [RFC2518] showed that many clients
+ parsing Multi-Status responses did not fully implement the full
+ Reference Resolution defined in Section 5 of [RFC3986]. Thus,
+ servers in particular need to be careful in handling URLs in
+ responses, to ensure that clients have enough context to be able to
+ interpret all the URLs. The rules in this section apply not only to
+ resource URLs in the 'href' element in Multi-Status responses, but
+ also to the Destination and If header resource URLs.
+
+ The sender has a choice between two approaches: using a relative
+ reference, which is resolved against the Request-URI, or a full URI.
+ A server MUST ensure that every 'href' value within a Multi-Status
+ response uses the same format.
+
+ WebDAV only uses one form of relative reference in its extensions,
+ the absolute path.
+
+ Simple-ref = absolute-URI | ( path-absolute [ "?" query ] )
+
+ The absolute-URI, path-absolute and query productions are defined in
+ Sections 4.3, 3.3, and 3.4 of [RFC3986].
+
+ Within Simple-ref productions, senders MUST NOT:
+
+ o use dot-segments ("." or ".."), or
+
+ o have prefixes that do not match the Request-URI (using the
+ comparison rules defined in Section 3.2.3 of [RFC2616]).
+
+ Identifiers for collections SHOULD end in a '/' character.
+
+8.3.1. Example - Correct URL Handling
+
+ Consider the collection http://example.com/sample/ with the internal
+ member URL http://example.com/sample/a%20test and the PROPFIND
+ request below:
+
+ >>Request:
+
+ PROPFIND /sample/ HTTP/1.1
+ Host: example.com
+ Depth: 1
+
+
+
+
+
+
+Dusseault Standards Track [Page 32]
+
+RFC 4918 WebDAV June 2007
+
+
+ In this case, the server should return two 'href' elements containing
+ either
+
+ o 'http://example.com/sample/' and
+ 'http://example.com/sample/a%20test', or
+
+ o '/sample/' and '/sample/a%20test'
+
+ Note that even though the server may be storing the member resource
+ internally as 'a test', it has to be percent-encoded when used inside
+ a URI reference (see Section 2.1 of [RFC3986]). Also note that a
+ legal URI may still contain characters that need to be escaped within
+ XML character data, such as the ampersand character.
+
+8.4. Required Bodies in Requests
+
+ Some of these new methods do not define bodies. Servers MUST examine
+ all requests for a body, even when a body was not expected. In cases
+ where a request body is present but would be ignored by a server, the
+ server MUST reject the request with 415 (Unsupported Media Type).
+ This informs the client (which may have been attempting to use an
+ extension) that the body could not be processed as the client
+ intended.
+
+8.5. HTTP Headers for Use in WebDAV
+
+ HTTP defines many headers that can be used in WebDAV requests and
+ responses. Not all of these are appropriate in all situations and
+ some interactions may be undefined. Note that HTTP 1.1 requires the
+ Date header in all responses if possible (see Section 14.18,
+ [RFC2616]).
+
+ The server MUST do authorization checks before checking any HTTP
+ conditional header.
+
+8.6. ETag
+
+ HTTP 1.1 recommends the use of ETags rather than modification dates,
+ for cache control, and there are even stronger reasons to prefer
+ ETags for authoring. Correct use of ETags is even more important in
+ a distributed authoring environment, because ETags are necessary
+ along with locks to avoid the lost-update problem. A client might
+ fail to renew a lock, for example, when the lock times out and the
+ client is accidentally offline or in the middle of a long upload.
+ When a client fails to renew the lock, it's quite possible the
+ resource can still be relocked and the user can go on editing, as
+ long as no changes were made in the meantime. ETags are required for
+ the client to be able to distinguish this case. Otherwise, the
+
+
+
+Dusseault Standards Track [Page 33]
+
+RFC 4918 WebDAV June 2007
+
+
+ client is forced to ask the user whether to overwrite the resource on
+ the server without even being able to tell the user if it has
+ changed. Timestamps do not solve this problem nearly as well as
+ ETags.
+
+ Strong ETags are much more useful for authoring use cases than weak
+ ETags (see Section 13.3.3 of [RFC2616]). Semantic equivalence can be
+ a useful concept but that depends on the document type and the
+ application type, and interoperability might require some agreement
+ or standard outside the scope of this specification and HTTP. Note
+ also that weak ETags have certain restrictions in HTTP, e.g., these
+ cannot be used in If-Match headers.
+
+ Note that the meaning of an ETag in a PUT response is not clearly
+ defined either in this document or in RFC 2616 (i.e., whether the
+ ETag means that the resource is octet-for-octet equivalent to the
+ body of the PUT request, or whether the server could have made minor
+ changes in the formatting or content of the document upon storage).
+ This is an HTTP issue, not purely a WebDAV issue.
+
+ Because clients may be forced to prompt users or throw away changed
+ content if the ETag changes, a WebDAV server SHOULD NOT change the
+ ETag (or the Last-Modified time) for a resource that has an unchanged
+ body and location. The ETag represents the state of the body or
+ contents of the resource. There is no similar way to tell if
+ properties have changed.
+
+8.7. Including Error Response Bodies
+
+ HTTP and WebDAV did not use the bodies of most error responses for
+ machine-parsable information until the specification for Versioning
+ Extensions to WebDAV introduced a mechanism to include more specific
+ information in the body of an error response (Section 1.6 of
+ [RFC3253]). The error body mechanism is appropriate to use with any
+ error response that may take a body but does not already have a body
+ defined. The mechanism is particularly appropriate when a status
+ code can mean many things (for example, 400 Bad Request can mean
+ required headers are missing, headers are incorrectly formatted, or
+ much more). This error body mechanism is covered in Section 16.
+
+8.8. Impact of Namespace Operations on Cache Validators
+
+ Note that the HTTP response headers "Etag" and "Last-Modified" (see
+ [RFC2616], Sections 14.19 and 14.29) are defined per URL (not per
+ resource), and are used by clients for caching. Therefore servers
+ must ensure that executing any operation that affects the URL
+ namespace (such as COPY, MOVE, DELETE, PUT, or MKCOL) does preserve
+ their semantics, in particular:
+
+
+
+Dusseault Standards Track [Page 34]
+
+RFC 4918 WebDAV June 2007
+
+
+ o For any given URL, the "Last-Modified" value MUST increment every
+ time the representation returned upon GET changes (within the
+ limits of timestamp resolution).
+
+ o For any given URL, an "ETag" value MUST NOT be reused for
+ different representations returned by GET.
+
+ In practice this means that servers
+
+ o might have to increment "Last-Modified" timestamps for every
+ resource inside the destination namespace of a namespace operation
+ unless it can do so more selectively, and
+
+ o similarly, might have to re-assign "ETag" values for these
+ resources (unless the server allocates entity tags in a way so
+ that they are unique across the whole URL namespace managed by the
+ server).
+
+ Note that these considerations also apply to specific use cases, such
+ as using PUT to create a new resource at a URL that has been mapped
+ before, but has been deleted since then.
+
+ Finally, WebDAV properties (such as DAV:getetag and DAV:
+ getlastmodified) that inherit their semantics from HTTP headers must
+ behave accordingly.
+
+9. HTTP Methods for Distributed Authoring
+
+9.1. PROPFIND Method
+
+ The PROPFIND method retrieves properties defined on the resource
+ identified by the Request-URI, if the resource does not have any
+ internal members, or on the resource identified by the Request-URI
+ and potentially its member resources, if the resource is a collection
+ that has internal member URLs. All DAV-compliant resources MUST
+ support the PROPFIND method and the propfind XML element
+ (Section 14.20) along with all XML elements defined for use with that
+ element.
+
+ A client MUST submit a Depth header with a value of "0", "1", or
+ "infinity" with a PROPFIND request. Servers MUST support "0" and "1"
+ depth requests on WebDAV-compliant resources and SHOULD support
+ "infinity" requests. In practice, support for infinite-depth
+ requests MAY be disabled, due to the performance and security
+ concerns associated with this behavior. Servers SHOULD treat a
+ request without a Depth header as if a "Depth: infinity" header was
+ included.
+
+
+
+
+Dusseault Standards Track [Page 35]
+
+RFC 4918 WebDAV June 2007
+
+
+ A client may submit a 'propfind' XML element in the body of the
+ request method describing what information is being requested. It is
+ possible to:
+
+ o Request particular property values, by naming the properties
+ desired within the 'prop' element (the ordering of properties in
+ here MAY be ignored by the server),
+
+ o Request property values for those properties defined in this
+ specification (at a minimum) plus dead properties, by using the
+ 'allprop' element (the 'include' element can be used with
+ 'allprop' to instruct the server to also include additional live
+ properties that may not have been returned otherwise),
+
+ o Request a list of names of all the properties defined on the
+ resource, by using the 'propname' element.
+
+ A client may choose not to submit a request body. An empty PROPFIND
+ request body MUST be treated as if it were an 'allprop' request.
+
+ Note that 'allprop' does not return values for all live properties.
+ WebDAV servers increasingly have expensively-calculated or lengthy
+ properties (see [RFC3253] and [RFC3744]) and do not return all
+ properties already. Instead, WebDAV clients can use propname
+ requests to discover what live properties exist, and request named
+ properties when retrieving values. For a live property defined
+ elsewhere, that definition can specify whether or not that live
+ property would be returned in 'allprop' requests.
+
+ All servers MUST support returning a response of content type text/
+ xml or application/xml that contains a multistatus XML element that
+ describes the results of the attempts to retrieve the various
+ properties.
+
+ If there is an error retrieving a property, then a proper error
+ result MUST be included in the response. A request to retrieve the
+ value of a property that does not exist is an error and MUST be noted
+ with a 'response' XML element that contains a 404 (Not Found) status
+ value.
+
+ Consequently, the 'multistatus' XML element for a collection resource
+ MUST include a 'response' XML element for each member URL of the
+ collection, to whatever depth was requested. It SHOULD NOT include
+ any 'response' elements for resources that are not WebDAV-compliant.
+ Each 'response' element MUST contain an 'href' element that contains
+ the URL of the resource on which the properties in the prop XML
+ element are defined. Results for a PROPFIND on a collection resource
+ are returned as a flat list whose order of entries is not
+
+
+
+Dusseault Standards Track [Page 36]
+
+RFC 4918 WebDAV June 2007
+
+
+ significant. Note that a resource may have only one value for a
+ property of a given name, so the property may only show up once in
+ PROPFIND responses.
+
+ Properties may be subject to access control. In the case of
+ 'allprop' and 'propname' requests, if a principal does not have the
+ right to know whether a particular property exists, then the property
+ MAY be silently excluded from the response.
+
+ Some PROPFIND results MAY be cached, with care, as there is no cache
+ validation mechanism for most properties. This method is both safe
+ and idempotent (see Section 9.1 of [RFC2616]).
+
+9.1.1. PROPFIND Status Codes
+
+ This section, as with similar sections for other methods, provides
+ some guidance on error codes and preconditions or postconditions
+ (defined in Section 16) that might be particularly useful with
+ PROPFIND.
+
+ 403 Forbidden - A server MAY reject PROPFIND requests on collections
+ with depth header of "Infinity", in which case it SHOULD use this
+ error with the precondition code 'propfind-finite-depth' inside the
+ error body.
+
+9.1.2. Status Codes for Use in 'propstat' Element
+
+ In PROPFIND responses, information about individual properties is
+ returned inside 'propstat' elements (see Section 14.22), each
+ containing an individual 'status' element containing information
+ about the properties appearing in it. The list below summarizes the
+ most common status codes used inside 'propstat'; however, clients
+ should be prepared to handle other 2/3/4/5xx series status codes as
+ well.
+
+ 200 OK - A property exists and/or its value is successfully returned.
+
+ 401 Unauthorized - The property cannot be viewed without appropriate
+ authorization.
+
+ 403 Forbidden - The property cannot be viewed regardless of
+ authentication.
+
+ 404 Not Found - The property does not exist.
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 37]
+
+RFC 4918 WebDAV June 2007
+
+
+9.1.3. Example - Retrieving Named Properties
+
+ >>Request
+
+ PROPFIND /file HTTP/1.1
+ Host: www.example.com
+ Content-type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox/>
+ <R:author/>
+ <R:DingALing/>
+ <R:Random/>
+ </D:prop>
+ </D:propfind>
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response xmlns:R="http://ns.example.com/boxschema/">
+ <D:href>http://www.example.com/file</D:href>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox>
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ <R:author>
+ <R:Name>J.J. Johnson</R:Name>
+ </R:author>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop><R:DingALing/><R:Random/></D:prop>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ <D:responsedescription> The user does not have access to the
+ DingALing property.
+ </D:responsedescription>
+ </D:propstat>
+
+
+
+Dusseault Standards Track [Page 38]
+
+RFC 4918 WebDAV June 2007
+
+
+ </D:response>
+ <D:responsedescription> There has been an access violation error.
+ </D:responsedescription>
+ </D:multistatus>
+
+
+ In this example, PROPFIND is executed on a non-collection resource
+ http://www.example.com/file. The propfind XML element specifies the
+ name of four properties whose values are being requested. In this
+ case, only two properties were returned, since the principal issuing
+ the request did not have sufficient access rights to see the third
+ and fourth properties.
+
+9.1.4. Example - Using 'propname' to Retrieve All Property Names
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.example.com
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <propfind xmlns="DAV:">
+ <propname/>
+ </propfind>
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <multistatus xmlns="DAV:">
+ <response>
+ <href>http://www.example.com/container/</href>
+ <propstat>
+ <prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox/>
+ <R:author/>
+ <creationdate/>
+ <displayname/>
+ <resourcetype/>
+ <supportedlock/>
+ </prop>
+ <status>HTTP/1.1 200 OK</status>
+
+
+
+Dusseault Standards Track [Page 39]
+
+RFC 4918 WebDAV June 2007
+
+
+ </propstat>
+ </response>
+ <response>
+ <href>http://www.example.com/container/front.html</href>
+ <propstat>
+ <prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox/>
+ <creationdate/>
+ <displayname/>
+ <getcontentlength/>
+ <getcontenttype/>
+ <getetag/>
+ <getlastmodified/>
+ <resourcetype/>
+ <supportedlock/>
+ </prop>
+ <status>HTTP/1.1 200 OK</status>
+ </propstat>
+ </response>
+ </multistatus>
+
+ In this example, PROPFIND is invoked on the collection resource
+ http://www.example.com/container/, with a propfind XML element
+ containing the propname XML element, meaning the name of all
+ properties should be returned. Since no Depth header is present, it
+ assumes its default value of "infinity", meaning the name of the
+ properties on the collection and all its descendants should be
+ returned.
+
+ Consistent with the previous example, resource
+ http://www.example.com/container/ has six properties defined on it:
+ bigbox and author in the "http://ns.example.com/boxschema/"
+ namespace, and creationdate, displayname, resourcetype, and
+ supportedlock in the "DAV:" namespace.
+
+ The resource http://www.example.com/container/index.html, a member of
+ the "container" collection, has nine properties defined on it, bigbox
+ in the "http://ns.example.com/boxschema/" namespace and creationdate,
+ displayname, getcontentlength, getcontenttype, getetag,
+ getlastmodified, resourcetype, and supportedlock in the "DAV:"
+ namespace.
+
+ This example also demonstrates the use of XML namespace scoping and
+ the default namespace. Since the "xmlns" attribute does not contain
+ a prefix, the namespace applies by default to all enclosed elements.
+ Hence, all elements that do not explicitly state the namespace to
+ which they belong are members of the "DAV:" namespace.
+
+
+
+
+Dusseault Standards Track [Page 40]
+
+RFC 4918 WebDAV June 2007
+
+
+9.1.5. Example - Using So-called 'allprop'
+
+ Note that 'allprop', despite its name, which remains for backward-
+ compatibility, does not return every property, but only dead
+ properties and the live properties defined in this specification.
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.example.com
+ Depth: 1
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ </D:propfind>
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>/container/</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox><R:BoxType>Box type A</R:BoxType></R:bigbox>
+ <R:author><R:Name>Hadrian</R:Name></R:author>
+ <D:creationdate>1997-12-01T17:42:21-08:00</D:creationdate>
+ <D:displayname>Example collection</D:displayname>
+ <D:resourcetype><D:collection/></D:resourcetype>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+
+
+
+Dusseault Standards Track [Page 41]
+
+RFC 4918 WebDAV June 2007
+
+
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/container/front.html</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox><R:BoxType>Box type B</R:BoxType>
+ </R:bigbox>
+ <D:creationdate>1997-12-01T18:27:21-08:00</D:creationdate>
+ <D:displayname>Example HTML resource</D:displayname>
+ <D:getcontentlength>4525</D:getcontentlength>
+ <D:getcontenttype>text/html</D:getcontenttype>
+ <D:getetag>"zzyzx"</D:getetag>
+ <D:getlastmodified
+ >Mon, 12 Jan 1998 09:25:56 GMT</D:getlastmodified>
+ <D:resourcetype/>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ In this example, PROPFIND was invoked on the resource
+ http://www.example.com/container/ with a Depth header of 1, meaning
+ the request applies to the resource and its children, and a propfind
+ XML element containing the allprop XML element, meaning the request
+ should return the name and value of all the dead properties defined
+ on the resources, plus the name and value of all the properties
+ defined in this specification. This example illustrates the use of
+ relative references in the 'href' elements of the response.
+
+ The resource http://www.example.com/container/ has six properties
+ defined on it: 'bigbox' and 'author in the
+ "http://ns.example.com/boxschema/" namespace, DAV:creationdate, DAV:
+ displayname, DAV:resourcetype, and DAV:supportedlock.
+
+
+
+
+
+Dusseault Standards Track [Page 42]
+
+RFC 4918 WebDAV June 2007
+
+
+ The last four properties are WebDAV-specific, defined in Section 15.
+ Since GET is not supported on this resource, the get* properties
+ (e.g., DAV:getcontentlength) are not defined on this resource. The
+ WebDAV-specific properties assert that "container" was created on
+ December 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
+ (DAV:creationdate), has a name of "Example collection" (DAV:
+ displayname), a collection resource type (DAV:resourcetype), and
+ supports exclusive write and shared write locks (DAV:supportedlock).
+
+ The resource http://www.example.com/container/front.html has nine
+ properties defined on it:
+
+ 'bigbox' in the "http://ns.example.com/boxschema/" namespace (another
+ instance of the "bigbox" property type), DAV:creationdate, DAV:
+ displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
+ DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
+
+ The DAV-specific properties assert that "front.html" was created on
+ December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
+ (DAV:creationdate), has a name of "Example HTML resource" (DAV:
+ displayname), a content length of 4525 bytes (DAV:getcontentlength),
+ a MIME type of "text/html" (DAV:getcontenttype), an entity tag of
+ "zzyzx" (DAV:getetag), was last modified on Monday, January 12, 1998,
+ at 09:25:56 GMT (DAV:getlastmodified), has an empty resource type,
+ meaning that it is not a collection (DAV:resourcetype), and supports
+ both exclusive write and shared write locks (DAV:supportedlock).
+
+9.1.6. Example - Using 'allprop' with 'include'
+
+ >>Request
+
+ PROPFIND /mycol/ HTTP/1.1
+ Host: www.example.com
+ Depth: 1
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ <D:include>
+ <D:supported-live-property-set/>
+ <D:supported-report-set/>
+ </D:include>
+ </D:propfind>
+
+
+
+
+
+
+Dusseault Standards Track [Page 43]
+
+RFC 4918 WebDAV June 2007
+
+
+ In this example, PROPFIND is executed on the resource
+ http://www.example.com/mycol/ and its internal member resources. The
+ client requests the values of all live properties defined in this
+ specification, plus all dead properties, plus two more live
+ properties defined in [RFC3253]. The response is not shown.
+
+9.2. PROPPATCH Method
+
+ The PROPPATCH method processes instructions specified in the request
+ body to set and/or remove properties defined on the resource
+ identified by the Request-URI.
+
+ All DAV-compliant resources MUST support the PROPPATCH method and
+ MUST process instructions that are specified using the
+ propertyupdate, set, and remove XML elements. Execution of the
+ directives in this method is, of course, subject to access control
+ constraints. DAV-compliant resources SHOULD support the setting of
+ arbitrary dead properties.
+
+ The request message body of a PROPPATCH method MUST contain the
+ propertyupdate XML element.
+
+ Servers MUST process PROPPATCH instructions in document order (an
+ exception to the normal rule that ordering is irrelevant).
+ Instructions MUST either all be executed or none executed. Thus, if
+ any error occurs during processing, all executed instructions MUST be
+ undone and a proper error result returned. Instruction processing
+ details can be found in the definition of the set and remove
+ instructions in Sections 14.23 and 14.26.
+
+ If a server attempts to make any of the property changes in a
+ PROPPATCH request (i.e., the request is not rejected for high-level
+ errors before processing the body), the response MUST be a Multi-
+ Status response as described in Section 9.2.1.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.2.1. Status Codes for Use in 'propstat' Element
+
+ In PROPPATCH responses, information about individual properties is
+ returned inside 'propstat' elements (see Section 14.22), each
+ containing an individual 'status' element containing information
+ about the properties appearing in it. The list below summarizes the
+ most common status codes used inside 'propstat'; however, clients
+ should be prepared to handle other 2/3/4/5xx series status codes as
+ well.
+
+
+
+
+Dusseault Standards Track [Page 44]
+
+RFC 4918 WebDAV June 2007
+
+
+ 200 (OK) - The property set or change succeeded. Note that if this
+ appears for one property, it appears for every property in the
+ response, due to the atomicity of PROPPATCH.
+
+ 403 (Forbidden) - The client, for reasons the server chooses not to
+ specify, cannot alter one of the properties.
+
+ 403 (Forbidden): The client has attempted to set a protected
+ property, such as DAV:getetag. If returning this error, the server
+ SHOULD use the precondition code 'cannot-modify-protected-property'
+ inside the response body.
+
+ 409 (Conflict) - The client has provided a value whose semantics are
+ not appropriate for the property.
+
+ 424 (Failed Dependency) - The property change could not be made
+ because of another property change that failed.
+
+ 507 (Insufficient Storage) - The server did not have sufficient space
+ to record the property.
+
+9.2.2. Example - PROPPATCH
+
+ >>Request
+
+ PROPPATCH /bar.html HTTP/1.1
+ Host: www.example.com
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propertyupdate xmlns:D="DAV:"
+ xmlns:Z="http://ns.example.com/standards/z39.50/">
+ <D:set>
+ <D:prop>
+ <Z:Authors>
+ <Z:Author>Jim Whitehead</Z:Author>
+ <Z:Author>Roy Fielding</Z:Author>
+ </Z:Authors>
+ </D:prop>
+ </D:set>
+ <D:remove>
+ <D:prop><Z:Copyright-Owner/></D:prop>
+ </D:remove>
+ </D:propertyupdate>
+
+
+
+
+
+
+Dusseault Standards Track [Page 45]
+
+RFC 4918 WebDAV June 2007
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:Z="http://ns.example.com/standards/z39.50/">
+ <D:response>
+ <D:href>http://www.example.com/bar.html</D:href>
+ <D:propstat>
+ <D:prop><Z:Authors/></D:prop>
+ <D:status>HTTP/1.1 424 Failed Dependency</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop><Z:Copyright-Owner/></D:prop>
+ <D:status>HTTP/1.1 409 Conflict</D:status>
+ </D:propstat>
+ <D:responsedescription> Copyright Owner cannot be deleted or
+ altered.</D:responsedescription>
+ </D:response>
+ </D:multistatus>
+
+ In this example, the client requests the server to set the value of
+ the "Authors" property in the
+ "http://ns.example.com/standards/z39.50/" namespace, and to remove
+ the property "Copyright-Owner" in the same namespace. Since the
+ Copyright-Owner property could not be removed, no property
+ modifications occur. The 424 (Failed Dependency) status code for the
+ Authors property indicates this action would have succeeded if it
+ were not for the conflict with removing the Copyright-Owner property.
+
+9.3. MKCOL Method
+
+ MKCOL creates a new collection resource at the location specified by
+ the Request-URI. If the Request-URI is already mapped to a resource,
+ then the MKCOL MUST fail. During MKCOL processing, a server MUST
+ make the Request-URI an internal member of its parent collection,
+ unless the Request-URI is "/". If no such ancestor exists, the
+ method MUST fail. When the MKCOL operation creates a new collection
+ resource, all ancestors MUST already exist, or the method MUST fail
+ with a 409 (Conflict) status code. For example, if a request to
+ create collection /a/b/c/d/ is made, and /a/b/c/ does not exist, the
+ request must fail.
+
+ When MKCOL is invoked without a request body, the newly created
+ collection SHOULD have no members.
+
+
+
+Dusseault Standards Track [Page 46]
+
+RFC 4918 WebDAV June 2007
+
+
+ A MKCOL request message may contain a message body. The precise
+ behavior of a MKCOL request when the body is present is undefined,
+ but limited to creating collections, members of a collection, bodies
+ of members, and properties on the collections or members. If the
+ server receives a MKCOL request entity type it does not support or
+ understand, it MUST respond with a 415 (Unsupported Media Type)
+ status code. If the server decides to reject the request based on
+ the presence of an entity or the type of an entity, it should use the
+ 415 (Unsupported Media Type) status code.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.3.1. MKCOL Status Codes
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to MKCOL:
+
+ 201 (Created) - The collection was created.
+
+ 403 (Forbidden) - This indicates at least one of two conditions: 1)
+ the server does not allow the creation of collections at the given
+ location in its URL namespace, or 2) the parent collection of the
+ Request-URI exists but cannot accept members.
+
+ 405 (Method Not Allowed) - MKCOL can only be executed on an unmapped
+ URL.
+
+ 409 (Conflict) - A collection cannot be made at the Request-URI until
+ one or more intermediate collections have been created. The server
+ MUST NOT create those intermediate collections automatically.
+
+ 415 (Unsupported Media Type) - The server does not support the
+ request body type (although bodies are legal on MKCOL requests, since
+ this specification doesn't define any, the server is likely not to
+ support any given body type).
+
+ 507 (Insufficient Storage) - The resource does not have sufficient
+ space to record the state of the resource after the execution of this
+ method.
+
+9.3.2. Example - MKCOL
+
+ This example creates a collection called /webdisc/xfiles/ on the
+ server www.example.com.
+
+
+
+
+
+
+Dusseault Standards Track [Page 47]
+
+RFC 4918 WebDAV June 2007
+
+
+ >>Request
+
+ MKCOL /webdisc/xfiles/ HTTP/1.1
+ Host: www.example.com
+
+
+ >>Response
+
+ HTTP/1.1 201 Created
+
+9.4. GET, HEAD for Collections
+
+ The semantics of GET are unchanged when applied to a collection,
+ since GET is defined as, "retrieve whatever information (in the form
+ of an entity) is identified by the Request-URI" [RFC2616]. GET, when
+ applied to a collection, may return the contents of an "index.html"
+ resource, a human-readable view of the contents of the collection, or
+ something else altogether. Hence, it is possible that the result of
+ a GET on a collection will bear no correlation to the membership of
+ the collection.
+
+ Similarly, since the definition of HEAD is a GET without a response
+ message body, the semantics of HEAD are unmodified when applied to
+ collection resources.
+
+9.5. POST for Collections
+
+ Since by definition the actual function performed by POST is
+ determined by the server and often depends on the particular
+ resource, the behavior of POST when applied to collections cannot be
+ meaningfully modified because it is largely undefined. Thus, the
+ semantics of POST are unmodified when applied to a collection.
+
+9.6. DELETE Requirements
+
+ DELETE is defined in [RFC2616], Section 9.7, to "delete the resource
+ identified by the Request-URI". However, WebDAV changes some DELETE
+ handling requirements.
+
+ A server processing a successful DELETE request:
+
+ MUST destroy locks rooted on the deleted resource
+
+ MUST remove the mapping from the Request-URI to any resource.
+
+ Thus, after a successful DELETE operation (and in the absence of
+ other actions), a subsequent GET/HEAD/PROPFIND request to the target
+ Request-URI MUST return 404 (Not Found).
+
+
+
+Dusseault Standards Track [Page 48]
+
+RFC 4918 WebDAV June 2007
+
+
+9.6.1. DELETE for Collections
+
+ The DELETE method on a collection MUST act as if a "Depth: infinity"
+ header was used on it. A client MUST NOT submit a Depth header with
+ a DELETE on a collection with any value but infinity.
+
+ DELETE instructs that the collection specified in the Request-URI and
+ all resources identified by its internal member URLs are to be
+ deleted.
+
+ If any resource identified by a member URL cannot be deleted, then
+ all of the member's ancestors MUST NOT be deleted, so as to maintain
+ URL namespace consistency.
+
+ Any headers included with DELETE MUST be applied in processing every
+ resource to be deleted.
+
+ When the DELETE method has completed processing, it MUST result in a
+ consistent URL namespace.
+
+ If an error occurs deleting a member resource (a resource other than
+ the resource identified in the Request-URI), then the response can be
+ a 207 (Multi-Status). Multi-Status is used here to indicate which
+ internal resources could NOT be deleted, including an error code,
+ which should help the client understand which resources caused the
+ failure. For example, the Multi-Status body could include a response
+ with status 423 (Locked) if an internal resource was locked.
+
+ The server MAY return a 4xx status response, rather than a 207, if
+ the request failed completely.
+
+ 424 (Failed Dependency) status codes SHOULD NOT be in the 207 (Multi-
+ Status) response for DELETE. They can be safely left out because the
+ client will know that the ancestors of a resource could not be
+ deleted when the client receives an error for the ancestor's progeny.
+ Additionally, 204 (No Content) errors SHOULD NOT be returned in the
+ 207 (Multi-Status). The reason for this prohibition is that 204 (No
+ Content) is the default success code.
+
+9.6.2. Example - DELETE
+
+ >>Request
+
+ DELETE /container/ HTTP/1.1
+ Host: www.example.com
+
+
+
+
+
+
+Dusseault Standards Track [Page 49]
+
+RFC 4918 WebDAV June 2007
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/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.example.com/container/resource3</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ <d:error><d:lock-token-submitted/></d:error>
+ </d:response>
+ </d:multistatus>
+
+ In this example, the attempt to delete
+ http://www.example.com/container/resource3 failed because it is
+ locked, and no lock token was submitted with the request.
+ Consequently, the attempt to delete http://www.example.com/container/
+ also failed. Thus, the client knows that the attempt to delete
+ http://www.example.com/container/ must have also failed since the
+ parent cannot be deleted unless its child has also been deleted.
+ Even though a Depth header has not been included, a depth of infinity
+ is assumed because the method is on a collection.
+
+9.7. PUT Requirements
+
+9.7.1. PUT for Non-Collection Resources
+
+ A PUT performed on an existing resource replaces the GET response
+ entity of the resource. Properties defined on the resource may be
+ recomputed during PUT processing but are not otherwise affected. For
+ example, if a server recognizes the content type of the request body,
+ it may be able to automatically extract information that could be
+ profitably exposed as properties.
+
+ A PUT that would result in the creation of a resource without an
+ appropriately scoped parent collection MUST fail with a 409
+ (Conflict).
+
+ A PUT request allows a client to indicate what media type an entity
+ body has, and whether it should change if overwritten. Thus, a
+ client SHOULD provide a Content-Type for a new resource if any is
+ known. If the client does not provide a Content-Type for a new
+ resource, the server MAY create a resource with no Content-Type
+ assigned, or it MAY attempt to assign a Content-Type.
+
+
+
+
+
+Dusseault Standards Track [Page 50]
+
+RFC 4918 WebDAV June 2007
+
+
+ Note that although a recipient ought generally to treat metadata
+ supplied with an HTTP request as authoritative, in practice there's
+ no guarantee that a server will accept client-supplied metadata
+ (e.g., any request header beginning with "Content-"). Many servers
+ do not allow configuring the Content-Type on a per-resource basis in
+ the first place. Thus, clients can't always rely on the ability to
+ directly influence the content type by including a Content-Type
+ request header.
+
+9.7.2. PUT for Collections
+
+ This specification does not define the behavior of the PUT method for
+ existing collections. A PUT request to an existing collection MAY be
+ treated as an error (405 Method Not Allowed).
+
+ The MKCOL method is defined to create collections.
+
+9.8. COPY Method
+
+ The COPY method creates a duplicate of the source resource identified
+ by the Request-URI, in the destination resource identified by the URI
+ in the Destination header. The Destination header MUST be present.
+ The exact behavior of the COPY method depends on the type of the
+ source resource.
+
+ All WebDAV-compliant resources MUST support the COPY method.
+ However, support for the COPY method does not guarantee the ability
+ to copy a resource. For example, separate programs may control
+ resources on the same server. As a result, it may not be possible to
+ copy a resource to a location that appears to be on the same server.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.8.1. COPY for Non-collection Resources
+
+ When the source resource is not a collection, the result of the COPY
+ method is the creation of a new resource at the destination whose
+ state and behavior match that of the source resource as closely as
+ possible. Since the environment at the destination may be different
+ than at the source due to factors outside the scope of control of the
+ server, such as the absence of resources required for correct
+ operation, it may not be possible to completely duplicate the
+ behavior of the resource at the destination. Subsequent alterations
+ to the destination resource will not modify the source resource.
+ Subsequent alterations to the source resource will not modify the
+ destination resource.
+
+
+
+
+Dusseault Standards Track [Page 51]
+
+RFC 4918 WebDAV June 2007
+
+
+9.8.2. COPY for Properties
+
+ After a successful COPY invocation, all dead properties on the source
+ resource SHOULD be duplicated on the destination resource. Live
+ properties described in this document SHOULD be duplicated as
+ identically behaving live properties at the destination resource, but
+ not necessarily with the same values. Servers SHOULD NOT convert
+ live properties into dead properties on the destination resource,
+ because clients may then draw incorrect conclusions about the state
+ or functionality of a resource. Note that some live properties are
+ defined such that the absence of the property has a specific meaning
+ (e.g., a flag with one meaning if present, and the opposite if
+ absent), and in these cases, a successful COPY might result in the
+ property being reported as "Not Found" in subsequent requests.
+
+ When the destination is an unmapped URL, a COPY operation creates a
+ new resource much like a PUT operation does. Live properties that
+ are related to resource creation (such as DAV:creationdate) should
+ have their values set accordingly.
+
+9.8.3. COPY for Collections
+
+ The COPY method on a collection without a Depth header MUST act as if
+ a Depth header with value "infinity" was included. A client may
+ submit a Depth header on a COPY on a collection with a value of "0"
+ or "infinity". Servers MUST support the "0" and "infinity" Depth
+ header behaviors on WebDAV-compliant resources.
+
+ An infinite-depth COPY instructs that the collection resource
+ identified by the Request-URI is to be copied to the location
+ identified by the URI in the Destination header, and all its internal
+ member resources are to be copied to a location relative to it,
+ recursively through all levels of the collection hierarchy. Note
+ that an infinite-depth COPY of /A/ into /A/B/ could lead to infinite
+ recursion if not handled correctly.
+
+ A COPY of "Depth: 0" only instructs that the collection and its
+ properties, but not resources identified by its internal member URLs,
+ are to be copied.
+
+ Any headers included with a COPY MUST be applied in processing every
+ resource to be copied with the exception of the Destination header.
+
+ The Destination header only specifies the destination URI for the
+ Request-URI. When applied to members of the collection identified by
+ the Request-URI, the value of Destination is to be modified to
+ reflect the current location in the hierarchy. So, if the Request-
+ URI is /a/ with Host header value http://example.com/ and the
+
+
+
+Dusseault Standards Track [Page 52]
+
+RFC 4918 WebDAV June 2007
+
+
+ Destination is http://example.com/b/, then when
+ http://example.com/a/c/d is processed, it must use a Destination of
+ http://example.com/b/c/d.
+
+ When the COPY method has completed processing, it MUST have created a
+ consistent URL namespace at the destination (see Section 5.1 for the
+ definition of namespace consistency). However, if an error occurs
+ while copying an internal collection, the server MUST NOT copy any
+ resources identified by members of this collection (i.e., the server
+ must skip this subtree), as this would create an inconsistent
+ namespace. After detecting an error, the COPY operation SHOULD try
+ to finish as much of the original copy operation as possible (i.e.,
+ the server should still attempt to copy other subtrees and their
+ members that are not descendants of an error-causing collection).
+
+ So, for example, if an infinite-depth copy operation is performed on
+ collection /a/, which contains collections /a/b/ and /a/c/, and an
+ error occurs copying /a/b/, an attempt should still be made to copy
+ /a/c/. Similarly, after encountering an error copying a non-
+ collection resource as part of an infinite-depth copy, the server
+ SHOULD try to finish as much of the original copy operation as
+ possible.
+
+ If an error in executing the COPY method occurs with a resource other
+ than the resource identified in the Request-URI, then the response
+ MUST be a 207 (Multi-Status), and the URL of the resource causing the
+ failure MUST appear with the specific error.
+
+ The 424 (Failed Dependency) status code SHOULD NOT be returned in the
+ 207 (Multi-Status) response from a COPY method. These responses can
+ be safely omitted because the client will know that the progeny of a
+ resource could not be copied when the client receives an error for
+ the parent. Additionally, 201 (Created)/204 (No Content) status
+ codes SHOULD NOT be returned as values in 207 (Multi-Status)
+ responses from COPY methods. They, too, can be safely omitted
+ because they are the default success codes.
+
+9.8.4. COPY and Overwriting Destination Resources
+
+ If a COPY request has an Overwrite header with a value of "F", and a
+ resource exists at the Destination URL, the server MUST fail the
+ request.
+
+ When a server executes a COPY request and overwrites a destination
+ resource, the exact behavior MAY depend on many factors, including
+ WebDAV extension capabilities (see particularly [RFC3253]). For
+
+
+
+
+
+Dusseault Standards Track [Page 53]
+
+RFC 4918 WebDAV June 2007
+
+
+ example, when an ordinary resource is overwritten, the server could
+ delete the target resource before doing the copy, or could do an in-
+ place overwrite to preserve live properties.
+
+ When a collection is overwritten, the membership of the destination
+ collection after the successful COPY request MUST be the same
+ membership as the source collection immediately before the COPY.
+ Thus, merging the membership of the source and destination
+ collections together in the destination is not a compliant behavior.
+
+ In general, if clients require the state of the destination URL to be
+ wiped out prior to a COPY (e.g., to force live properties to be
+ reset), then the client could send a DELETE to the destination before
+ the COPY request to ensure this reset.
+
+9.8.5. Status Codes
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to COPY:
+
+ 201 (Created) - The source resource was successfully copied. The
+ COPY operation resulted in the creation of a new resource.
+
+ 204 (No Content) - The source resource was successfully copied to a
+ preexisting destination resource.
+
+ 207 (Multi-Status) - Multiple resources were to be affected by the
+ COPY, but errors on some of them prevented the operation from taking
+ place. Specific error messages, together with the most appropriate
+ of the source and destination URLs, appear in the body of the multi-
+ status response. For example, if a destination resource was locked
+ and could not be overwritten, then the destination resource URL
+ appears with the 423 (Locked) status.
+
+ 403 (Forbidden) - The operation is forbidden. A special case for
+ COPY could be that the source and destination resources are the same
+ resource.
+
+ 409 (Conflict) - A resource cannot be created at the destination
+ until one or more intermediate collections have been created. The
+ server MUST NOT create those intermediate collections automatically.
+
+ 412 (Precondition Failed) - A precondition header check failed, e.g.,
+ the Overwrite header is "F" and the destination URL is already mapped
+ to a resource.
+
+
+
+
+
+
+Dusseault Standards Track [Page 54]
+
+RFC 4918 WebDAV June 2007
+
+
+ 423 (Locked) - The destination resource, or resource within the
+ destination collection, was locked. This response SHOULD contain the
+ 'lock-token-submitted' precondition element.
+
+ 502 (Bad Gateway) - This may occur when the destination is on another
+ server, repository, or URL namespace. Either the source namespace
+ does not support copying to the destination namespace, or the
+ destination namespace refuses to accept the resource. The client may
+ wish to try GET/PUT and PROPFIND/PROPPATCH instead.
+
+ 507 (Insufficient Storage) - The destination resource does not have
+ sufficient space to record the state of the resource after the
+ execution of this method.
+
+9.8.6. Example - COPY with Overwrite
+
+ This example shows resource
+ http://www.example.com/~fielding/index.html being copied to the
+ location http://www.example.com/users/f/fielding/index.html. The 204
+ (No Content) status code indicates that the existing resource at the
+ destination was overwritten.
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/users/f/fielding/index.html
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+9.8.7. Example - COPY with No Overwrite
+
+ The following example shows the same copy operation being performed,
+ but with the Overwrite header set to "F." A response of 412
+ (Precondition Failed) is returned because the destination URL is
+ already mapped to a resource.
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/users/f/fielding/index.html
+ Overwrite: F
+
+
+
+
+
+
+Dusseault Standards Track [Page 55]
+
+RFC 4918 WebDAV June 2007
+
+
+ >>Response
+
+ HTTP/1.1 412 Precondition Failed
+
+9.8.8. Example - COPY of a Collection
+
+ >>Request
+
+ COPY /container/ HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/othercontainer/
+ Depth: infinity
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/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.example.com/othercontainer/R2/</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ <d:error><d:lock-token-submitted/></d:error>
+ </d:response>
+ </d:multistatus>
+
+ The Depth header is unnecessary as the default behavior of COPY on a
+ collection is to act as if a "Depth: infinity" header had been
+ submitted. In this example, most of the resources, along with the
+ collection, were copied successfully. However, the collection R2
+ failed because the destination R2 is locked. Because there was an
+ error copying R2, none of R2's members were copied. However, no
+ errors were listed for those members due to the error minimization
+ rules.
+
+9.9. MOVE Method
+
+ The MOVE operation on a non-collection resource is the logical
+ equivalent of a copy (COPY), followed by consistency maintenance
+ processing, followed by a delete of the source, where all three
+ actions are performed in a single operation. The consistency
+ maintenance step allows the server to perform updates caused by the
+ move, such as updating all URLs, other than the Request-URI that
+ identifies the source resource, to point to the new destination
+ resource.
+
+
+
+Dusseault Standards Track [Page 56]
+
+RFC 4918 WebDAV June 2007
+
+
+ The Destination header MUST be present on all MOVE methods and MUST
+ follow all COPY requirements for the COPY part of the MOVE method.
+ All WebDAV-compliant resources MUST support the MOVE method.
+
+ Support for the MOVE method does not guarantee the ability to move a
+ resource to a particular destination. For example, separate programs
+ may actually control different sets of resources on the same server.
+ Therefore, it may not be possible to move a resource within a
+ namespace that appears to belong to the same server.
+
+ If a resource exists at the destination, the destination resource
+ will be deleted as a side-effect of the MOVE operation, subject to
+ the restrictions of the Overwrite header.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.9.1. MOVE for Properties
+
+ Live properties described in this document SHOULD be moved along with
+ the resource, such that the resource has identically behaving live
+ properties at the destination resource, but not necessarily with the
+ same values. Note that some live properties are defined such that
+ the absence of the property has a specific meaning (e.g., a flag with
+ one meaning if present, and the opposite if absent), and in these
+ cases, a successful MOVE might result in the property being reported
+ as "Not Found" in subsequent requests. If the live properties will
+ not work the same way at the destination, the server MAY fail the
+ request.
+
+ MOVE is frequently used by clients to rename a file without changing
+ its parent collection, so it's not appropriate to reset all live
+ properties that are set at resource creation. For example, the DAV:
+ creationdate property value SHOULD remain the same after a MOVE.
+
+ Dead properties MUST be moved along with the resource.
+
+9.9.2. MOVE for Collections
+
+ A MOVE with "Depth: infinity" instructs that the collection
+ identified by the Request-URI be moved to the address specified in
+ the Destination header, and all resources identified by its internal
+ member URLs are to be moved to locations relative to it, recursively
+ through all levels of the collection hierarchy.
+
+ The MOVE method on a collection MUST act as if a "Depth: infinity"
+ header was used on it. A client MUST NOT submit a Depth header on a
+ MOVE on a collection with any value but "infinity".
+
+
+
+Dusseault Standards Track [Page 57]
+
+RFC 4918 WebDAV June 2007
+
+
+ Any headers included with MOVE MUST be applied in processing every
+ resource to be moved with the exception of the Destination header.
+ The behavior of the Destination header is the same as given for COPY
+ on collections.
+
+ When the MOVE method has completed processing, it MUST have created a
+ consistent URL namespace at both the source and destination (see
+ Section 5.1 for the definition of namespace consistency). However,
+ if an error occurs while moving an internal collection, the server
+ MUST NOT move any resources identified by members of the failed
+ collection (i.e., the server must skip the error-causing subtree), as
+ this would create an inconsistent namespace. In this case, after
+ detecting the error, the move operation SHOULD try to finish as much
+ of the original move as possible (i.e., the server should still
+ attempt to move other subtrees and the resources identified by their
+ members that are not descendants of an error-causing collection).
+ So, for example, if an infinite-depth move is performed on collection
+ /a/, which contains collections /a/b/ and /a/c/, and an error occurs
+ moving /a/b/, an attempt should still be made to try moving /a/c/.
+ Similarly, after encountering an error moving a non-collection
+ resource as part of an infinite-depth move, the server SHOULD try to
+ finish as much of the original move operation as possible.
+
+ If an error occurs with a resource other than the resource identified
+ in the Request-URI, then the response MUST be a 207 (Multi-Status),
+ and the errored resource's URL MUST appear with the specific error.
+
+ The 424 (Failed Dependency) status code SHOULD NOT be returned in the
+ 207 (Multi-Status) response from a MOVE method. These errors can be
+ safely omitted because the client will know that the progeny of a
+ resource could not be moved when the client receives an error for the
+ parent. Additionally, 201 (Created)/204 (No Content) responses
+ SHOULD NOT be returned as values in 207 (Multi-Status) responses from
+ a MOVE. These responses can be safely omitted because they are the
+ default success codes.
+
+9.9.3. MOVE and the Overwrite Header
+
+ If a resource exists at the destination and the Overwrite header is
+ "T", then prior to performing the move, the server MUST perform a
+ DELETE with "Depth: infinity" on the destination resource. If the
+ Overwrite header is set to "F", then the operation will fail.
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 58]
+
+RFC 4918 WebDAV June 2007
+
+
+9.9.4. Status Codes
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to MOVE:
+
+ 201 (Created) - The source resource was successfully moved, and a new
+ URL mapping was created at the destination.
+
+ 204 (No Content) - The source resource was successfully moved to a
+ URL that was already mapped.
+
+ 207 (Multi-Status) - Multiple resources were to be affected by the
+ MOVE, but errors on some of them prevented the operation from taking
+ place. Specific error messages, together with the most appropriate
+ of the source and destination URLs, appear in the body of the multi-
+ status response. For example, if a source resource was locked and
+ could not be moved, then the source resource URL appears with the 423
+ (Locked) status.
+
+ 403 (Forbidden) - Among many possible reasons for forbidding a MOVE
+ operation, this status code is recommended for use when the source
+ and destination resources are the same.
+
+ 409 (Conflict) - A resource cannot be created at the destination
+ until one or more intermediate collections have been created. The
+ server MUST NOT create those intermediate collections automatically.
+ Or, the server was unable to preserve the behavior of the live
+ properties and still move the resource to the destination (see
+ 'preserved-live-properties' postcondition).
+
+ 412 (Precondition Failed) - A condition header failed. Specific to
+ MOVE, this could mean that the Overwrite header is "F" and the
+ destination URL is already mapped to a resource.
+
+ 423 (Locked) - The source or the destination resource, the source or
+ destination resource parent, or some resource within the source or
+ destination collection, was locked. This response SHOULD contain the
+ 'lock-token-submitted' precondition element.
+
+ 502 (Bad Gateway) - This may occur when the destination is on another
+ server and the destination server refuses to accept the resource.
+ This could also occur when the destination is on another sub-section
+ of the same server namespace.
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 59]
+
+RFC 4918 WebDAV June 2007
+
+
+9.9.5. Example - MOVE of a Non-Collection
+
+ This example shows resource
+ http://www.example.com/~fielding/index.html being moved to the
+ location http://www.example.com/users/f/fielding/index.html. The
+ contents of the destination resource would have been overwritten if
+ the destination URL was already mapped to a resource. In this case,
+ since there was nothing at the destination resource, the response
+ code is 201 (Created).
+
+ >>Request
+
+ MOVE /~fielding/index.html HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example/users/f/fielding/index.html
+
+ >>Response
+
+ HTTP/1.1 201 Created
+ Location: http://www.example.com/users/f/fielding/index.html
+
+9.9.6. Example - MOVE of a Collection
+
+ >>Request
+
+ MOVE /container/ HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/othercontainer/
+ Overwrite: F
+ If: (<urn:uuid:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
+ (<urn:uuid:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/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.example.com/othercontainer/C2/</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ <d:error><d:lock-token-submitted/></d:error>
+ </d:response>
+ </d:multistatus>
+
+
+
+
+
+Dusseault Standards Track [Page 60]
+
+RFC 4918 WebDAV June 2007
+
+
+ In this example, the client has submitted a number of lock tokens
+ with the request. A lock token will need to be submitted for every
+ resource, both source and destination, anywhere in the scope of the
+ method, that is locked. In this case, the proper lock token was not
+ submitted for the destination
+ http://www.example.com/othercontainer/C2/. This means that the
+ resource /container/C2/ could not be moved. Because there was an
+ error moving /container/C2/, none of /container/C2's members were
+ moved. However, no errors were listed for those members due to the
+ error minimization rules. User agent authentication has previously
+ occurred via a mechanism outside the scope of the HTTP protocol, in
+ an underlying transport layer.
+
+9.10. LOCK Method
+
+ The following sections describe the LOCK method, which is used to
+ take out a lock of any access type and to refresh an existing lock.
+ These sections on the LOCK method describe only those semantics that
+ are specific to the LOCK method and are independent of the access
+ type of the lock being requested.
+
+ Any resource that supports the LOCK method MUST, at minimum, support
+ the XML request and response formats defined herein.
+
+ This method is neither idempotent nor safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.10.1. Creating a Lock on an Existing Resource
+
+ A LOCK request to an existing resource will create a lock on the
+ resource identified by the Request-URI, provided the resource is not
+ already locked with a conflicting lock. The resource identified in
+ the Request-URI becomes the root of the lock. LOCK method requests
+ to create a new lock MUST have an XML request body. The server MUST
+ preserve the information provided by the client in the 'owner'
+ element in the LOCK request. The LOCK request MAY have a Timeout
+ header.
+
+ When a new lock is created, the LOCK response:
+
+ o MUST contain a body with the value of the DAV:lockdiscovery
+ property in a prop XML element. This MUST contain the full
+ information about the lock just granted, while information about
+ other (shared) locks is OPTIONAL.
+
+ o MUST include the Lock-Token response header with the token
+ associated with the new lock.
+
+
+
+
+Dusseault Standards Track [Page 61]
+
+RFC 4918 WebDAV June 2007
+
+
+9.10.2. Refreshing Locks
+
+ A lock is refreshed by sending a LOCK request to the URL of a
+ resource within the scope of the lock. This request MUST NOT have a
+ body and it MUST specify which lock to refresh by using the 'If'
+ header with a single lock token (only one lock may be refreshed at a
+ time). The request MAY contain a Timeout header, which a server MAY
+ accept to change the duration remaining on the lock to the new value.
+ A server MUST ignore the Depth header on a LOCK refresh.
+
+ If the resource has other (shared) locks, those locks are unaffected
+ by a lock refresh. Additionally, those locks do not prevent the
+ named lock from being refreshed.
+
+ The Lock-Token header is not returned in the response for a
+ successful refresh LOCK request, but the LOCK response body MUST
+ contain the new value for the DAV:lockdiscovery property.
+
+9.10.3. Depth and Locking
+
+ The Depth header may be used with the LOCK method. Values other than
+ 0 or infinity MUST NOT be used with the Depth header on a LOCK
+ method. All resources that support the LOCK method MUST support the
+ Depth header.
+
+ A Depth header of value 0 means to just lock the resource specified
+ by the Request-URI.
+
+ If the Depth header is set to infinity, then the resource specified
+ in the Request-URI along with all its members, all the way down the
+ hierarchy, are to be locked. A successful result MUST return a
+ single lock token. Similarly, if an UNLOCK is successfully executed
+ on this token, all associated resources are unlocked. Hence, partial
+ success is not an option for LOCK or UNLOCK. Either the entire
+ hierarchy is locked or no resources are locked.
+
+ If the lock cannot be granted to all resources, the server MUST
+ return a Multi-Status response with a 'response' element for at least
+ one resource that prevented the lock from being granted, along with a
+ suitable status code for that failure (e.g., 403 (Forbidden) or 423
+ (Locked)). Additionally, if the resource causing the failure was not
+ the resource requested, then the server SHOULD include a 'response'
+ element for the Request-URI as well, with a 'status' element
+ containing 424 Failed Dependency.
+
+ If no Depth header is submitted on a LOCK request, then the request
+ MUST act as if a "Depth:infinity" had been submitted.
+
+
+
+
+Dusseault Standards Track [Page 62]
+
+RFC 4918 WebDAV June 2007
+
+
+9.10.4. Locking Unmapped URLs
+
+ A successful LOCK method MUST result in the creation of an empty
+ resource that is locked (and that is not a collection) when a
+ resource did not previously exist at that URL. Later on, the lock
+ may go away but the empty resource remains. Empty resources MUST
+ then appear in PROPFIND responses including that URL in the response
+ scope. A server MUST respond successfully to a GET request to an
+ empty resource, either by using a 204 No Content response, or by
+ using 200 OK with a Content-Length header indicating zero length
+
+9.10.5. Lock Compatibility Table
+
+ The table below describes the behavior that occurs when a lock
+ request is made on a resource.
+
+ +--------------------------+----------------+-------------------+
+ | Current State | Shared Lock OK | Exclusive Lock OK |
+ +--------------------------+----------------+-------------------+
+ | None | True | True |
+ | Shared Lock | True | False |
+ | Exclusive Lock | False | False* |
+ +--------------------------+----------------+-------------------+
+
+ Legend: True = lock may be granted. False = lock MUST NOT be
+ granted. *=It is illegal for a principal to request the same lock
+ twice.
+
+ The current lock state of a resource is given in the leftmost column,
+ and lock requests are listed in the first row. The intersection of a
+ row and column gives the result of a lock request. For example, if a
+ shared lock is held on a resource, and an exclusive lock is
+ requested, the table entry is "false", indicating that the lock must
+ not be granted.
+
+9.10.6. LOCK Responses
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to LOCK:
+
+ 200 (OK) - The LOCK request succeeded and the value of the DAV:
+ lockdiscovery property is included in the response body.
+
+ 201 (Created) - The LOCK request was to an unmapped URL, the request
+ succeeded and resulted in the creation of a new resource, and the
+ value of the DAV:lockdiscovery property is included in the response
+ body.
+
+
+
+
+Dusseault Standards Track [Page 63]
+
+RFC 4918 WebDAV June 2007
+
+
+ 409 (Conflict) - A resource cannot be created at the destination
+ until one or more intermediate collections have been created. The
+ server MUST NOT create those intermediate collections automatically.
+
+ 423 (Locked), potentially with 'no-conflicting-lock' precondition
+ code - There is already a lock on the resource that is not compatible
+ with the requested lock (see lock compatibility table above).
+
+ 412 (Precondition Failed), with 'lock-token-matches-request-uri'
+ precondition code - The LOCK request was made with an If header,
+ indicating that the client wishes to refresh the given lock.
+ However, the Request-URI did not fall within the scope of the lock
+ identified by the token. The lock may have a scope that does not
+ include the Request-URI, or the lock could have disappeared, or the
+ token may be invalid.
+
+9.10.7. Example - Simple Lock Request
+
+ >>Request
+
+ LOCK /workspace/webdav/proposal.doc HTTP/1.1
+ Host: example.com
+ Timeout: Infinite, Second-4100000000
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="ejw@example.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:lockinfo xmlns:D='DAV:'>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ <D:owner>
+ <D:href>http://example.org/~ejw/contact.html</D:href>
+ </D:owner>
+ </D:lockinfo>
+
+ >>Response
+
+ HTTP/1.1 200 OK
+ Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:">
+
+
+
+Dusseault Standards Track [Page 64]
+
+RFC 4918 WebDAV June 2007
+
+
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>infinity</D:depth>
+ <D:owner>
+ <D:href>http://example.org/~ejw/contact.html</D:href>
+ </D:owner>
+ <D:timeout>Second-604800</D:timeout>
+ <D:locktoken>
+ <D:href
+ >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
+ </D:locktoken>
+ <D:lockroot>
+ <D:href
+ >http://example.com/workspace/webdav/proposal.doc</D:href>
+ </D:lockroot>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+
+
+ This example shows the successful creation of an exclusive write lock
+ on resource http://example.com/workspace/webdav/proposal.doc. The
+ resource http://example.org/~ejw/contact.html contains contact
+ information for the creator of the lock. The server has an activity-
+ based timeout policy in place on this resource, which causes the lock
+ to automatically be removed after 1 week (604800 seconds). Note that
+ the nonce, response, and opaque fields have not been calculated in
+ the Authorization request header.
+
+9.10.8. Example - Refreshing a Write Lock
+
+ >>Request
+
+ LOCK /workspace/webdav/proposal.doc HTTP/1.1
+ Host: example.com
+ Timeout: Infinite, Second-4100000000
+ If: (<urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>)
+ Authorization: Digest username="ejw",
+ realm="ejw@example.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 65]
+
+RFC 4918 WebDAV June 2007
+
+
+ >>Response
+
+ HTTP/1.1 200 OK
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:">
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>infinity</D:depth>
+ <D:owner>
+ <D:href>http://example.org/~ejw/contact.html</D:href>
+ </D:owner>
+ <D:timeout>Second-604800</D:timeout>
+ <D:locktoken>
+ <D:href
+ >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
+ </D:locktoken>
+ <D:lockroot>
+ <D:href
+ >http://example.com/workspace/webdav/proposal.doc</D:href>
+ </D:lockroot>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+
+
+ This request would refresh the lock, attempting to reset the timeout
+ to the new value specified in the timeout header. Notice that the
+ client asked for an infinite time out but the server choose to ignore
+ the request. In this example, the nonce, response, and opaque fields
+ have not been calculated in the Authorization request header.
+
+9.10.9. Example - Multi-Resource Lock Request
+
+ >>Request
+
+ LOCK /webdav/ HTTP/1.1
+ Host: example.com
+ Timeout: Infinite, Second-4100000000
+ Depth: infinity
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="ejw@example.com", nonce="...",
+
+
+
+Dusseault Standards Track [Page 66]
+
+RFC 4918 WebDAV June 2007
+
+
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:lockinfo xmlns:D="DAV:">
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:owner>
+ <D:href>http://example.org/~ejw/contact.html</D:href>
+ </D:owner>
+ </D:lockinfo>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://example.com/webdav/secret</D:href>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ </D:response>
+ <D:response>
+ <D:href>http://example.com/webdav/</D:href>
+ <D:status>HTTP/1.1 424 Failed Dependency</D:status>
+ </D:response>
+ </D:multistatus>
+
+
+ This example shows a request for an exclusive write lock on a
+ collection and all its children. In this request, the client has
+ specified that it desires an infinite-length lock, if available,
+ otherwise a timeout of 4.1 billion seconds, if available. The
+ request entity body contains the contact information for the
+ principal taking out the lock -- in this case, a Web page URL.
+
+ The error is a 403 (Forbidden) response on the resource
+ http://example.com/webdav/secret. Because this resource could not be
+ locked, none of the resources were locked. Note also that the a
+ 'response' element for the Request-URI itself has been included as
+ required.
+
+ In this example, the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+
+
+
+
+Dusseault Standards Track [Page 67]
+
+RFC 4918 WebDAV June 2007
+
+
+9.11. UNLOCK Method
+
+ The UNLOCK method removes the lock identified by the lock token in
+ the Lock-Token request header. The Request-URI MUST identify a
+ resource within the scope of the lock.
+
+ Note that use of the Lock-Token header to provide the lock token is
+ not consistent with other state-changing methods, which all require
+ an If header with the lock token. Thus, the If header is not needed
+ to provide the lock token. Naturally, when the If header is present,
+ it has its normal meaning as a conditional header.
+
+ For a successful response to this method, the server MUST delete the
+ lock entirely.
+
+ If all resources that have been locked under the submitted lock token
+ cannot be unlocked, then the UNLOCK request MUST fail.
+
+ A successful response to an UNLOCK method does not mean that the
+ resource is necessarily unlocked. It means that the specific lock
+ corresponding to the specified token no longer exists.
+
+ Any DAV-compliant resource that supports the LOCK method MUST support
+ the UNLOCK method.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.11.1. Status Codes
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to UNLOCK:
+
+ 204 (No Content) - Normal success response (rather than 200 OK, since
+ 200 OK would imply a response body, and an UNLOCK success response
+ does not normally contain a body).
+
+ 400 (Bad Request) - No lock token was provided.
+
+ 403 (Forbidden) - The currently authenticated principal does not have
+ permission to remove the lock.
+
+ 409 (Conflict), with 'lock-token-matches-request-uri' precondition -
+ The resource was not locked, or the request was made to a Request-URI
+ that was not within the scope of the lock.
+
+
+
+
+
+
+Dusseault Standards Track [Page 68]
+
+RFC 4918 WebDAV June 2007
+
+
+9.11.2. Example - UNLOCK
+
+ >>Request
+
+ UNLOCK /workspace/webdav/info.doc HTTP/1.1
+ Host: example.com
+ Lock-Token: <urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
+ Authorization: Digest username="ejw"
+ realm="ejw@example.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+ In this example, the lock identified by the lock token
+ "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully
+ removed from the resource
+ http://example.com/workspace/webdav/info.doc. If this lock included
+ more than just one resource, the lock is removed from all resources
+ included in the lock.
+
+ In this example, the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+10. HTTP Headers for Distributed Authoring
+
+ All DAV headers follow the same basic formatting rules as HTTP
+ headers. This includes rules like line continuation and how to
+ combine (or separate) multiple instances of the same header using
+ commas.
+
+ WebDAV adds two new conditional headers to the set defined in HTTP:
+ the If and Overwrite headers.
+
+10.1. DAV Header
+
+ DAV = "DAV" ":" #( compliance-class )
+ compliance-class = ( "1" | "2" | "3" | extend )
+ extend = Coded-URL | token
+ ; token is defined in RFC 2616, Section 2.2
+ Coded-URL = "<" absolute-URI ">"
+ ; No linear whitespace (LWS) allowed in Coded-URL
+ ; absolute-URI defined in RFC 3986, Section 4.3
+
+
+
+
+
+
+Dusseault Standards Track [Page 69]
+
+RFC 4918 WebDAV June 2007
+
+
+ This general-header appearing in the response indicates that the
+ resource supports the DAV schema and protocol as specified. All DAV-
+ compliant resources MUST return the DAV header with compliance-class
+ "1" on all OPTIONS responses. In cases where WebDAV is only
+ supported in part of the server namespace, an OPTIONS request to non-
+ WebDAV resources (including "/") SHOULD NOT advertise WebDAV support.
+
+ The value is a comma-separated list of all compliance class
+ identifiers that the resource supports. Class identifiers may be
+ Coded-URLs or tokens (as defined by [RFC2616]). Identifiers can
+ appear in any order. Identifiers that are standardized through the
+ IETF RFC process are tokens, but other identifiers SHOULD be Coded-
+ URLs to encourage uniqueness.
+
+ A resource must show class 1 compliance if it shows class 2 or 3
+ compliance. In general, support for one compliance class does not
+ entail support for any other, and in particular, support for
+ compliance class 3 does not require support for compliance class 2.
+ Please refer to Section 18 for more details on compliance classes
+ defined in this specification.
+
+ Note that many WebDAV servers do not advertise WebDAV support in
+ response to "OPTIONS *".
+
+ As a request header, this header allows the client to advertise
+ compliance with named features when the server needs that
+ information. Clients SHOULD NOT send this header unless a standards
+ track specification requires it. Any extension that makes use of
+ this as a request header will need to carefully consider caching
+ implications.
+
+10.2. Depth Header
+
+ Depth = "Depth" ":" ("0" | "1" | "infinity")
+
+ The Depth request header is used with methods executed on resources
+ that could potentially have internal members to indicate whether the
+ method is to be applied only to the resource ("Depth: 0"), to the
+ resource and its internal members only ("Depth: 1"), or the resource
+ and all its members ("Depth: infinity").
+
+ The Depth header is only supported if a method's definition
+ explicitly provides for such support.
+
+ The following rules are the default behavior for any method that
+ supports the Depth header. A method may override these defaults by
+ defining different behavior in its definition.
+
+
+
+
+Dusseault Standards Track [Page 70]
+
+RFC 4918 WebDAV June 2007
+
+
+ Methods that support the Depth header may choose not to support all
+ of the header's values and may define, on a case-by-case basis, the
+ behavior of the method if a Depth header is not present. For
+ example, the MOVE method only supports "Depth: infinity", and if a
+ Depth header is not present, it will act as if a "Depth: infinity"
+ header had been applied.
+
+ Clients MUST NOT rely upon methods executing on members of their
+ hierarchies in any particular order or on the execution being atomic
+ unless the particular method explicitly provides such guarantees.
+
+ Upon execution, a method with a Depth header will perform as much of
+ its assigned task as possible and then return a response specifying
+ what it was able to accomplish and what it failed to do.
+
+ So, for example, an attempt to COPY a hierarchy may result in some of
+ the members being copied and some not.
+
+ By default, the Depth header does not interact with other headers.
+ That is, each header on a request with a Depth header MUST be applied
+ only to the Request-URI if it applies to any resource, unless
+ specific Depth behavior is defined for that header.
+
+ If a source or destination resource within the scope of the Depth
+ header is locked in such a way as to prevent the successful execution
+ of the method, then the lock token for that resource MUST be
+ submitted with the request in the If request header.
+
+ The Depth header only specifies the behavior of the method with
+ regards to internal members. If a resource does not have internal
+ members, then the Depth header MUST be ignored.
+
+10.3. Destination Header
+
+ The Destination request header specifies the URI that identifies a
+ destination resource for methods such as COPY and MOVE, which take
+ two URIs as parameters.
+
+ Destination = "Destination" ":" Simple-ref
+
+
+ If the Destination value is an absolute-URI (Section 4.3 of
+ [RFC3986]), it may name a different server (or different port or
+ scheme). If the source server cannot attempt a copy to the remote
+ server, it MUST fail the request. Note that copying and moving
+ resources to remote servers is not fully defined in this
+ specification (e.g., specific error conditions).
+
+
+
+
+Dusseault Standards Track [Page 71]
+
+RFC 4918 WebDAV June 2007
+
+
+ If the Destination value is too long or otherwise unacceptable, the
+ server SHOULD return 400 (Bad Request), ideally with helpful
+ information in an error body.
+
+10.4. If Header
+
+ The If request header is intended to have similar functionality to
+ the If-Match header defined in Section 14.24 of [RFC2616]. However,
+ the If header handles any state token as well as ETags. A typical
+ example of a state token is a lock token, and lock tokens are the
+ only state tokens defined in this specification.
+
+10.4.1. Purpose
+
+ The If header has two distinct purposes:
+
+ o The first purpose is to make a request conditional by supplying a
+ series of state lists with conditions that match tokens and ETags
+ to a specific resource. If this header is evaluated and all state
+ lists fail, then the request MUST fail with a 412 (Precondition
+ Failed) status. On the other hand, the request can succeed only
+ if one of the described state lists succeeds. The success
+ criteria for state lists and matching functions are defined in
+ Sections 10.4.3 and 10.4.4.
+
+ o Additionally, the mere fact that a state token appears in an If
+ header means that it has been "submitted" with the request. In
+ general, this is used to indicate that the client has knowledge of
+ that state token. The semantics for submitting a state token
+ depend on its type (for lock tokens, please refer to Section 6).
+
+ Note that these two purposes need to be treated distinctly: a state
+ token counts as being submitted independently of whether the server
+ actually has evaluated the state list it appears in, and also
+ independently of whether or not the condition it expressed was found
+ to be true.
+
+10.4.2. Syntax
+
+ If = "If" ":" ( 1*No-tag-list | 1*Tagged-list )
+
+ No-tag-list = List
+ Tagged-list = Resource-Tag 1*List
+
+ List = "(" 1*Condition ")"
+ Condition = ["Not"] (State-token | "[" entity-tag "]")
+ ; entity-tag: see Section 3.11 of [RFC2616]
+ ; No LWS allowed between "[", entity-tag and "]"
+
+
+
+Dusseault Standards Track [Page 72]
+
+RFC 4918 WebDAV June 2007
+
+
+ State-token = Coded-URL
+
+ Resource-Tag = "<" Simple-ref ">"
+ ; Simple-ref: see Section 8.3
+ ; No LWS allowed in Resource-Tag
+
+ The syntax distinguishes between untagged lists ("No-tag-list") and
+ tagged lists ("Tagged-list"). Untagged lists apply to the resource
+ identified by the Request-URI, while tagged lists apply to the
+ resource identified by the preceding Resource-Tag.
+
+ A Resource-Tag applies to all subsequent Lists, up to the next
+ Resource-Tag.
+
+ Note that the two list types cannot be mixed within an If header.
+ This is not a functional restriction because the No-tag-list syntax
+ is just a shorthand notation for a Tagged-list production with a
+ Resource-Tag referring to the Request-URI.
+
+ Each List consists of one or more Conditions. Each Condition is
+ defined in terms of an entity-tag or state-token, potentially negated
+ by the prefix "Not".
+
+ Note that the If header syntax does not allow multiple instances of
+ If headers in a single request. However, the HTTP header syntax
+ allows extending single header values across multiple lines, by
+ inserting a line break followed by whitespace (see [RFC2616], Section
+ 4.2).
+
+10.4.3. List Evaluation
+
+ A Condition that consists of a single entity-tag or state-token
+ evaluates to true if the resource matches the described state (where
+ the individual matching functions are defined below in
+ Section 10.4.4). Prefixing it with "Not" reverses the result of the
+ evaluation (thus, the "Not" applies only to the subsequent entity-tag
+ or state-token).
+
+ Each List production describes a series of conditions. The whole
+ list evaluates to true if and only if each condition evaluates to
+ true (that is, the list represents a logical conjunction of
+ Conditions).
+
+ Each No-tag-list and Tagged-list production may contain one or more
+ Lists. They evaluate to true if and only if any of the contained
+ lists evaluates to true (that is, if there's more than one List, that
+ List sequence represents a logical disjunction of the Lists).
+
+
+
+
+Dusseault Standards Track [Page 73]
+
+RFC 4918 WebDAV June 2007
+
+
+ Finally, the whole If header evaluates to true if and only if at
+ least one of the No-tag-list or Tagged-list productions evaluates to
+ true. If the header evaluates to false, the server MUST reject the
+ request with a 412 (Precondition Failed) status. Otherwise,
+ execution of the request can proceed as if the header wasn't present.
+
+10.4.4. Matching State Tokens and ETags
+
+ When performing If header processing, the definition of a matching
+ state token or entity tag is as follows:
+
+ Identifying a resource: The resource is identified by the URI along
+ with the token, in tagged list production, or by the Request-URI in
+ untagged list production.
+
+ Matching entity tag: Where the entity tag matches an entity tag
+ associated with the identified resource. Servers MUST use either the
+ weak or the strong comparison function defined in Section 13.3.3 of
+ [RFC2616].
+
+ Matching state token: Where there is an exact match between the state
+ token in the If header and any state token on the identified
+ resource. A lock state token is considered to match if the resource
+ is anywhere in the scope of the lock.
+
+ Handling unmapped URLs: For both ETags and state tokens, treat as if
+ the URL identified a resource that exists but does not have the
+ specified state.
+
+10.4.5. If Header and Non-DAV-Aware Proxies
+
+ Non-DAV-aware proxies will not honor the If header, since they will
+ not understand the If header, and HTTP requires non-understood
+ headers to be ignored. When communicating with HTTP/1.1 proxies, the
+ client MUST use the "Cache-Control: no-cache" request header so as to
+ prevent the proxy from improperly trying to service the request from
+ its cache. When dealing with HTTP/1.0 proxies, the "Pragma: no-
+ cache" request header MUST be used for the same reason.
+
+ Because in general clients may not be able to reliably detect non-
+ DAV-aware intermediates, they are advised to always prevent caching
+ using the request directives mentioned above.
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 74]
+
+RFC 4918 WebDAV June 2007
+
+
+10.4.6. Example - No-tag Production
+
+ If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
+ ["I am an ETag"])
+ (["I am another ETag"])
+
+ The previous header would require that the resource identified in the
+ Request-URI be locked with the specified lock token and be in the
+ state identified by the "I am an ETag" ETag or in the state
+ identified by the second ETag "I am another ETag".
+
+ To put the matter more plainly one can think of the previous If
+ header as expressing the condition below:
+
+ (
+ is-locked-with(urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2) AND
+ matches-etag("I am an ETag")
+ )
+ OR
+ (
+ matches-etag("I am another ETag")
+ )
+
+10.4.7. Example - Using "Not" with No-tag Production
+
+ If: (Not <urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
+ <urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092>)
+
+ This If header requires that the resource must not be locked with a
+ lock having the lock token
+ urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked by a
+ lock with the lock token
+ urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092.
+
+10.4.8. Example - Causing a Condition to Always Evaluate to True
+
+ There may be cases where a client wishes to submit state tokens, but
+ doesn't want the request to fail just because the state token isn't
+ current anymore. One simple way to do this is to include a Condition
+ that is known to always evaluate to true, such as in:
+
+ If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
+ (Not <DAV:no-lock>)
+
+ "DAV:no-lock" is known to never represent a current lock token. Lock
+ tokens are assigned by the server, following the uniqueness
+ requirements described in Section 6.5, therefore cannot use the
+ "DAV:" scheme. Thus, by applying "Not" to a state token that is
+
+
+
+Dusseault Standards Track [Page 75]
+
+RFC 4918 WebDAV June 2007
+
+
+ known not to be current, the Condition always evaluates to true.
+ Consequently, the whole If header will always evaluate to true, and
+ the lock token urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 will be
+ submitted in any case.
+
+10.4.9. Example - Tagged List If Header in COPY
+
+ >>Request
+
+ COPY /resource1 HTTP/1.1
+ Host: www.example.com
+ Destination: /resource2
+ If: </resource1>
+ (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
+ [W/"A weak ETag"]) (["strong ETag"])
+
+ In this example, http://www.example.com/resource1 is being copied to
+ http://www.example.com/resource2. When the method is first applied
+ to http://www.example.com/resource1, resource1 must be in the state
+ specified by "(<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> [W/"A
+ weak ETag"]) (["strong ETag"])". That is, either it must be locked
+ with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2"
+ and have a weak entity tag W/"A weak ETag" or it must have a strong
+ entity tag "strong ETag".
+
+10.4.10. Example - Matching Lock Tokens with Collection Locks
+
+ DELETE /specs/rfc2518.txt HTTP/1.1
+ Host: www.example.com
+ If: <http://www.example.com/specs/>
+ (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
+
+ For this example, the lock token must be compared to the identified
+ resource, which is the 'specs' collection identified by the URL in
+ the tagged list production. If the 'specs' collection is not locked
+ by a lock with the specified lock token, the request MUST fail.
+ Otherwise, this request could succeed, because the If header
+ evaluates to true, and because the lock token for the lock affecting
+ the affected resource has been submitted.
+
+10.4.11. Example - Matching ETags on Unmapped URLs
+
+ Consider a collection "/specs" that does not contain the member
+ "/specs/rfc2518.doc". In this case, the If header
+
+ If: </specs/rfc2518.doc> (["4217"])
+
+
+
+
+
+Dusseault Standards Track [Page 76]
+
+RFC 4918 WebDAV June 2007
+
+
+ will evaluate to false (the URI isn't mapped, thus the resource
+ identified by the URI doesn't have an entity matching the ETag
+ "4217").
+
+ On the other hand, an If header of
+
+ If: </specs/rfc2518.doc> (Not ["4217"])
+
+ will consequently evaluate to true.
+
+ Note that, as defined above in Section 10.4.4, the same
+ considerations apply to matching state tokens.
+
+10.5. Lock-Token Header
+
+ Lock-Token = "Lock-Token" ":" Coded-URL
+
+ The Lock-Token request header is used with the UNLOCK method to
+ identify the lock to be removed. The lock token in the Lock-Token
+ request header MUST identify a lock that contains the resource
+ identified by Request-URI as a member.
+
+ The Lock-Token response header is used with the LOCK method to
+ indicate the lock token created as a result of a successful LOCK
+ request to create a new lock.
+
+10.6. Overwrite Header
+
+ Overwrite = "Overwrite" ":" ("T" | "F")
+
+ The Overwrite request header specifies whether the server should
+ overwrite a resource mapped to the destination URL during a COPY or
+ MOVE. A value of "F" states that the server must not perform the
+ COPY or MOVE operation if the destination URL does map to a resource.
+ If the overwrite header is not included in a COPY or MOVE request,
+ then the resource MUST treat the request as if it has an overwrite
+ header of value "T". While the Overwrite header appears to duplicate
+ the functionality of using an "If-Match: *" header (see [RFC2616]),
+ If-Match applies only to the Request-URI, and not to the Destination
+ of a COPY or MOVE.
+
+ If a COPY or MOVE is not performed due to the value of the Overwrite
+ header, the method MUST fail with a 412 (Precondition Failed) status
+ code. The server MUST do authorization checks before checking this
+ or any conditional header.
+
+ All DAV-compliant resources MUST support the Overwrite header.
+
+
+
+
+Dusseault Standards Track [Page 77]
+
+RFC 4918 WebDAV June 2007
+
+
+10.7. Timeout Request Header
+
+ TimeOut = "Timeout" ":" 1#TimeType
+ TimeType = ("Second-" DAVTimeOutVal | "Infinite")
+ ; No LWS allowed within TimeType
+ DAVTimeOutVal = 1*DIGIT
+
+ Clients MAY include Timeout request headers in their LOCK requests.
+ However, the server is not required to honor or even consider these
+ requests. Clients MUST NOT submit a Timeout request header with any
+ method other than a LOCK method.
+
+ The "Second" TimeType specifies the number of seconds that will
+ elapse between granting of the lock at the server, and the automatic
+ removal of the lock. The timeout value for TimeType "Second" MUST
+ NOT be greater than 2^32-1.
+
+ See Section 6.6 for a description of lock timeout behavior.
+
+11. Status Code Extensions to HTTP/1.1
+
+ The following status codes are added to those defined in HTTP/1.1
+ [RFC2616].
+
+11.1. 207 Multi-Status
+
+ The 207 (Multi-Status) status code provides status for multiple
+ independent operations (see Section 13 for more information).
+
+11.2. 422 Unprocessable Entity
+
+ The 422 (Unprocessable Entity) status code means the server
+ understands the content type of the request entity (hence a
+ 415(Unsupported Media Type) status code is inappropriate), and the
+ syntax of the request entity is correct (thus a 400 (Bad Request)
+ status code is inappropriate) but was unable to process the contained
+ instructions. For example, this error condition may occur if an XML
+ request body contains well-formed (i.e., syntactically correct), but
+ semantically erroneous, XML instructions.
+
+11.3. 423 Locked
+
+ The 423 (Locked) status code means the source or destination resource
+ of a method is locked. This response SHOULD contain an appropriate
+ precondition or postcondition code, such as 'lock-token-submitted' or
+ 'no-conflicting-lock'.
+
+
+
+
+
+Dusseault Standards Track [Page 78]
+
+RFC 4918 WebDAV June 2007
+
+
+11.4. 424 Failed Dependency
+
+ The 424 (Failed Dependency) status code means that the method could
+ not be performed on the resource because the requested action
+ depended on another action and that action failed. For example, if a
+ command in a PROPPATCH method fails, then, at minimum, the rest of
+ the commands will also fail with 424 (Failed Dependency).
+
+11.5. 507 Insufficient Storage
+
+ The 507 (Insufficient Storage) status code means the method could not
+ be performed on the resource because the server is unable to store
+ the representation needed to successfully complete the request. This
+ condition is considered to be temporary. If the request that
+ received this status code was the result of a user action, the
+ request MUST NOT be repeated until it is requested by a separate user
+ action.
+
+12. Use of HTTP Status Codes
+
+ These HTTP codes are not redefined, but their use is somewhat
+ extended by WebDAV methods and requirements. In general, many HTTP
+ status codes can be used in response to any request, not just in
+ cases described in this document. Note also that WebDAV servers are
+ known to use 300-level redirect responses (and early interoperability
+ tests found clients unprepared to see those responses). A 300-level
+ response MUST NOT be used when the server has created a new resource
+ in response to the request.
+
+12.1. 412 Precondition Failed
+
+ Any request can contain a conditional header defined in HTTP (If-
+ Match, If-Modified-Since, etc.) or the "If" or "Overwrite"
+ conditional headers defined in this specification. If the server
+ evaluates a conditional header, and if that condition fails to hold,
+ then this error code MUST be returned. On the other hand, if the
+ client did not include a conditional header in the request, then the
+ server MUST NOT use this status code.
+
+12.2. 414 Request-URI Too Long
+
+ This status code is used in HTTP 1.1 only for Request-URIs, not URIs
+ in other locations.
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 79]
+
+RFC 4918 WebDAV June 2007
+
+
+13. Multi-Status Response
+
+ A Multi-Status response conveys information about multiple resources
+ in situations where multiple status codes might be appropriate. The
+ default Multi-Status response body is a text/xml or application/xml
+ HTTP entity with a 'multistatus' root element. Further elements
+ contain 200, 300, 400, and 500 series status codes generated during
+ the method invocation. 100 series status codes SHOULD NOT be recorded
+ in a 'response' XML element.
+
+ Although '207' is used as the overall response status code, the
+ recipient needs to consult the contents of the multistatus response
+ body for further information about the success or failure of the
+ method execution. The response MAY be used in success, partial
+ success and also in failure situations.
+
+ The 'multistatus' root element holds zero or more 'response' elements
+ in any order, each with information about an individual resource.
+ Each 'response' element MUST have an 'href' element to identify the
+ resource.
+
+ A Multi-Status response uses one out of two distinct formats for
+ representing the status:
+
+ 1. A 'status' element as child of the 'response' element indicates
+ the status of the message execution for the identified resource
+ as a whole (for instance, see Section 9.6.2). Some method
+ definitions provide information about specific status codes
+ clients should be prepared to see in a response. However,
+ clients MUST be able to handle other status codes, using the
+ generic rules defined in Section 10 of [RFC2616].
+
+ 2. For PROPFIND and PROPPATCH, the format has been extended using
+ the 'propstat' element instead of 'status', providing information
+ about individual properties of a resource. This format is
+ specific to PROPFIND and PROPPATCH, and is described in detail in
+ Sections 9.1 and 9.2.
+
+13.1. Response Headers
+
+ HTTP defines the Location header to indicate a preferred URL for the
+ resource that was addressed in the Request-URI (e.g., in response to
+ successful PUT requests or in redirect responses). However, use of
+ this header creates ambiguity when there are URLs in the body of the
+ response, as with Multi-Status. Thus, use of the Location header
+ with the Multi-Status response is intentionally undefined.
+
+
+
+
+
+Dusseault Standards Track [Page 80]
+
+RFC 4918 WebDAV June 2007
+
+
+13.2. Handling Redirected Child Resources
+
+ Redirect responses (300-303, 305, and 307) defined in HTTP 1.1
+ normally take a Location header to indicate the new URI for the
+ single resource redirected from the Request-URI. Multi-Status
+ responses contain many resource addresses, but the original
+ definition in [RFC2518] did not have any place for the server to
+ provide the new URI for redirected resources. This specification
+ does define a 'location' element for this information (see
+ Section 14.9). Servers MUST use this new element with redirect
+ responses in Multi-Status.
+
+ Clients encountering redirected resources in Multi-Status MUST NOT
+ rely on the 'location' element being present with a new URI. If the
+ element is not present, the client MAY reissue the request to the
+ individual redirected resource, because the response to that request
+ can be redirected with a Location header containing the new URI.
+
+13.3. Internal Status Codes
+
+ Sections 9.2.1, 9.1.2, 9.6.1, 9.8.3, and 9.9.2 define various status
+ codes used in Multi-Status responses. This specification does not
+ define the meaning of other status codes that could appear in these
+ responses.
+
+14. XML Element Definitions
+
+ In this section, the final line of each section gives the element
+ type declaration using the format defined in [REC-XML]. The "Value"
+ field, where present, specifies further restrictions on the allowable
+ contents of the XML element using BNF (i.e., to further restrict the
+ values of a PCDATA element). Note that all of the elements defined
+ here may be extended according to the rules defined in Section 17.
+ All elements defined here are in the "DAV:" namespace.
+
+14.1. activelock XML Element
+
+ Name: activelock
+
+ Purpose: Describes a lock on a resource.
+
+
+ <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
+ locktoken?, lockroot)>
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 81]
+
+RFC 4918 WebDAV June 2007
+
+
+14.2. allprop XML Element
+
+ Name: allprop
+
+ Purpose: Specifies that all names and values of dead properties and
+ the live properties defined by this document existing on the
+ resource are to be returned.
+
+ <!ELEMENT allprop EMPTY >
+
+14.3. collection XML Element
+
+ Name: collection
+
+ Purpose: Identifies the associated resource as a collection. The
+ DAV:resourcetype property of a collection resource MUST contain
+ this element. It is normally empty but extensions may add sub-
+ elements.
+
+ <!ELEMENT collection EMPTY >
+
+14.4. depth XML Element
+
+ Name: depth
+
+ Purpose: Used for representing depth values in XML content (e.g.,
+ in lock information).
+
+ Value: "0" | "1" | "infinity"
+
+ <!ELEMENT depth (#PCDATA) >
+
+14.5. error XML Element
+
+ Name: error
+
+ Purpose: Error responses, particularly 403 Forbidden and 409
+ Conflict, sometimes need more information to indicate what went
+ wrong. In these cases, servers MAY return an XML response body
+ with a document element of 'error', containing child elements
+ identifying particular condition codes.
+
+ Description: Contains at least one XML element, and MUST NOT
+ contain text or mixed content. Any element that is a child of the
+ 'error' element is considered to be a precondition or
+ postcondition code. Unrecognized elements MUST be ignored.
+
+ <!ELEMENT error ANY >
+
+
+
+Dusseault Standards Track [Page 82]
+
+RFC 4918 WebDAV June 2007
+
+
+14.6. exclusive XML Element
+
+ Name: exclusive
+
+ Purpose: Specifies an exclusive lock.
+
+
+ <!ELEMENT exclusive EMPTY >
+
+
+14.7. href XML Element
+
+ Name: href
+
+ Purpose: MUST contain a URI or a relative reference.
+
+ Description: There may be limits on the value of 'href' depending
+ on the context of its use. Refer to the specification text where
+ 'href' is used to see what limitations apply in each case.
+
+ Value: Simple-ref
+
+
+ <!ELEMENT href (#PCDATA)>
+
+14.8. include XML Element
+
+ Name: include
+
+ Purpose: Any child element represents the name of a property to be
+ included in the PROPFIND response. All elements inside an
+ 'include' XML element MUST define properties related to the
+ resource, although possible property names are in no way limited
+ to those property names defined in this document or other
+ standards. This element MUST NOT contain text or mixed content.
+
+ <!ELEMENT include ANY >
+
+14.9. location XML Element
+
+ Name: location
+
+ Purpose: HTTP defines the "Location" header (see [RFC2616], Section
+ 14.30) for use with some status codes (such as 201 and the 300
+ series codes). When these codes are used inside a 'multistatus'
+ element, the 'location' element can be used to provide the
+ accompanying Location header value.
+
+
+
+
+Dusseault Standards Track [Page 83]
+
+RFC 4918 WebDAV June 2007
+
+
+ Description: Contains a single href element with the same value
+ that would be used in a Location header.
+
+
+ <!ELEMENT location (href)>
+
+14.10. lockentry XML Element
+
+ Name: lockentry
+
+ Purpose: Defines the types of locks that can be used with the
+ resource.
+
+ <!ELEMENT lockentry (lockscope, locktype) >
+
+14.11. lockinfo XML Element
+
+ Name: lockinfo
+
+ Purpose: The 'lockinfo' XML element is used with a LOCK method to
+ specify the type of lock the client wishes to have created.
+
+
+ <!ELEMENT lockinfo (lockscope, locktype, owner?) >
+
+14.12. lockroot XML Element
+
+ Name: lockroot
+
+ Purpose: Contains the root URL of the lock, which is the URL
+ through which the resource was addressed in the LOCK request.
+
+ Description: The href element contains the root of the lock. The
+ server SHOULD include this in all DAV:lockdiscovery property
+ values and the response to LOCK requests.
+
+ <!ELEMENT lockroot (href) >
+
+14.13. lockscope XML Element
+
+ Name: lockscope
+
+ Purpose: Specifies whether a lock is an exclusive lock, or a shared
+ lock.
+
+
+ <!ELEMENT lockscope (exclusive | shared) >
+
+
+
+
+Dusseault Standards Track [Page 84]
+
+RFC 4918 WebDAV June 2007
+
+
+14.14. locktoken XML Element
+
+ Name: locktoken
+
+ Purpose: The lock token associated with a lock.
+
+ Description: The href contains a single lock token URI, which
+ refers to the lock.
+
+ <!ELEMENT locktoken (href) >
+
+14.15. locktype XML Element
+
+ Name: locktype
+
+ Purpose: Specifies the access type of a lock. At present, this
+ specification only defines one lock type, the write lock.
+
+
+ <!ELEMENT locktype (write) >
+
+
+14.16. multistatus XML Element
+
+ Name: multistatus
+
+ Purpose: Contains multiple response messages.
+
+ Description: The 'responsedescription' element at the top level is
+ used to provide a general message describing the overarching
+ nature of the response. If this value is available, an
+ application may use it instead of presenting the individual
+ response descriptions contained within the responses.
+
+
+ <!ELEMENT multistatus (response*, responsedescription?) >
+
+
+14.17. owner XML Element
+
+ Name: owner
+
+ Purpose: Holds client-supplied information about the creator of a
+ lock.
+
+ Description: Allows a client to provide information sufficient for
+ either directly contacting a principal (such as a telephone number
+ or Email URI), or for discovering the principal (such as the URL
+
+
+
+Dusseault Standards Track [Page 85]
+
+RFC 4918 WebDAV June 2007
+
+
+ of a homepage) who created a lock. The value provided MUST be
+ treated as a dead property in terms of XML Information Item
+ preservation. The server MUST NOT alter the value unless the
+ owner value provided by the client is empty. For a certain amount
+ of interoperability between different client implementations, if
+ clients have URI-formatted contact information for the lock
+ creator suitable for user display, then clients SHOULD put those
+ URIs in 'href' child elements of the 'owner' element.
+
+ Extensibility: MAY be extended with child elements, mixed content,
+ text content or attributes.
+
+ <!ELEMENT owner ANY >
+
+14.18. prop XML Element
+
+ Name: prop
+
+ Purpose: Contains properties related to a resource.
+
+ Description: A generic container for properties defined on
+ resources. All elements inside a 'prop' XML element MUST define
+ properties related to the resource, although possible property
+ names are in no way limited to those property names defined in
+ this document or other standards. This element MUST NOT contain
+ text or mixed content.
+
+ <!ELEMENT prop ANY >
+
+14.19. propertyupdate XML Element
+
+ Name: propertyupdate
+
+ Purpose: Contains a request to alter the properties on a resource.
+
+ Description: This XML element is a container for the information
+ required to modify the properties on the resource.
+
+ <!ELEMENT propertyupdate (remove | set)+ >
+
+14.20. propfind XML Element
+
+ Name: propfind
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 86]
+
+RFC 4918 WebDAV June 2007
+
+
+ Purpose: Specifies the properties to be returned from a PROPFIND
+ method. Four special elements are specified for use with
+ 'propfind': 'prop', 'allprop', 'include', and 'propname'. If
+ 'prop' is used inside 'propfind', it MUST NOT contain property
+ values.
+
+ <!ELEMENT propfind ( propname | (allprop, include?) | prop ) >
+
+14.21. propname XML Element
+
+ Name: propname
+
+ Purpose: Specifies that only a list of property names on the
+ resource is to be returned.
+
+ <!ELEMENT propname EMPTY >
+
+14.22. propstat XML Element
+
+ Name: propstat
+
+ Purpose: Groups together a prop and status element that is
+ associated with a particular 'href' element.
+
+ Description: The propstat XML element MUST contain one prop XML
+ element and one status XML element. The contents of the prop XML
+ element MUST only list the names of properties to which the result
+ in the status element applies. The optional precondition/
+ postcondition element and 'responsedescription' text also apply to
+ the properties named in 'prop'.
+
+ <!ELEMENT propstat (prop, status, error?, responsedescription?) >
+
+14.23. remove XML Element
+
+ Name: remove
+
+ Purpose: Lists the properties to be removed from a resource.
+
+ Description: Remove instructs that the properties specified in prop
+ should be removed. Specifying the removal of a property that does
+ not exist is not an error. All the XML elements in a 'prop' XML
+ element inside of a 'remove' XML element MUST be empty, as only
+ the names of properties to be removed are required.
+
+ <!ELEMENT remove (prop) >
+
+
+
+
+
+Dusseault Standards Track [Page 87]
+
+RFC 4918 WebDAV June 2007
+
+
+14.24. response XML Element
+
+ Name: response
+
+ Purpose: Holds a single response describing the effect of a method
+ on resource and/or its properties.
+
+ Description: The 'href' element contains an HTTP URL pointing to a
+ WebDAV resource when used in the 'response' container. A
+ particular 'href' value MUST NOT appear more than once as the
+ child of a 'response' XML element under a 'multistatus' XML
+ element. This requirement is necessary in order to keep
+ processing costs for a response to linear time. Essentially, this
+ prevents having to search in order to group together all the
+ responses by 'href'. There are, however, no requirements
+ regarding ordering based on 'href' values. The optional
+ precondition/postcondition element and 'responsedescription' text
+ can provide additional information about this resource relative to
+ the request or result.
+
+
+ <!ELEMENT response (href, ((href*, status)|(propstat+)),
+ error?, responsedescription? , location?) >
+
+14.25. responsedescription XML Element
+
+ Name: responsedescription
+
+ Purpose: Contains information about a status response within a
+ Multi-Status.
+
+ Description: Provides information suitable to be presented to a
+ user.
+
+ <!ELEMENT responsedescription (#PCDATA) >
+
+14.26. set XML Element
+
+ Name: set
+
+ Purpose: Lists the property values to be set for a resource.
+
+ Description: The 'set' element MUST contain only a 'prop' element.
+ The elements contained by the 'prop' element inside the 'set'
+ element MUST specify the name and value of properties that are set
+ on the resource identified by Request-URI. If a property already
+ exists, then its value is replaced. Language tagging information
+ appearing in the scope of the 'prop' element (in the "xml:lang"
+
+
+
+Dusseault Standards Track [Page 88]
+
+RFC 4918 WebDAV June 2007
+
+
+ attribute, if present) MUST be persistently stored along with the
+ property, and MUST be subsequently retrievable using PROPFIND.
+
+ <!ELEMENT set (prop) >
+
+14.27. shared XML Element
+
+ Name: shared
+
+ Purpose: Specifies a shared lock.
+
+
+ <!ELEMENT shared EMPTY >
+
+
+14.28. status XML Element
+
+ Name: status
+
+ Purpose: Holds a single HTTP status-line.
+
+ Value: status-line (defined in Section 6.1 of [RFC2616])
+
+ <!ELEMENT status (#PCDATA) >
+
+14.29. timeout XML Element
+
+ Name: timeout
+
+ Purpose: The number of seconds remaining before a lock expires.
+
+ Value: TimeType (defined in Section 10.7)
+
+
+ <!ELEMENT timeout (#PCDATA) >
+
+14.30. write XML Element
+
+ Name: write
+
+ Purpose: Specifies a write lock.
+
+
+ <!ELEMENT write EMPTY >
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 89]
+
+RFC 4918 WebDAV June 2007
+
+
+15. DAV Properties
+
+ For DAV properties, the name of the property is also the same as the
+ name of the XML element that contains its value. In the section
+ below, the final line of each section gives the element type
+ declaration using the format defined in [REC-XML]. The "Value"
+ field, where present, specifies further restrictions on the allowable
+ contents of the XML element using BNF (i.e., to further restrict the
+ values of a PCDATA element).
+
+ A protected property is one that cannot be changed with a PROPPATCH
+ request. There may be other requests that would result in a change
+ to a protected property (as when a LOCK request affects the value of
+ DAV:lockdiscovery). Note that a given property could be protected on
+ one type of resource, but not protected on another type of resource.
+
+ A computed property is one with a value defined in terms of a
+ computation (based on the content and other properties of that
+ resource, or even of some other resource). A computed property is
+ always a protected property.
+
+ COPY and MOVE behavior refers to local COPY and MOVE operations.
+
+ For properties defined based on HTTP GET response headers (DAV:get*),
+ the header value could include LWS as defined in [RFC2616], Section
+ 4.2. Server implementors SHOULD strip LWS from these values before
+ using as WebDAV property values.
+
+15.1. creationdate Property
+
+ Name: creationdate
+
+ Purpose: Records the time and date the resource was created.
+
+ Value: date-time (defined in [RFC3339], see the ABNF in Section
+ 5.6.)
+
+ Protected: MAY be protected. Some servers allow DAV:creationdate
+ to be changed to reflect the time the document was created if that
+ is more meaningful to the user (rather than the time it was
+ uploaded). Thus, clients SHOULD NOT use this property in
+ synchronization logic (use DAV:getetag instead).
+
+ COPY/MOVE behavior: This property value SHOULD be kept during a
+ MOVE operation, but is normally re-initialized when a resource is
+ created with a COPY. It should not be set in a COPY.
+
+
+
+
+
+Dusseault Standards Track [Page 90]
+
+RFC 4918 WebDAV June 2007
+
+
+ Description: The DAV:creationdate property SHOULD be defined on all
+ DAV compliant resources. If present, it contains a timestamp of
+ the moment when the resource was created. Servers that are
+ incapable of persistently recording the creation date SHOULD
+ instead leave it undefined (i.e. report "Not Found").
+
+ <!ELEMENT creationdate (#PCDATA) >
+
+15.2. displayname Property
+
+ Name: displayname
+
+ Purpose: Provides a name for the resource that is suitable for
+ presentation to a user.
+
+ Value: Any text.
+
+ Protected: SHOULD NOT be protected. Note that servers implementing
+ [RFC2518] might have made this a protected property as this is a
+ new requirement.
+
+ COPY/MOVE behavior: This property value SHOULD be preserved in COPY
+ and MOVE operations.
+
+ Description: Contains a description of the resource that is
+ suitable for presentation to a user. This property is defined on
+ the resource, and hence SHOULD have the same value independent of
+ the Request-URI used to retrieve it (thus, computing this property
+ based on the Request-URI is deprecated). While generic clients
+ might display the property value to end users, client UI designers
+ must understand that the method for identifying resources is still
+ the URL. Changes to DAV:displayname do not issue moves or copies
+ to the server, but simply change a piece of meta-data on the
+ individual resource. Two resources can have the same DAV:
+ displayname value even within the same collection.
+
+ <!ELEMENT displayname (#PCDATA) >
+
+15.3. getcontentlanguage Property
+
+ Name: getcontentlanguage
+
+ Purpose: Contains the Content-Language header value (from Section
+ 14.12 of [RFC2616]) as it would be returned by a GET without
+ accept headers.
+
+ Value: language-tag (language-tag is defined in Section 3.10 of
+ [RFC2616])
+
+
+
+Dusseault Standards Track [Page 91]
+
+RFC 4918 WebDAV June 2007
+
+
+ Protected: SHOULD NOT be protected, so that clients can reset the
+ language. Note that servers implementing [RFC2518] might have
+ made this a protected property as this is a new requirement.
+
+ COPY/MOVE behavior: This property value SHOULD be preserved in COPY
+ and MOVE operations.
+
+ Description: The DAV:getcontentlanguage property MUST be defined on
+ any DAV-compliant resource that returns the Content-Language
+ header on a GET.
+
+ <!ELEMENT getcontentlanguage (#PCDATA) >
+
+15.4. getcontentlength Property
+
+ Name: getcontentlength
+
+ Purpose: Contains the Content-Length header returned by a GET
+ without accept headers.
+
+ Value: See Section 14.13 of [RFC2616].
+
+ Protected: This property is computed, therefore protected.
+
+ Description: The DAV:getcontentlength property MUST be defined on
+ any DAV-compliant resource that returns the Content-Length header
+ in response to a GET.
+
+ COPY/MOVE behavior: This property value is dependent on the size of
+ the destination resource, not the value of the property on the
+ source resource.
+
+ <!ELEMENT getcontentlength (#PCDATA) >
+
+15.5. getcontenttype Property
+
+ Name: getcontenttype
+
+ Purpose: Contains the Content-Type header value (from Section 14.17
+ of [RFC2616]) as it would be returned by a GET without accept
+ headers.
+
+ Value: media-type (defined in Section 3.7 of [RFC2616])
+
+ Protected: Potentially protected if the server prefers to assign
+ content types on its own (see also discussion in Section 9.7.1).
+
+
+
+
+
+Dusseault Standards Track [Page 92]
+
+RFC 4918 WebDAV June 2007
+
+
+ COPY/MOVE behavior: This property value SHOULD be preserved in COPY
+ and MOVE operations.
+
+ Description: This property MUST be defined on any DAV-compliant
+ resource that returns the Content-Type header in response to a
+ GET.
+
+ <!ELEMENT getcontenttype (#PCDATA) >
+
+15.6. getetag Property
+
+ Name: getetag
+
+ Purpose: Contains the ETag header value (from Section 14.19 of
+ [RFC2616]) as it would be returned by a GET without accept
+ headers.
+
+ Value: entity-tag (defined in Section 3.11 of [RFC2616])
+
+ Protected: MUST be protected because this value is created and
+ controlled by the server.
+
+ COPY/MOVE behavior: This property value is dependent on the final
+ state of the destination resource, not the value of the property
+ on the source resource. Also note the considerations in
+ Section 8.8.
+
+ Description: The getetag property MUST be defined on any DAV-
+ compliant resource that returns the Etag header. Refer to Section
+ 3.11 of RFC 2616 for a complete definition of the semantics of an
+ ETag, and to Section 8.6 for a discussion of ETags in WebDAV.
+
+ <!ELEMENT getetag (#PCDATA) >
+
+15.7. getlastmodified Property
+
+ Name: getlastmodified
+
+ Purpose: Contains the Last-Modified header value (from Section
+ 14.29 of [RFC2616]) as it would be returned by a GET method
+ without accept headers.
+
+ Value: rfc1123-date (defined in Section 3.3.1 of [RFC2616])
+
+ Protected: SHOULD be protected because some clients may rely on the
+ value for appropriate caching behavior, or on the value of the
+ Last-Modified header to which this property is linked.
+
+
+
+
+Dusseault Standards Track [Page 93]
+
+RFC 4918 WebDAV June 2007
+
+
+ COPY/MOVE behavior: This property value is dependent on the last
+ modified date of the destination resource, not the value of the
+ property on the source resource. Note that some server
+ implementations use the file system date modified value for the
+ DAV:getlastmodified value, and this can be preserved in a MOVE
+ even when the HTTP Last-Modified value SHOULD change. Note that
+ since [RFC2616] requires clients to use ETags where provided, a
+ server implementing ETags can count on clients using a much better
+ mechanism than modification dates for offline synchronization or
+ cache control. Also note the considerations in Section 8.8.
+
+ Description: The last-modified date on a resource SHOULD only
+ reflect changes in the body (the GET responses) of the resource.
+ A change in a property only SHOULD NOT cause the last-modified
+ date to change, because clients MAY rely on the last-modified date
+ to know when to overwrite the existing body. The DAV:
+ getlastmodified property MUST be defined on any DAV-compliant
+ resource that returns the Last-Modified header in response to a
+ GET.
+
+ <!ELEMENT getlastmodified (#PCDATA) >
+
+15.8. lockdiscovery Property
+
+ Name: lockdiscovery
+
+ Purpose: Describes the active locks on a resource
+
+ Protected: MUST be protected. Clients change the list of locks
+ through LOCK and UNLOCK, not through PROPPATCH.
+
+ COPY/MOVE behavior: The value of this property depends on the lock
+ state of the destination, not on the locks of the source resource.
+ Recall that locks are not moved in a MOVE operation.
+
+ Description: Returns a listing of who has a lock, what type of lock
+ he has, the timeout type and the time remaining on the timeout,
+ and the associated lock token. Owner information MAY be omitted
+ if it is considered sensitive. If there are no locks, but the
+ server supports locks, the property will be present but contain
+ zero 'activelock' elements. If there are one or more locks, an
+ 'activelock' element appears for each lock on the resource. This
+ property is NOT lockable with respect to write locks (Section 7).
+
+ <!ELEMENT lockdiscovery (activelock)* >
+
+
+
+
+
+
+Dusseault Standards Track [Page 94]
+
+RFC 4918 WebDAV June 2007
+
+
+15.8.1. Example - Retrieving DAV:lockdiscovery
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.example.com
+ Content-Length: xxxx
+ Content-Type: application/xml; charset="utf-8"
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D='DAV:'>
+ <D:prop><D:lockdiscovery/></D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/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.example.com/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>0</D:depth>
+ <D:owner>Jane Smith</D:owner>
+ <D:timeout>Infinite</D:timeout>
+ <D:locktoken>
+ <D:href
+ >urn:uuid:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76</D:href>
+ </D:locktoken>
+ <D:lockroot>
+ <D:href>http://www.example.com/container/</D:href>
+ </D:lockroot>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+Dusseault Standards Track [Page 95]
+
+RFC 4918 WebDAV June 2007
+
+
+ This resource has a single exclusive write lock on it, with an
+ infinite timeout.
+
+15.9. resourcetype Property
+
+ Name: resourcetype
+
+ Purpose: Specifies the nature of the resource.
+
+ Protected: SHOULD be protected. Resource type is generally decided
+ through the operation creating the resource (MKCOL vs PUT), not by
+ PROPPATCH.
+
+ COPY/MOVE behavior: Generally a COPY/MOVE of a resource results in
+ the same type of resource at the destination.
+
+ Description: MUST be defined on all DAV-compliant resources. Each
+ child element identifies a specific type the resource belongs to,
+ such as 'collection', which is the only resource type defined by
+ this specification (see Section 14.3). If the element contains
+ the 'collection' child element plus additional unrecognized
+ elements, it should generally be treated as a collection. If the
+ element contains no recognized child elements, it should be
+ treated as a non-collection resource. The default value is empty.
+ This element MUST NOT contain text or mixed content. Any custom
+ child element is considered to be an identifier for a resource
+ type.
+
+ Example: (fictional example to show extensibility)
+
+ <x:resourcetype xmlns:x="DAV:">
+ <x:collection/>
+ <f:search-results xmlns:f="http://www.example.com/ns"/>
+ </x:resourcetype>
+
+15.10. supportedlock Property
+
+ Name: supportedlock
+
+ Purpose: To provide a listing of the lock capabilities supported by
+ the resource.
+
+ Protected: MUST be protected. Servers, not clients, determine what
+ lock mechanisms are supported.
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 96]
+
+RFC 4918 WebDAV June 2007
+
+
+ COPY/MOVE behavior: This property value is dependent on the kind of
+ locks supported at the destination, not on the value of the
+ property at the source resource. Servers attempting to COPY to a
+ destination should not attempt to set this property at the
+ destination.
+
+ Description: Returns a listing of the combinations of scope and
+ access types that may be specified in a lock request on the
+ resource. Note that the actual contents are themselves controlled
+ by access controls, so a server is not required to provide
+ information the client is not authorized to see. This property is
+ NOT lockable with respect to write locks (Section 7).
+
+ <!ELEMENT supportedlock (lockentry)* >
+
+15.10.1. Example - Retrieving DAV:supportedlock
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.example.com
+ Content-Length: xxxx
+ Content-Type: application/xml; charset="utf-8"
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop><D:supportedlock/></D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/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.example.com/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+
+
+
+Dusseault Standards Track [Page 97]
+
+RFC 4918 WebDAV June 2007
+
+
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+16. Precondition/Postcondition XML Elements
+
+ As introduced in Section 8.7, extra information on error conditions
+ can be included in the body of many status responses. This section
+ makes requirements on the use of the error body mechanism and
+ introduces a number of precondition and postcondition codes.
+
+ 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.
+
+ Each precondition and postcondition has a unique XML element
+ associated with it. In a 207 Multi-Status response, the XML element
+ MUST appear inside an 'error' element in the appropriate 'propstat or
+ 'response' element depending on whether the condition applies to one
+ or more properties or to the resource as a whole. In all other error
+ responses where this specification's 'error' body is used, the
+ precondition/postcondition XML element MUST be returned as the child
+ of a top-level 'error' element in the response body, unless otherwise
+ negotiated by the request, along with an appropriate response status.
+ The most common response status codes are 403 (Forbidden) if the
+ request should not be repeated because it will always fail, and 409
+ (Conflict) if it is expected that the user might be able to resolve
+ the conflict and resubmit the request. The 'error' element MAY
+ contain child elements with specific error information and MAY be
+ extended with any custom child elements.
+
+ This mechanism does not take the place of using a correct numeric
+ status code as defined here or in HTTP, because the client must
+ always be able to take a reasonable course of action based only on
+ the numeric code. However, it does remove the need to define new
+ numeric codes. The new machine-readable codes used for this purpose
+ are XML elements classified as preconditions and postconditions, so
+ naturally, any group defining a new condition code can use their own
+ namespace. As always, the "DAV:" namespace is reserved for use by
+ IETF-chartered WebDAV working groups.
+
+
+
+
+
+Dusseault Standards Track [Page 98]
+
+RFC 4918 WebDAV June 2007
+
+
+ A server supporting this specification SHOULD use the XML error
+ whenever a precondition or postcondition defined in this document is
+ violated. For error conditions not specified in this document, the
+ server MAY simply choose an appropriate numeric status and leave the
+ response body blank. However, a server MAY instead use a custom
+ condition code and other supporting text, because even when clients
+ do not automatically recognize condition codes, they can be quite
+ useful in interoperability testing and debugging.
+
+ Example - Response with precondition code
+
+ >>Response
+
+ HTTP/1.1 423 Locked
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:lock-token-submitted>
+ <D:href>/workspace/webdav/</D:href>
+ </D:lock-token-submitted>
+ </D:error>
+
+ In this example, a client unaware of a depth-infinity lock on the
+ parent collection "/workspace/webdav/" attempted to modify the
+ collection member "/workspace/webdav/proposal.doc".
+
+ Some other useful preconditions and postconditions have been defined
+ in other specifications extending WebDAV, such as [RFC3744] (see
+ particularly Section 7.1.1), [RFC3253], and [RFC3648].
+
+ All these elements are in the "DAV:" namespace. If not specified
+ otherwise, the content for each condition's XML element is defined to
+ be empty.
+
+
+ Name: lock-token-matches-request-uri
+
+ Use with: 409 Conflict
+
+ Purpose: (precondition) -- A request may include a Lock-Token header
+ to identify a lock for the UNLOCK method. However, if the
+ Request-URI does not fall within the scope of the lock identified
+ by the token, the server SHOULD use this error. The lock may have
+ a scope that does not include the Request-URI, or the lock could
+ have disappeared, or the token may be invalid.
+
+
+
+
+Dusseault Standards Track [Page 99]
+
+RFC 4918 WebDAV June 2007
+
+
+ Name: lock-token-submitted (precondition)
+
+ Use with: 423 Locked
+
+ Purpose: The request could not succeed because a lock token should
+ have been submitted. This element, if present, MUST contain at
+ least one URL of a locked resource that prevented the request. In
+ cases of MOVE, COPY, and DELETE where collection locks are
+ involved, it can be difficult for the client to find out which
+ locked resource made the request fail -- but the server is only
+ responsible for returning one such locked resource. The server
+ MAY return every locked resource that prevented the request from
+ succeeding if it knows them all.
+
+ <!ELEMENT lock-token-submitted (href+) >
+
+
+ Name: no-conflicting-lock (precondition)
+
+ Use with: Typically 423 Locked
+
+ Purpose: A LOCK request failed due the presence of an already
+ existing conflicting lock. Note that a lock can be in conflict
+ although the resource to which the request was directed is only
+ indirectly locked. In this case, the precondition code can be
+ used to inform the client about the resource that is the root of
+ the conflicting lock, avoiding a separate lookup of the
+ "lockdiscovery" property.
+
+ <!ELEMENT no-conflicting-lock (href)* >
+
+
+ Name: no-external-entities
+
+ Use with: 403 Forbidden
+
+ Purpose: (precondition) -- If the server rejects a client request
+ because the request body contains an external entity, the server
+ SHOULD use this error.
+
+
+ Name: preserved-live-properties
+
+ Use with: 409 Conflict
+
+ Purpose: (postcondition) -- The server received an otherwise-valid
+ MOVE or COPY request, but cannot maintain the live properties with
+ the same behavior at the destination. It may be that the server
+
+
+
+Dusseault Standards Track [Page 100]
+
+RFC 4918 WebDAV June 2007
+
+
+ only supports some live properties in some parts of the
+ repository, or simply has an internal error.
+
+
+ Name: propfind-finite-depth
+
+ Use with: 403 Forbidden
+
+ Purpose: (precondition) -- This server does not allow infinite-depth
+ PROPFIND requests on collections.
+
+
+ Name: cannot-modify-protected-property
+
+ Use with: 403 Forbidden
+
+ Purpose: (precondition) -- The client attempted to set a protected
+ property in a PROPPATCH (such as DAV:getetag). See also
+ [RFC3253], Section 3.12.
+
+17. XML Extensibility in DAV
+
+ The XML namespace extension ([REC-XML-NAMES]) is used in this
+ specification in order to allow for new XML elements to be added
+ without fear of colliding with other element names. 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 SHOULD NOT be used in the request or
+ response body unless that XML element is explicitly defined in an
+ IETF RFC reviewed by a WebDAV working group.
+
+ For WebDAV to be both extensible and backwards-compatible, both
+ clients and servers need to know how to behave when unexpected or
+ unrecognized command extensions are received. For XML processing,
+ this means that clients and servers MUST process received XML
+ documents as if unexpected elements and attributes (and all children
+ of unrecognized elements) were not there. An unexpected element or
+ attribute includes one that may be used in another context but is not
+ expected here. Ignoring such items for purposes of processing can of
+ course be consistent with logging all information or presenting for
+ debugging.
+
+ This restriction also applies to the processing, by clients, of DAV
+ property values where unexpected XML elements SHOULD be ignored
+ unless the property's schema declares otherwise.
+
+ This restriction does not apply to setting dead DAV properties on the
+ server where the server MUST record all XML elements.
+
+
+
+Dusseault Standards Track [Page 101]
+
+RFC 4918 WebDAV June 2007
+
+
+ Additionally, this restriction does not apply to the use of XML where
+ XML happens to be the content type of the entity body, for example,
+ when used as the body of a PUT.
+
+ Processing instructions in XML SHOULD be ignored by recipients.
+ Thus, specifications extending WebDAV SHOULD NOT use processing
+ instructions to define normative behavior.
+
+ XML DTD fragments are included for all the XML elements defined in
+ this specification. However, correct XML will not be valid according
+ to any DTD due to namespace usage and extension rules. In
+ particular:
+
+ o Elements (from this specification) are in the "DAV:" namespace,
+
+ o Element ordering is irrelevant unless otherwise stated,
+
+ o Extension attributes MAY be added,
+
+ o For element type definitions of "ANY", the normative text
+ definition for that element defines what can be in it and what
+ that means.
+
+ o For element type definitions of "#PCDATA", extension elements MUST
+ NOT be added.
+
+ o For other element type definitions, including "EMPTY", extension
+ elements MAY be added.
+
+ Note that this means that elements containing elements cannot be
+ extended to contain text, and vice versa.
+
+ With DTD validation relaxed by the rules above, the constraints
+ described by the DTD fragments are normative (see for example
+ Appendix A). A recipient of a WebDAV message with an XML body MUST
+ NOT validate the XML document according to any hard-coded or
+ dynamically-declared DTD.
+
+ Note that this section describes backwards-compatible extensibility
+ rules. There might also be times when an extension is designed not
+ to be backwards-compatible, for example, defining an extension that
+ reuses an XML element defined in this document but omitting one of
+ the child elements required by the DTDs in this specification.
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 102]
+
+RFC 4918 WebDAV June 2007
+
+
+18. DAV Compliance Classes
+
+ A DAV-compliant resource can advertise several classes of compliance.
+ A client can discover the compliance classes of a resource by
+ executing OPTIONS on the resource and examining the "DAV" header
+ which is returned. Note particularly that resources, rather than
+ servers, are spoken of as being compliant. That is because
+ theoretically some resources on a server could support different
+ feature sets. For example, a server could have a sub-repository
+ where an advanced feature like versioning was supported, even if that
+ feature was not supported on all sub-repositories.
+
+ Since this document describes extensions to the HTTP/1.1 protocol,
+ minimally all DAV-compliant resources, clients, and proxies MUST be
+ compliant with [RFC2616].
+
+ A resource that is class 2 or class 3 compliant must also be class 1
+ compliant.
+
+18.1. Class 1
+
+ A class 1 compliant resource MUST meet all "MUST" requirements in all
+ sections of this document.
+
+ Class 1 compliant resources MUST return, at minimum, the value "1" in
+ the DAV header on all responses to the OPTIONS method.
+
+18.2. Class 2
+
+ A class 2 compliant resource MUST meet all class 1 requirements and
+ support the LOCK method, the DAV:supportedlock property, the DAV:
+ lockdiscovery property, the Time-Out response header and the Lock-
+ Token request header. A class 2 compliant resource SHOULD also
+ support the Timeout request header and the 'owner' XML element.
+
+ Class 2 compliant resources MUST return, at minimum, the values "1"
+ and "2" in the DAV header on all responses to the OPTIONS method.
+
+18.3. Class 3
+
+ A resource can explicitly advertise its support for the revisions to
+ [RFC2518] made in this document. Class 1 MUST be supported as well.
+ Class 2 MAY be supported. Advertising class 3 support in addition to
+ class 1 and 2 means that the server supports all the requirements in
+ this specification. Advertising class 3 and class 1 support, but not
+ class 2, means that the server supports all the requirements in this
+ specification except possibly those that involve locking support.
+
+
+
+
+Dusseault Standards Track [Page 103]
+
+RFC 4918 WebDAV June 2007
+
+
+ Example:
+
+ DAV: 1, 3
+
+19. Internationalization Considerations
+
+ In the realm of internationalization, this specification complies
+ with the IETF Character Set Policy [RFC2277]. In this specification,
+ human-readable fields can be found either in the value of a property,
+ or in an error message returned in a response entity body. In both
+ cases, the human-readable content is encoded using XML, which has
+ explicit provisions for character set tagging and encoding, and
+ requires that XML processors read XML elements encoded, at minimum,
+ using the UTF-8 [RFC3629] and UTF-16 [RFC2781] encodings of the ISO
+ 10646 multilingual plane. XML examples in this specification
+ demonstrate use of the charset parameter of the Content-Type header
+ (defined in [RFC3023]), as well as XML charset declarations.
+
+ XML also provides a language tagging capability for specifying the
+ language of the contents of a particular XML element. The "xml:lang"
+ attribute appears on an XML element to identify the language of its
+ content and attributes. See [REC-XML] for definitions of values and
+ scoping.
+
+ WebDAV applications MUST support the character set tagging, character
+ set encoding, and the language tagging functionality of the XML
+ specification. Implementors of WebDAV applications are strongly
+ encouraged to read "XML Media Types" [RFC3023] for instruction on
+ which MIME media type to use for XML transport, and on use of the
+ charset parameter of the Content-Type header.
+
+ Names used within this specification fall into four categories: names
+ of protocol elements such as methods and headers, names of XML
+ elements, names of properties, and names of conditions. Naming of
+ protocol elements follows the precedent of HTTP, using English names
+ encoded in US-ASCII for methods and headers. Since these protocol
+ elements are not visible to users, and are simply long token
+ identifiers, they do not need to support multiple languages.
+ Similarly, the names of XML elements used in this specification are
+ not visible to the user and hence do not need to support multiple
+ languages.
+
+ WebDAV property names are qualified XML names (pairs of XML namespace
+ name and local name). Although some applications (e.g., a generic
+ property viewer) will display property names directly to their users,
+ it is expected that the typical application will use a fixed set of
+ properties, and will provide a mapping from the property name and
+ namespace to a human-readable field when displaying the property name
+
+
+
+Dusseault Standards Track [Page 104]
+
+RFC 4918 WebDAV June 2007
+
+
+ to a user. It is only in the case where the set of properties is not
+ known ahead of time that an application need display a property name
+ to a user. We recommend that applications provide human-readable
+ property names wherever feasible.
+
+ For error reporting, we follow the convention of HTTP/1.1 status
+ codes, including with each status code a short, English description
+ of the code (e.g., 423 (Locked)). While the possibility exists that
+ a poorly crafted user agent would display this message to a user,
+ internationalized applications will ignore this message, and display
+ an appropriate message in the user's language and character set.
+
+ Since interoperation of clients and servers does not require locale
+ information, this specification does not specify any mechanism for
+ transmission of this information.
+
+20. Security Considerations
+
+ This section is provided to detail issues concerning security
+ implications of which WebDAV applications need to be aware.
+
+ All of the security considerations of HTTP/1.1 (discussed in
+ [RFC2616]) and XML (discussed in [RFC3023]) also apply to WebDAV. In
+ addition, the security risks inherent in remote authoring require
+ stronger authentication technology, introduce several new privacy
+ concerns, and may increase the hazards from poor server design.
+ These issues are detailed below.
+
+20.1. Authentication of Clients
+
+ Due to their emphasis on authoring, WebDAV servers need to use
+ authentication technology to protect not just access to a network
+ resource, but the integrity of the resource as well. Furthermore,
+ the introduction of locking functionality requires support for
+ authentication.
+
+ A password sent in the clear over an insecure channel is an
+ inadequate means for protecting the accessibility and integrity of a
+ resource as the password may be intercepted. Since Basic
+ authentication for HTTP/1.1 performs essentially clear text
+ transmission of a password, Basic authentication MUST NOT be used to
+ authenticate a WebDAV client to a server unless the connection is
+ secure. Furthermore, a WebDAV server MUST NOT send a Basic
+ authentication challenge in a WWW-Authenticate header unless the
+ connection is secure. An example of a secure connection would be a
+ Transport Layer Security (TLS) connection employing a strong cipher
+ suite and server authentication.
+
+
+
+
+Dusseault Standards Track [Page 105]
+
+RFC 4918 WebDAV June 2007
+
+
+ WebDAV applications MUST support the Digest authentication scheme
+ [RFC2617]. Since Digest authentication verifies that both parties to
+ a communication know a shared secret, a password, without having to
+ send that secret in the clear, Digest authentication avoids the
+ security problems inherent in Basic authentication while providing a
+ level of authentication that is useful in a wide range of scenarios.
+
+20.2. Denial of Service
+
+ Denial-of-service attacks are of special concern to WebDAV servers.
+ WebDAV plus HTTP enables denial-of-service attacks on every part of a
+ system's resources.
+
+ o The underlying storage can be attacked by PUTting extremely large
+ files.
+
+ o Asking for recursive operations on large collections can attack
+ processing time.
+
+ o Making multiple pipelined requests on multiple connections can
+ attack network connections.
+
+ WebDAV servers need to be aware of the possibility of a denial-of-
+ service attack at all levels. The proper response to such an attack
+ MAY be to simply drop the connection. Or, if the server is able to
+ make a response, the server MAY use a 400-level status request such
+ as 400 (Bad Request) and indicate why the request was refused (a 500-
+ level status response would indicate that the problem is with the
+ server, whereas unintentional DoS attacks are something the client is
+ capable of remedying).
+
+20.3. Security through Obscurity
+
+ WebDAV provides, through the PROPFIND method, a mechanism for listing
+ the member resources of a collection. This greatly diminishes the
+ effectiveness of security or privacy techniques that rely only on the
+ difficulty of discovering the names of network resources. Users of
+ WebDAV servers are encouraged to use access control techniques to
+ prevent unwanted access to resources, rather than depending on the
+ relative obscurity of their resource names.
+
+20.4. Privacy Issues Connected to Locks
+
+ When submitting a lock request, a user agent may also submit an
+ 'owner' XML field giving contact information for the person taking
+ out the lock (for those cases where a person, rather than a robot, is
+ taking out the lock). This contact information is stored in a DAV:
+ lockdiscovery property on the resource, and can be used by other
+
+
+
+Dusseault Standards Track [Page 106]
+
+RFC 4918 WebDAV June 2007
+
+
+ collaborators to begin negotiation over access to the resource.
+ However, in many cases, this contact information can be very private,
+ and should not be widely disseminated. Servers SHOULD limit read
+ access to the DAV:lockdiscovery property as appropriate.
+ Furthermore, user agents SHOULD provide control over whether contact
+ information is sent at all, and if contact information is sent,
+ control over exactly what information is sent.
+
+20.5. Privacy Issues Connected to Properties
+
+ Since property values are typically used to hold information such as
+ the author of a document, there is the possibility that privacy
+ concerns could arise stemming from widespread access to a resource's
+ property data. To reduce the risk of inadvertent release of private
+ information via properties, servers are encouraged to develop access
+ control mechanisms that separate read access to the resource body and
+ read access to the resource's properties. This allows a user to
+ control the dissemination of their property data without overly
+ restricting access to the resource's contents.
+
+20.6. Implications of XML Entities
+
+ XML supports a facility known as "external entities", defined in
+ Section 4.2.2 of [REC-XML], which instructs an XML processor to
+ retrieve and include additional XML. An external XML entity can be
+ used to append or modify the document type declaration (DTD)
+ associated with an XML document. An external XML entity can also be
+ used to include XML within the content of an XML document. For non-
+ validating XML, such as the XML used in this specification, including
+ an external XML entity is not required by XML. However, XML does
+ state that an XML processor may, at its discretion, include the
+ external XML entity.
+
+ External XML entities have no inherent trustworthiness and are
+ subject to all the attacks that are endemic to any HTTP GET request.
+ Furthermore, it is possible for an external XML entity to modify the
+ DTD, and hence affect the final form of an XML document, in the worst
+ case, significantly modifying its semantics or exposing the XML
+ processor to the security risks discussed in [RFC3023]. Therefore,
+ implementers must be aware that external XML entities should be
+ treated as untrustworthy. If a server chooses not to handle external
+ XML entities, it SHOULD respond to requests containing external
+ entities with the 'no-external-entities' condition code.
+
+ There is also the scalability risk that would accompany a widely
+ deployed application that made use of external XML entities. In this
+ situation, it is possible that there would be significant numbers of
+ requests for one external XML entity, potentially overloading any
+
+
+
+Dusseault Standards Track [Page 107]
+
+RFC 4918 WebDAV June 2007
+
+
+ server that fields requests for the resource containing the external
+ XML entity.
+
+ Furthermore, there's also a risk based on the evaluation of "internal
+ entities" as defined in Section 4.2.2 of [REC-XML]. A small,
+ carefully crafted request using nested internal entities may require
+ enormous amounts of memory and/or processing time to process. Server
+ implementers should be aware of this risk and configure their XML
+ parsers so that requests like these can be detected and rejected as
+ early as possible.
+
+20.7. Risks Connected with Lock Tokens
+
+ This specification encourages the use of "A Universally Unique
+ Identifier (UUID) URN Namespace" ([RFC4122]) for lock tokens
+ (Section 6.5), in order to guarantee their uniqueness across space
+ and time. Version 1 UUIDs (defined in Section 4) MAY contain a
+ "node" field that "consists of an IEEE 802 MAC address, usually the
+ host address. For systems with multiple IEEE addresses, any
+ available one can be used". Since a WebDAV server will issue many
+ locks over its lifetime, the implication is that it may also be
+ publicly exposing its IEEE 802 address.
+
+ There are several risks associated with exposure of IEEE 802
+ addresses. Using the IEEE 802 address:
+
+ o It is possible to track the movement of hardware from subnet to
+ subnet.
+
+ o It may be possible to identify the manufacturer of the hardware
+ running a WebDAV server.
+
+ o It may be possible to determine the number of each type of
+ computer running WebDAV.
+
+ This risk only applies to host-address-based UUID versions. Section
+ 4 of [RFC4122] describes several other mechanisms for generating
+ UUIDs that do not involve the host address and therefore do not
+ suffer from this risk.
+
+20.8. Hosting Malicious Content
+
+ HTTP has the ability to host programs that are executed on client
+ machines. These programs can take many forms including Web scripts,
+ executables, plug-in modules, and macros in documents. WebDAV does
+ not change any of the security concerns around these programs, yet
+ often WebDAV is used in contexts where a wide range of users can
+ publish documents on a server. The server might not have a close
+
+
+
+Dusseault Standards Track [Page 108]
+
+RFC 4918 WebDAV June 2007
+
+
+ trust relationship with the author that is publishing the document.
+ Servers that allow clients to publish arbitrary content can usefully
+ implement precautions to check that content published to the server
+ is not harmful to other clients. Servers could do this by techniques
+ such as restricting the types of content that is allowed to be
+ published and running virus and malware detection software on
+ published content. Servers can also mitigate the risk by having
+ appropriate access restriction and authentication of users that are
+ allowed to publish content to the server.
+
+21. IANA Considerations
+
+21.1. New URI Schemes
+
+ This specification defines two URI schemes:
+
+ 1. the "opaquelocktoken" scheme defined in Appendix C, and
+
+ 2. the "DAV" URI scheme, which historically was used in [RFC2518] to
+ disambiguate WebDAV property and XML element names and which
+ continues to be used for that purpose in this specification and
+ others extending WebDAV. Creation of identifiers in the "DAV:"
+ namespace is controlled by the IETF.
+
+ Note that defining new URI schemes for XML namespaces is now
+ discouraged. "DAV:" was defined before standard best practices
+ emerged.
+
+21.2. XML Namespaces
+
+ XML namespaces disambiguate WebDAV property names and XML elements.
+ Any WebDAV user or application can define a new namespace in order to
+ create custom properties or extend WebDAV XML syntax. IANA does not
+ need to manage such namespaces, property names, or element names.
+
+21.3. Message Header Fields
+
+ The message header fields below should be added to the permanent
+ registry (see [RFC3864]).
+
+21.3.1. DAV
+
+ Header field name: DAV
+
+ Applicable protocol: http
+
+ Status: standard
+
+
+
+
+Dusseault Standards Track [Page 109]
+
+RFC 4918 WebDAV June 2007
+
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.1)
+
+21.3.2. Depth
+
+ Header field name: Depth
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.2)
+
+21.3.3. Destination
+
+ Header field name: Destination
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.3)
+
+21.3.4. If
+
+ Header field name: If
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.4)
+
+21.3.5. Lock-Token
+
+ Header field name: Lock-Token
+
+ Applicable protocol: http
+
+ Status: standard
+
+
+
+
+Dusseault Standards Track [Page 110]
+
+RFC 4918 WebDAV June 2007
+
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.5)
+
+21.3.6. Overwrite
+
+ Header field name: Overwrite
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.6)
+
+21.3.7. Timeout
+
+ Header field name: Timeout
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.7)
+
+21.4. HTTP Status Codes
+
+ This specification defines the HTTP status codes
+
+ o 207 Multi-Status (Section 11.1)
+
+ o 422 Unprocessable Entity (Section 11.2),
+
+ o 423 Locked (Section 11.3),
+
+ o 424 Failed Dependency (Section 11.4) and
+
+ o 507 Insufficient Storage (Section 11.5),
+
+ to be updated in the registry at
+ <http://www.iana.org/assignments/http-status-codes>.
+
+ Note: the HTTP status code 102 (Processing) has been removed in this
+ specification; its IANA registration should continue to reference RFC
+ 2518.
+
+
+
+Dusseault Standards Track [Page 111]
+
+RFC 4918 WebDAV June 2007
+
+
+22. Acknowledgements
+
+ A specification such as this thrives on piercing critical review and
+ withers from apathetic neglect. The authors gratefully acknowledge
+ the contributions of the following people, whose insights were so
+ valuable at every stage of our work.
+
+ Contributors to RFC 2518
+
+ Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan
+ Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners-
+ Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith
+ Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee
+ Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan
+ Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis
+ Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der
+ Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven
+ Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten,
+ Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff,
+ Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike
+ Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi,
+ Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran,
+ Fabio Vitali, Gregory Woodhouse, and Lauren Wood.
+
+ Two from this list deserve special mention. The contributions by
+ Larry Masinter have been invaluable; he both helped the formation of
+ the working group and patiently coached the authors along the way.
+ In so many ways he has set high standards that we have toiled to
+ meet. The contributions of Judith Slein were also invaluable; by
+ clarifying the requirements and in patiently reviewing version after
+ version, she both improved this specification and expanded our minds
+ on document management.
+
+ We would also like to thank John Turner for developing the XML DTD.
+
+ The authors of RFC 2518 were Yaron Goland, Jim Whitehead, A. Faizi,
+ Steve Carter, and D. Jensen. Although their names had to be removed
+ due to IETF author count restrictions, they can take credit for the
+ majority of the design of WebDAV.
+
+ Additional Acknowledgements for This Specification
+
+ Significant contributors of text for this specification are listed as
+ contributors in the section below. We must also gratefully
+ acknowledge Geoff Clemm, Joel Soderberg, and Dan Brotsky for hashing
+ out specific text on the list or in meetings. Joe Hildebrand and
+ Cullen Jennings helped close many issues. Barry Lind described an
+ additional security consideration and Cullen Jennings provided text
+
+
+
+Dusseault Standards Track [Page 112]
+
+RFC 4918 WebDAV June 2007
+
+
+ for that consideration. Jason Crawford tracked issue status for this
+ document for a period of years, followed by Elias Sinderson.
+
+23. Contributors to This Specification
+
+ Julian Reschke
+ <green/>bytes GmbH
+ Hafenweg 16, 48155 Muenster, Germany
+ EMail: julian.reschke@greenbytes.de
+
+
+ Elias Sinderson
+ University of California, Santa Cruz
+ 1156 High Street, Santa Cruz, CA 95064
+ EMail: elias@cse.ucsc.edu
+
+
+ Jim Whitehead
+ University of California, Santa Cruz
+ 1156 High Street, Santa Cruz, CA 95064
+ EMail: ejw@soe.ucsc.edu
+
+24. Authors of RFC 2518
+
+ Y. Y. Goland
+ Microsoft Corporation
+ One Microsoft Way
+ Redmond, WA 98052-6399
+ EMail: yarong@microsoft.com
+
+
+ E. J. Whitehead, Jr.
+ Dept. Of Information and Computer Science
+ University of California, Irvine
+ Irvine, CA 92697-3425
+ EMail: ejw@ics.uci.edu
+
+
+ A. Faizi
+ Netscape
+ 685 East Middlefield Road
+ Mountain View, CA 94043
+ EMail: asad@netscape.com
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 113]
+
+RFC 4918 WebDAV June 2007
+
+
+ S. R. Carter
+ Novell
+ 1555 N. Technology Way
+ M/S ORM F111
+ Orem, UT 84097-2399
+ EMail: srcarter@novell.com
+
+
+ D. Jensen
+ Novell
+ 1555 N. Technology Way
+ M/S ORM F111
+ Orem, UT 84097-2399
+ EMail: dcjensen@novell.com
+
+25. References
+
+25.1. Normative References
+
+ [REC-XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler,
+ E., and F. Yergeau, "Extensible Markup Language
+ (XML) 1.0 (Fourth Edition)", W3C REC-xml-20060816,
+ August 2006,
+ <http://www.w3.org/TR/2006/REC-xml-20060816/>.
+
+ [REC-XML-INFOSET] Cowan, J. and R. Tobin, "XML Information Set
+ (Second Edition)", W3C REC-xml-infoset-20040204,
+ February 2004, <http://www.w3.org/TR/2004/
+ REC-xml-infoset-20040204/>.
+
+ [REC-XML-NAMES] Bray, T., Hollander, D., Layman, A., and R. Tobin,
+ "Namespaces in XML 1.0 (Second Edition)", W3C REC-
+ xml-names-20060816, August 2006, <http://
+ www.w3.org/TR/2006/REC-xml-names-20060816/>.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to
+ Indicate Requirement Levels", BCP 14, RFC 2119,
+ March 1997.
+
+ [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
+ Languages", BCP 18, RFC 2277, January 1998.
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+ Masinter, L., Leach, P., and T. Berners-Lee,
+ "Hypertext Transfer Protocol -- HTTP/1.1",
+ RFC 2616, June 1999.
+
+
+
+
+
+Dusseault Standards Track [Page 114]
+
+RFC 4918 WebDAV June 2007
+
+
+ [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J.,
+ Lawrence, S., Leach, P., Luotonen, A., and L.
+ Stewart, "HTTP Authentication: Basic and Digest
+ Access Authentication", RFC 2617, June 1999.
+
+ [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on
+ the Internet: Timestamps", RFC 3339, July 2002.
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of
+ ISO 10646", STD 63, RFC 3629, November 2003.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter,
+ "Uniform Resource Identifier (URI): Generic
+ Syntax", STD 66, RFC 3986, January 2005.
+
+ [RFC4122] Leach, P., Mealling, M., and R. Salz, "A
+ Universally Unique IDentifier (UUID) URN
+ Namespace", RFC 4122, July 2005.
+
+25.2. Informative References
+
+ [RFC2291] Slein, J., Vitali, F., Whitehead, E., and D.
+ Durand, "Requirements for a Distributed Authoring
+ and Versioning Protocol for the World Wide Web",
+ RFC 2291, February 1998.
+
+ [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S.,
+ and D. Jensen, "HTTP Extensions for Distributed
+ Authoring -- WEBDAV", RFC 2518, February 1999.
+
+ [RFC2781] Hoffman, P. and F. Yergeau, "UTF-16, an encoding
+ of ISO 10646", RFC 2781, February 2000.
+
+ [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML
+ Media Types", RFC 3023, January 2001.
+
+ [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and
+ J. Whitehead, "Versioning Extensions to WebDAV
+ (Web Distributed Authoring and Versioning)",
+ RFC 3253, March 2002.
+
+ [RFC3648] Whitehead, J. and J. Reschke, Ed., "Web
+ Distributed Authoring and Versioning (WebDAV)
+ Ordered Collections Protocol", RFC 3648,
+ December 2003.
+
+
+
+
+
+
+Dusseault Standards Track [Page 115]
+
+RFC 4918 WebDAV June 2007
+
+
+ [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J.
+ Whitehead, "Web Distributed Authoring and
+ Versioning (WebDAV) Access Control Protocol",
+ RFC 3744, May 2004.
+
+ [RFC3864] Klyne, G., Nottingham, M., and J. Mogul,
+ "Registration Procedures for Message Header
+ Fields", BCP 90, RFC 3864, September 2004.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 116]
+
+RFC 4918 WebDAV June 2007
+
+
+Appendix A. Notes on Processing XML Elements
+
+A.1. Notes on Empty XML Elements
+
+ XML supports two mechanisms for indicating that an XML element does
+ not have any content. The first is to declare an XML element of the
+ form <A></A>. The second is to declare an XML element of the form
+ <A/>. The two XML elements are semantically identical.
+
+A.2. Notes on Illegal XML Processing
+
+ XML is a flexible data format that makes it easy to submit data that
+ appears legal but in fact is not. The philosophy of "Be flexible in
+ what you accept and strict in what you send" still applies, but it
+ must not be applied inappropriately. XML is extremely flexible in
+ dealing with issues of whitespace, element ordering, inserting new
+ elements, etc. This flexibility does not require extension,
+ especially not in the area of the meaning of elements.
+
+ There is no kindness in accepting illegal combinations of XML
+ elements. At best, it will cause an unwanted result and at worst it
+ can cause real damage.
+
+A.3. Example - XML Syntax Error
+
+ The following request body for a PROPFIND method is illegal.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ <D:propname/>
+ </D:propfind>
+
+ The definition of the propfind element only allows for the allprop or
+ the propname element, not both. Thus, the above is an error and must
+ be responded to with a 400 (Bad Request).
+
+ Imagine, however, that a server wanted to be "kind" and decided to
+ pick the allprop element as the true element and respond to it. A
+ client running over a bandwidth limited line who intended to execute
+ a propname would be in for a big surprise if the server treated the
+ command as an allprop.
+
+ Additionally, if a server were lenient and decided to reply to this
+ request, the results would vary randomly from server to server, with
+ some servers executing the allprop directive, and others executing
+ the propname directive. This reduces interoperability rather than
+ increasing it.
+
+
+
+Dusseault Standards Track [Page 117]
+
+RFC 4918 WebDAV June 2007
+
+
+A.4. Example - Unexpected XML Element
+
+ The previous example was illegal because it contained two elements
+ that were explicitly banned from appearing together in the propfind
+ element. However, XML is an extensible language, so one can imagine
+ new elements being defined for use with propfind. Below is the
+ request body of a PROPFIND and, like the previous example, must be
+ rejected with a 400 (Bad Request) by a server that does not
+ understand the expired-props element.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.example.com/standards/props/">
+ <E:expired-props/>
+ </D:propfind>
+
+ To understand why a 400 (Bad Request) is returned, let us look at the
+ request body as the server unfamiliar with expired-props sees it.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.example.com/standards/props/">
+ </D:propfind>
+
+ As the server does not understand the 'expired-props' element,
+ according to the WebDAV-specific XML processing rules specified in
+ Section 17, it must process the request as if the element were not
+ there. Thus, the server sees an empty propfind, which by the
+ definition of the propfind element is illegal.
+
+ Please note that had the extension been additive, it would not
+ necessarily have resulted in a 400 (Bad Request). For example,
+ imagine the following request body for a PROPFIND:
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.example.com/standards/props/">
+ <D:propname/>
+ <E:leave-out>*boss*</E:leave-out>
+ </D:propfind>
+
+ The previous example contains the fictitious element leave-out. Its
+ purpose is to prevent the return of any property whose name matches
+ the submitted pattern. If the previous example were submitted to a
+ server unfamiliar with 'leave-out', the only result would be that the
+ 'leave-out' element would be ignored and a propname would be
+ executed.
+
+
+
+Dusseault Standards Track [Page 118]
+
+RFC 4918 WebDAV June 2007
+
+
+Appendix B. Notes on HTTP Client Compatibility
+
+ WebDAV was designed to be, and has been found to be, backward-
+ compatible with HTTP 1.1. The PUT and DELETE methods are defined in
+ HTTP and thus may be used by HTTP clients as well as WebDAV-aware
+ clients, but the responses to PUT and DELETE have been extended in
+ this specification in ways that only a WebDAV client would be
+ entirely prepared for. Some theoretical concerns were raised about
+ whether those responses would cause interoperability problems with
+ HTTP-only clients, and this section addresses those concerns.
+
+ Since any HTTP client ought to handle unrecognized 400-level and 500-
+ level status codes as errors, the following new status codes should
+ not present any issues: 422, 423, and 507 (424 is also a new status
+ code but it appears only in the body of a Multistatus response.) So,
+ for example, if an HTTP client attempted to PUT or DELETE a locked
+ resource, the 423 Locked response ought to result in a generic error
+ presented to the user.
+
+ The 207 Multistatus response is interesting because an HTTP client
+ issuing a DELETE request to a collection might interpret a 207
+ response as a success, even though it does not realize the resource
+ is a collection and cannot understand that the DELETE operation might
+ have been a complete or partial failure. That interpretation isn't
+ entirely justified, because a 200-level response indicates that the
+ server "received, understood, and accepted" the request, not that the
+ request resulted in complete success.
+
+ One option is that a server could treat a DELETE of a collection as
+ an atomic operation, and use either 204 No Content in case of
+ success, or some appropriate error response (400 or 500 level) for an
+ error. This approach would indeed maximize backward compatibility.
+ However, since interoperability tests and working group discussions
+ have not turned up any instances of HTTP clients issuing a DELETE
+ request against a WebDAV collection, this concern is more theoretical
+ than practical. Thus, servers are likely to be completely successful
+ at interoperating with HTTP clients even if they treat any collection
+ DELETE request as a WebDAV request and send a 207 Multi-Status
+ response.
+
+ In general, server implementations are encouraged to use the detailed
+ responses and other mechanisms defined in this document rather than
+ make changes for theoretical interoperability concerns.
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 119]
+
+RFC 4918 WebDAV June 2007
+
+
+Appendix C. The 'opaquelocktoken' Scheme and URIs
+
+ The 'opaquelocktoken' URI scheme was defined in [RFC2518] (and
+ registered by IANA) in order to create syntactically correct and
+ easy-to-generate URIs out of UUIDs, intended to be used as lock
+ tokens and to be unique across all resources for all time.
+
+ An opaquelocktoken URI is constructed by concatenating the
+ 'opaquelocktoken' scheme with a UUID, along with an optional
+ extension. Servers can create new UUIDs for each new lock token. If
+ a server wishes to reuse UUIDs, the server MUST add an extension, and
+ the algorithm generating the extension MUST guarantee that the same
+ extension will never be used twice with the associated UUID.
+
+ OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension]
+ ; UUID is defined in Section 3 of [RFC4122]. Note that LWS
+ ; is not allowed between elements of
+ ; this production.
+
+ Extension = path
+ ; path is defined in Section 3.3 of [RFC3986]
+
+
+Appendix D. Lock-null Resources
+
+ The original WebDAV model for locking unmapped URLs created "lock-
+ null resources". This model was over-complicated and some
+ interoperability and implementation problems were discovered. The
+ new WebDAV model for locking unmapped URLs (see Section 7.3) creates
+ "locked empty resources". Lock-null resources are deprecated. This
+ section discusses the original model briefly because clients MUST be
+ able to handle either model.
+
+ In the original "lock-null resource" model, which is no longer
+ recommended for implementation:
+
+ o A lock-null resource sometimes appeared as "Not Found". The
+ server responds with a 404 or 405 to any method except for PUT,
+ MKCOL, OPTIONS, PROPFIND, LOCK, UNLOCK.
+
+ o A lock-null resource does however show up as a member of its
+ parent collection.
+
+ o The server removes the lock-null resource entirely (its URI
+ becomes unmapped) if its lock goes away before it is converted to
+ a regular resource. Recall that locks go away not only when they
+ expire or are unlocked, but are also removed if a resource is
+ renamed or moved, or if any parent collection is renamed or moved.
+
+
+
+Dusseault Standards Track [Page 120]
+
+RFC 4918 WebDAV June 2007
+
+
+ o The server converts the lock-null resource into a regular resource
+ if a PUT request to the URL is successful.
+
+ o The server converts the lock-null resource into a collection if a
+ MKCOL request to the URL is successful (though interoperability
+ experience showed that not all servers followed this requirement).
+
+ o Property values were defined for DAV:lockdiscovery and DAV:
+ supportedlock properties but not necessarily for other properties
+ like DAV:getcontenttype.
+
+ Clients can easily interoperate both with servers that support the
+ old model "lock-null resources" and the recommended model of "locked
+ empty resources" by only attempting PUT after a LOCK to an unmapped
+ URL, not MKCOL or GET.
+
+D.1. Guidance for Clients Using LOCK to Create Resources
+
+ A WebDAV client implemented to this specification might find servers
+ that create lock-null resources (implemented before this
+ specification using [RFC2518]) as well as servers that create locked
+ empty resources. The response to the LOCK request will not indicate
+ what kind of resource was created. There are a few techniques that
+ help the client deal with either type.
+
+ If the client wishes to avoid accidentally creating either lock-
+ null or empty locked resources, an "If-Match: *" header can be
+ included with LOCK requests to prevent the server from creating a
+ new resource.
+
+ If a LOCK request creates a resource and the client subsequently
+ wants to overwrite that resource using a COPY or MOVE request, the
+ client should include an "Overwrite: T" header.
+
+ If a LOCK request creates a resource and the client then decides
+ to get rid of that resource, a DELETE request is supposed to fail
+ on a lock-null resource and UNLOCK should be used instead. But
+ with a locked empty resource, UNLOCK doesn't make the resource
+ disappear. Therefore, the client might have to try both requests
+ and ignore an error in one of the two requests.
+
+Appendix E. Guidance for Clients Desiring to Authenticate
+
+ Many WebDAV clients that have already been implemented have account
+ settings (similar to the way email clients store IMAP account
+ settings). Thus, the WebDAV client would be able to authenticate
+ with its first couple requests to the server, provided it had a way
+ to get the authentication challenge from the server with realm name,
+
+
+
+Dusseault Standards Track [Page 121]
+
+RFC 4918 WebDAV June 2007
+
+
+ nonce, and other challenge information. Note that the results of
+ some requests might vary according to whether or not the client is
+ authenticated -- a PROPFIND might return more visible resources if
+ the client is authenticated, yet not fail if the client is anonymous.
+
+ There are a number of ways the client might be able to trigger the
+ server to provide an authentication challenge. This appendix
+ describes a couple approaches that seem particularly likely to work.
+
+ The first approach is to perform a request that ought to require
+ authentication. However, it's possible that a server might handle
+ any request even without authentication, so to be entirely safe, the
+ client could add a conditional header to ensure that even if the
+ request passes permissions checks, it's not actually handled by the
+ server. An example of following this approach would be to use a PUT
+ request with an "If-Match" header with a made-up ETag value. This
+ approach might fail to result in an authentication challenge if the
+ server does not test authorization before testing conditionals as is
+ required (see Section 8.5), or if the server does not need to test
+ authorization.
+
+ Example - forcing auth challenge with write request
+
+ >>Request
+
+ PUT /forceauth.txt HTTP/1.1
+ Host: www.example.com
+ If-Match: "xxx"
+ Content-Type: text/plain
+ Content-Length: 0
+
+
+ The second approach is to use an Authorization header (defined in
+ [RFC2617]), which is likely to be rejected by the server but which
+ will then prompt a proper authentication challenge. For example, the
+ client could start with a PROPFIND request containing an
+ Authorization header containing a made-up Basic userid:password
+ string or with actual plausible credentials. This approach relies on
+ the server responding with a "401 Unauthorized" along with a
+ challenge if it receives an Authorization header with an unrecognized
+ username, invalid password, or if it doesn't even handle Basic
+ authentication. This seems likely to work because of the
+ requirements of RFC 2617:
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 122]
+
+RFC 4918 WebDAV June 2007
+
+
+ "If the origin server does not wish to accept the credentials sent
+ with a request, it SHOULD return a 401 (Unauthorized) response. The
+ response MUST include a WWW-Authenticate header field containing at
+ least one (possibly new) challenge applicable to the requested
+ resource."
+
+ There's a slight problem with implementing that recommendation in
+ some cases, because some servers do not even have challenge
+ information for certain resources. Thus, when there's no way to
+ authenticate to a resource or the resource is entirely publicly
+ available over all accepted methods, the server MAY ignore the
+ Authorization header, and the client will presumably try again later.
+
+ Example - forcing auth challenge with Authorization header
+
+ >>Request
+
+ PROPFIND /docs/ HTTP/1.1
+ Host: www.example.com
+ Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+ Content-type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ [body omitted]
+
+
+Appendix F. Summary of Changes from RFC 2518
+
+ This section lists major changes between this document and RFC 2518,
+ starting with those that are likely to result in implementation
+ changes. Servers will advertise support for all changes in this
+ specification by returning the compliance class "3" in the DAV
+ response header (see Sections 10.1 and 18.3).
+
+F.1. Changes for Both Client and Server Implementations
+
+ Collections and Namespace Operations
+
+ o The semantics of PROPFIND 'allprop' (Section 9.1) have been
+ relaxed so that servers return results including, at a minimum,
+ the live properties defined in this specification, but not
+ necessarily return other live properties. The 'allprop' directive
+ therefore means something more like "return all properties that
+ are supposed to be returned when 'allprop' is requested" -- a set
+ of properties that may include custom properties and properties
+ defined in other specifications if those other specifications so
+ require. Related to this, 'allprop' requests can now be extended
+ with the 'include' syntax to include specific named properties,
+
+
+
+Dusseault Standards Track [Page 123]
+
+RFC 4918 WebDAV June 2007
+
+
+ thereby avoiding additional requests due to changed 'allprop'
+ semantics.
+
+ o Servers are now allowed to reject PROPFIND requests with Depth:
+ Infinity. Clients that used this will need to be able to do a
+ series of Depth:1 requests instead.
+
+ o Multi-Status response bodies now can transport the value of HTTP's
+ Location response header in the new 'location' element. Clients
+ may use this to avoid additional roundtrips to the server when
+ there is a 'response' element with a 3xx status (see
+ Section 14.24).
+
+ o The definition of COPY has been relaxed so that it doesn't require
+ servers to first delete the target resources anymore (this was a
+ known incompatibility with [RFC3253]). See Section 9.8.
+
+ Headers and Marshalling
+
+ o The Destination and If request headers now allow absolute paths in
+ addition to full URIs (see Section 8.3). This may be useful for
+ clients operating through a reverse proxy that does rewrite the
+ Host request header, but not WebDAV-specific headers.
+
+ o This specification adopts the error marshalling extensions and the
+ "precondition/postcondition" terminology defined in [RFC3253] (see
+ Section 16). Related to that, it adds the "error" XML element
+ inside multistatus response bodies (see Section 14.5, however note
+ that it uses a format different from the one recommended in RFC
+ 3253).
+
+ o Senders and recipients are now required to support the UTF-16
+ character encoding in XML message bodies (see Section 19).
+
+ o Clients are now required to send the Depth header on PROPFIND
+ requests, although servers are still encouraged to support clients
+ that don't.
+
+ Locking
+
+ o RFC 2518's concept of "lock-null resources" (LNRs) has been
+ replaced by a simplified approach, the "locked empty resources"
+ (see Section 7.3). There are some aspects of lock-null resources
+ clients cannot rely on anymore, namely, the ability to use them to
+ create a locked collection or the fact that they disappear upon
+ UNLOCK when no PUT or MKCOL request was issued. Note that servers
+ are still allowed to implement LNRs as per RFC 2518.
+
+
+
+
+Dusseault Standards Track [Page 124]
+
+RFC 4918 WebDAV June 2007
+
+
+ o There is no implicit refresh of locks anymore. Locks are only
+ refreshed upon explicit request (see Section 9.10.2).
+
+ o Clarified that the DAV:owner value supplied in the LOCK request
+ must be preserved by the server just like a dead property
+ (Section 14.17). Also added the DAV:lockroot element
+ (Section 14.12), which allows clients to discover the root of
+ lock.
+
+F.2. Changes for Server Implementations
+
+ Collections and Namespace Operations
+
+ o Due to interoperability problems, allowable formats for contents
+ of 'href' elements in multistatus responses have been limited (see
+ Section 8.3).
+
+ o Due to lack of implementation, support for the 'propertybehavior'
+ request body for COPY and MOVE has been removed. Instead,
+ requirements for property preservation have been clarified (see
+ Sections 9.8 and 9.9).
+
+ Properties
+
+ o Strengthened server requirements for storage of property values,
+ in particular persistence of language information (xml:lang),
+ whitespace, and XML namespace information (see Section 4.3).
+
+ o Clarified requirements on which properties should be writable by
+ the client; in particular, setting "DAV:displayname" should be
+ supported by servers (see Section 15).
+
+ o Only 'rfc1123-date' productions are legal as values for DAV:
+ getlastmodified (see Section 15.7).
+
+ Headers and Marshalling
+
+ o Servers are now required to do authorization checks before
+ processing conditional headers (see Section 8.5).
+
+ Locking
+
+ o Strengthened requirement to check identity of lock creator when
+ accessing locked resources (see Section 6.4). Clients should be
+ aware that lock tokens returned to other principals can only be
+ used to break a lock, if at all.
+
+
+
+
+
+Dusseault Standards Track [Page 125]
+
+RFC 4918 WebDAV June 2007
+
+
+ o Section 8.10.4 of [RFC2518] incorrectly required servers to return
+ a 409 status where a 207 status was really appropriate. This has
+ been corrected (Section 9.10).
+
+F.3. Other Changes
+
+ The definition of collection state has been fixed so it doesn't vary
+ anymore depending on the Request-URI (see Section 5.2).
+
+ The DAV:source property introduced in Section 4.6 of [RFC2518] was
+ removed due to lack of implementation experience.
+
+ The DAV header now allows non-IETF extensions through URIs in
+ addition to compliance class tokens. It also can now be used in
+ requests, although this specification does not define any associated
+ semantics for the compliance classes defined in here (see
+ Section 10.1).
+
+ In RFC 2518, the definition of the Depth header (Section 9.2)
+ required that, by default, request headers would be applied to each
+ resource in scope. Based on implementation experience, the default
+ has now been reversed (see Section 10.2).
+
+ The definitions of HTTP status code 102 ([RFC2518], Section 10.1) and
+ the Status-URI response header (Section 9.7) have been removed due to
+ lack of implementation.
+
+ The TimeType format used in the Timeout request header and the
+ "timeout" XML element used to be extensible. Now, only the two
+ formats defined by this specification are allowed (see Section 10.7).
+
+Author's Address
+
+ Lisa Dusseault (editor)
+ CommerceNet
+ 2064 Edgewood Dr.
+ Palo Alto, CA 94303
+ US
+
+ EMail: ldusseault@commerce.net
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 126]
+
+RFC 4918 WebDAV June 2007
+
+
+Full Copyright Statement
+
+ Copyright (C) The IETF Trust (2007).
+
+ This document is subject to the rights, licenses and restrictions
+ contained in BCP 78, and except as set forth therein, the authors
+ retain all their rights.
+
+ This document and the information contained herein are provided on an
+ "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+ OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
+ THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
+ OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
+ THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Intellectual Property
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; nor does it represent that it has
+ made any independent effort to identify any such rights. Information
+ on the procedures with respect to rights in RFC documents can be
+ found in BCP 78 and BCP 79.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use of
+ such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository at
+ http://www.ietf.org/ipr.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to implement
+ this standard. Please address the information to the IETF at
+ ietf-ipr@ietf.org.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+Dusseault Standards Track [Page 127]
+
diff --git a/docs/rfcs/rfc5397.txt b/docs/rfcs/rfc5397.txt
new file mode 100644
index 0000000..616055e
--- /dev/null
+++ b/docs/rfcs/rfc5397.txt
@@ -0,0 +1,281 @@
+
+
+
+Network Working Group W. Sanchez
+Request for Comments: 5397 C. Daboo
+Category: Standards Track Apple Inc.
+ December 2008
+
+
+ WebDAV Current Principal Extension
+
+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) 2008 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document.
+
+Abstract
+
+ This specification defines a new WebDAV property that allows clients
+ to quickly determine the principal corresponding to the current
+ authenticated user.
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
+ 3. DAV:current-user-principal . . . . . . . . . . . . . . . . . . 3
+ 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 4
+ 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 6. Normative References . . . . . . . . . . . . . . . . . . . . . 4
+
+
+
+
+
+
+
+
+
+Sanchez & Daboo Standards Track [Page 1]
+
+RFC 5397 WebDAV Current Principal December 2008
+
+
+1. Introduction
+
+ WebDAV [RFC4918] is an extension to HTTP [RFC2616] to support
+ improved document authoring capabilities. The WebDAV Access Control
+ Protocol ("WebDAV ACL") [RFC3744] extension adds access control
+ capabilities to WebDAV. It introduces the concept of a "principal"
+ resource, which is used to represent information about authenticated
+ entities on the system.
+
+ Some clients have a need to determine which [RFC3744] principal a
+ server is associating with the currently authenticated HTTP user.
+ While [RFC3744] defines a DAV:current-user-privilege-set property for
+ retrieving the privileges granted to that principal, there is no
+ recommended way to identify the principal in question, which is
+ necessary to perform other useful operations. For example, a client
+ may wish to determine which groups the current user is a member of,
+ or modify a property of the principal resource associated with the
+ current user.
+
+ The DAV:principal-match REPORT provides some useful functionality,
+ but there are common situations where the results from that query can
+ be ambiguous. For example, not only is an individual user principal
+ returned, but also every group principal that the user is a member
+ of, and there is no clear way to distinguish which is which.
+
+ This specification proposes an extension to WebDAV ACL that adds a
+ DAV:current-user-principal property to resources under access control
+ on the server. This property provides a URL to a principal resource
+ corresponding to the currently authenticated user. This allows a
+ client to "bootstrap" itself by performing additional queries on the
+ principal resource to obtain additional information from that
+ resource, which is the purpose of this extension. Note that while it
+ is possible for multiple URLs to refer to the same principal
+ resource, or for multiple principal resources to correspond to a
+ single principal, this specification only allows for a single http(s)
+ URL in the DAV:current-user-principal property. If a client wishes
+ to obtain alternate URLs for the principal, it can query the
+ principal resource for this information; it is not the purpose of
+ this extension to provide a complete list of such URLs, but simply to
+ provide a means to locate a resource which contains that (and other)
+ information.
+
+2. Conventions Used in This Document
+
+ 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 [RFC2119].
+
+
+
+
+Sanchez & Daboo Standards Track [Page 2]
+
+RFC 5397 WebDAV Current Principal December 2008
+
+
+ When XML element types in the namespace "DAV:" are referenced in this
+ document outside of the context of an XML fragment, the string "DAV:"
+ will be prefixed to the element type names.
+
+ Processing of XML by clients and servers MUST follow the rules
+ defined in Section 17 of WebDAV [RFC4918].
+
+ Some of the declarations refer to XML elements defined by WebDAV
+ [RFC4918].
+
+3. DAV:current-user-principal
+
+ Name: current-user-principal
+
+ Namespace: DAV:
+
+ Purpose: Indicates a URL for the currently authenticated user's
+ principal resource on the server.
+
+ Value: A single DAV:href or DAV:unauthenticated element.
+
+ Protected: This property is computed on a per-request basis, and
+ therefore is protected.
+
+ Description: The DAV:current-user-principal property contains either
+ a DAV:href or DAV:unauthenticated XML element. The DAV:href
+ element contains a URL to a principal resource corresponding to
+ the currently authenticated user. That URL MUST be one of the
+ URLs in the DAV:principal-URL or DAV:alternate-URI-set properties
+ defined on the principal resource and MUST be an http(s) scheme
+ URL. When authentication has not been done or has failed, this
+ property MUST contain the DAV:unauthenticated pseudo-principal.
+
+ In some cases, there may be multiple principal resources
+ corresponding to the same authenticated principal. In that case,
+ the server is free to choose any one of the principal resource
+ URIs for the value of the DAV:current-user-principal property.
+ However, servers SHOULD be consistent and use the same principal
+ resource URI for each authenticated principal.
+
+ COPY/MOVE behavior: This property is computed on a per-request
+ basis, and is thus never copied or moved.
+
+ Definition:
+
+ <!ELEMENT current-user-principal (unauthenticated | href)>
+ <!-- href value: a URL to a principal resource -->
+
+
+
+
+Sanchez & Daboo Standards Track [Page 3]
+
+RFC 5397 WebDAV Current Principal December 2008
+
+
+ Example:
+
+ <D:current-user-principal xmlns:D="DAV:">
+ <D:href>/principals/users/cdaboo</D:href>
+ </D:current-user-principal>
+
+4. Security Considerations
+
+ This specification does not introduce any additional security issues
+ beyond those defined for HTTP [RFC2616], WebDAV [RFC4918], and WebDAV
+ ACL [RFC3744].
+
+5. Acknowledgments
+
+ This specification is based on discussions that took place within the
+ Calendaring and Scheduling Consortium's CalDAV Technical Committee.
+ The authors thank the participants of that group for their input.
+
+ The authors thank Julian Reschke for his valuable input via the
+ WebDAV working group mailing list.
+
+6. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+ Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
+ Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+ [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
+ Distributed Authoring and Versioning (WebDAV)
+ Access Control Protocol", RFC 3744, May 2004.
+
+ [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+
+Authors' Addresses
+
+ Wilfredo Sanchez
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: wsanchez@wsanchez.net
+ URI: http://www.apple.com/
+
+
+
+
+Sanchez & Daboo Standards Track [Page 4]
+
+RFC 5397 WebDAV Current Principal December 2008
+
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: cyrus@daboo.name
+ URI: http://www.apple.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sanchez & Daboo Standards Track [Page 5]
+
+
diff --git a/docs/rfcs/rfc6352.txt b/docs/rfcs/rfc6352.txt
new file mode 100644
index 0000000..cb03747
--- /dev/null
+++ b/docs/rfcs/rfc6352.txt
@@ -0,0 +1,2691 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Daboo
+Request for Comments: 6352 Apple
+Category: Standards Track August 2011
+ISSN: 2070-1721
+
+
+ CardDAV: vCard Extensions to
+ Web Distributed Authoring and Versioning (WebDAV)
+
+Abstract
+
+ This document defines extensions to the Web Distributed Authoring and
+ Versioning (WebDAV) protocol to specify a standard way of accessing,
+ managing, and sharing contact information based on the vCard format.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6352.
+
+Copyright Notice
+
+ Copyright (c) 2011 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+ This document may contain material from IETF Documents or IETF
+ Contributions published or made publicly available before November
+ 10, 2008. The person(s) controlling the copyright in some of this
+ material may not have granted the IETF Trust the right to allow
+
+
+
+Daboo Standards Track [Page 1]
+
+RFC 6352 CardDAV August 2011
+
+
+ modifications of such material outside the IETF Standards Process.
+ Without obtaining an adequate license from the person(s) controlling
+ the copyright in such materials, this document may not be modified
+ outside the IETF Standards Process, and derivative works of it may
+ not be created outside the IETF Standards Process, except to format
+ it for publication as an RFC or to translate it into languages other
+ than English.
+
+Table of Contents
+
+ 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4
+ 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6
+ 4. Address Book Data Model . . . . . . . . . . . . . . . . . . . 7
+ 4.1. Address Book Server . . . . . . . . . . . . . . . . . . . 7
+ 5. Address Book Resources . . . . . . . . . . . . . . . . . . . . 7
+ 5.1. Address Object Resources . . . . . . . . . . . . . . . . . 7
+ 5.1.1. Data Type Conversion . . . . . . . . . . . . . . . . . 8
+ 5.1.1.1. Additional Precondition for GET . . . . . . . . . 8
+ 5.2. Address Book Collections . . . . . . . . . . . . . . . . . 9
+ 6. Address Book Feature . . . . . . . . . . . . . . . . . . . . . 10
+ 6.1. Address Book Support . . . . . . . . . . . . . . . . . . . 10
+ 6.1.1. Example: Using OPTIONS for the Discovery of
+ Support for CardDAV . . . . . . . . . . . . . . . . . 10
+ 6.2. Address Book Properties . . . . . . . . . . . . . . . . . 10
+ 6.2.1. CARDDAV:addressbook-description Property . . . . . . . 10
+ 6.2.2. CARDDAV:supported-address-data Property . . . . . . . 11
+ 6.2.3. CARDDAV:max-resource-size Property . . . . . . . . . . 12
+ 6.3. Creating Resources . . . . . . . . . . . . . . . . . . . . 13
+ 6.3.1. Extended MKCOL Method . . . . . . . . . . . . . . . . 13
+ 6.3.1.1. Example - Successful MKCOL Request . . . . . . . . 14
+ 6.3.2. Creating Address Object Resources . . . . . . . . . . 15
+ 6.3.2.1. Additional Preconditions for PUT, COPY, and
+ MOVE . . . . . . . . . . . . . . . . . . . . . . . 16
+ 6.3.2.2. Non-Standard vCard Properties and Parameters . . . 17
+ 6.3.2.3. Address Object Resource Entity Tag . . . . . . . . 18
+ 7. Address Book Access Control . . . . . . . . . . . . . . . . . 18
+ 7.1. Additional Principal Properties . . . . . . . . . . . . . 18
+ 7.1.1. CARDDAV:addressbook-home-set Property . . . . . . . . 19
+ 7.1.2. CARDDAV:principal-address Property . . . . . . . . . . 19
+ 8. Address Book Reports . . . . . . . . . . . . . . . . . . . . . 20
+ 8.1. REPORT Method . . . . . . . . . . . . . . . . . . . . . . 20
+ 8.2. Ordinary Collections . . . . . . . . . . . . . . . . . . . 21
+ 8.3. Searching Text: Collations . . . . . . . . . . . . . . . . 21
+ 8.3.1. CARDDAV:supported-collation-set Property . . . . . . . 22
+ 8.4. Partial Retrieval . . . . . . . . . . . . . . . . . . . . 23
+ 8.5. Non-Standard Properties and Parameters . . . . . . . . . . 23
+
+
+
+
+Daboo Standards Track [Page 2]
+
+RFC 6352 CardDAV August 2011
+
+
+ 8.6. CARDDAV:addressbook-query Report . . . . . . . . . . . . . 23
+ 8.6.1. Limiting Results . . . . . . . . . . . . . . . . . . . 25
+ 8.6.2. Truncation of Results . . . . . . . . . . . . . . . . 25
+ 8.6.3. Example: Partial Retrieval of vCards Matching
+ NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 26
+ 8.6.4. Example: Partial Retrieval of vCards Matching a
+ Full Name or Email Address . . . . . . . . . . . . . . 27
+ 8.6.5. Example: Truncated Results . . . . . . . . . . . . . . 29
+ 8.7. CARDDAV:addressbook-multiget Report . . . . . . . . . . . 31
+ 8.7.1. Example: CARDDAV:addressbook-multiget Report . . . . . 32
+ 8.7.2. Example: CARDDAV:addressbook-multiget Report . . . . . 33
+ 9. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . 34
+ 9.1. Restrict the Properties Returned . . . . . . . . . . . . . 34
+ 9.2. Avoiding Lost Updates . . . . . . . . . . . . . . . . . . 35
+ 9.3. Client Configuration . . . . . . . . . . . . . . . . . . . 35
+ 9.4. Finding Other Users' Address Books . . . . . . . . . . . . 35
+ 10. XML Element Definitions . . . . . . . . . . . . . . . . . . . 36
+ 10.1. CARDDAV:addressbook XML Element . . . . . . . . . . . . . 36
+ 10.2. CARDDAV:supported-collation XML Element . . . . . . . . . 36
+ 10.3. CARDDAV:addressbook-query XML Element . . . . . . . . . . 37
+ 10.4. CARDDAV:address-data XML Element . . . . . . . . . . . . . 37
+ 10.4.1. CARDDAV:allprop XML Element . . . . . . . . . . . . . 39
+ 10.4.2. CARDDAV:prop XML Element . . . . . . . . . . . . . . . 39
+ 10.5. CARDDAV:filter XML Element . . . . . . . . . . . . . . . . 40
+ 10.5.1. CARDDAV:prop-filter XML Element . . . . . . . . . . . 40
+ 10.5.2. CARDDAV:param-filter XML Element . . . . . . . . . . . 41
+ 10.5.3. CARDDAV:is-not-defined XML Element . . . . . . . . . . 42
+ 10.5.4. CARDDAV:text-match XML Element . . . . . . . . . . . . 42
+ 10.6. CARDDAV:limit XML Element . . . . . . . . . . . . . . . . 43
+ 10.6.1. CARDDAV:nresults XML Element . . . . . . . . . . . . . 44
+ 10.7. CARDDAV:addressbook-multiget XML Element . . . . . . . . . 44
+ 11. Service Discovery via SRV Records . . . . . . . . . . . . . . 45
+ 12. Internationalization Considerations . . . . . . . . . . . . . 45
+ 13. Security Considerations . . . . . . . . . . . . . . . . . . . 45
+ 14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 46
+ 14.1. Namespace Registration . . . . . . . . . . . . . . . . . . 46
+ 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
+ 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 47
+ 16.1. Normative References . . . . . . . . . . . . . . . . . . . 47
+ 16.2. Informative References . . . . . . . . . . . . . . . . . . 48
+
+
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 3]
+
+RFC 6352 CardDAV August 2011
+
+
+1. Introduction and Overview
+
+ Address books containing contact information are a key component of
+ personal information management tools, such as email, calendaring and
+ scheduling, and instant messaging clients. To date several protocols
+ have been used for remote access to contact data, including the
+ Lightweight Directory Access Protocol (LDAP) [RFC4510], Internet
+ Message Support Protocol [IMSP], and Application Configuration Access
+ Protocol (ACAP) [RFC2244], together with SyncML used for
+ synchronization of such data.
+
+ WebDAV [RFC4918] offers a number of advantages as a framework or
+ basis for address book access and management. Most of these
+ advantages boil down to a significant reduction in the costs of
+ design, implementation, interoperability testing, and deployment.
+
+ The key features of address book support with WebDAV are:
+
+ 1. Ability to use multiple address books with hierarchical layout.
+
+ 2. Ability to control access to individual address books and address
+ entries as per WebDAV Access Control List (ACL) [RFC3744].
+
+ 3. Principal collections can be used to enumerate and query other
+ users on the system as per WebDAV ACL [RFC3744].
+
+ 4. Server-side searching of address data, avoiding the need for
+ clients to download an entire address book in order to do a quick
+ address 'expansion' operation.
+
+ 5. Well-defined internationalization support through WebDAV's use of
+ XML.
+
+ 6. Use of vCards [RFC2426] for well-defined address schema to
+ enhance client interoperability.
+
+ 7. Many limited clients (e.g., mobile devices) contain an HTTP stack
+ that makes implementing WebDAV much easier than other protocols.
+
+ The key disadvantage of address book support in WebDAV is:
+
+ 1. Lack of change notification. Many of the alternative protocols
+ also lack this ability. However, an extension for push
+ notifications could easily be developed.
+
+ vCard is a MIME directory profile aimed at encapsulating personal
+ addressing and contact information about people. The specification
+ of vCard was originally done by the Versit consortium, with a
+
+
+
+Daboo Standards Track [Page 4]
+
+RFC 6352 CardDAV August 2011
+
+
+ subsequent 3.0 version standardized by the IETF [RFC2426]. vCard is
+ in widespread use in email clients and mobile devices as a means of
+ encapsulating address information for transport via email or for
+ import/export and synchronization operations.
+
+ An update to vCard -- vCard v4 -- is currently being developed
+ [RFC6350] and is compatible with this specification.
+
+2. 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 [RFC2119].
+
+ The term "protected" is used in the Conformance field of property
+ definitions as defined in Section 15 of [RFC4918].
+
+ This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section
+ 3.2) as a purely notational convention. WebDAV request and response
+ bodies cannot be validated by a DTD due to the specific extensibility
+ rules defined in Section 17 of [RFC4918] and due to the fact that all
+ XML elements defined by that specification use the XML namespace name
+ "DAV:". In particular:
+
+ 1. Element names use the "DAV:" namespace.
+
+ 2. Element ordering is irrelevant unless explicitly stated.
+
+ 3. Extension elements (elements not already defined as valid child
+ elements) may be added anywhere, except when explicitly stated
+ otherwise.
+
+ 4. Extension attributes (attributes not already defined as valid for
+ this element) may be added anywhere, except when explicitly
+ stated otherwise.
+
+ The namespace "urn:ietf:params:xml:ns:carddav" is reserved for the
+ XML elements defined in this specification, its revisions, and
+ related CardDAV specifications. XML elements defined by individual
+ implementations MUST NOT use the "urn:ietf:params:xml:ns:carddav"
+ namespace, and instead should use a namespace that they control.
+
+ When XML element types in the namespaces "DAV:" and
+ "urn:ietf:params:xml:ns:carddav" are referenced in this document
+ outside of the context of an XML fragment, the strings "DAV:" and
+ "CARDDAV:" will be prefixed to the element types, respectively.
+
+
+
+
+
+Daboo Standards Track [Page 5]
+
+RFC 6352 CardDAV August 2011
+
+
+ This document inherits, and sometimes extends, DTD productions from
+ Section 14 of [RFC4918].
+
+ Also, note that some CardDAV XML element names are identical to
+ WebDAV XML element names, though their namespace differs. Care must
+ be taken not to confuse the two sets of names.
+
+3. Requirements Overview
+
+ This section lists what functionality is required of a CardDAV
+ server. To advertise support for CardDAV, a server:
+
+ o MUST support vCard v3 [RFC2426] as a media type for the address
+ object resource format;
+
+ o MUST support WebDAV Class 3 [RFC4918];
+
+ o MUST support WebDAV ACL [RFC3744];
+
+ o MUST support secure transport as defined in [RFC2818] using
+ Transport Layer Security (TLS) [RFC5246] and using the certificate
+ validation procedures described in [RFC5280];
+
+ o MUST support ETags [RFC2616] with additional requirements
+ specified in Section 6.3.2.3 of this document;
+
+ o MUST support all address book reports defined in Section 8 of this
+ document; and
+
+ o MUST advertise support on all address book collections and address
+ object resources for the address book reports in the
+ DAV:supported-report-set property, as defined in Versioning
+ Extensions to WebDAV [RFC3253].
+
+ In addition, a server:
+
+ o SHOULD support vCard v4 [RFC6350] as a media type for the address
+ object resource format;
+
+ o SHOULD support the extended MKCOL method [RFC5689] to create
+ address book collections as defined in Section 6.3.1 of this
+ document.
+
+ o SHOULD support the DAV:current-user-principal-URL property as
+ defined in [RFC5397] to give clients a fast way to locate user
+ principals.
+
+
+
+
+
+Daboo Standards Track [Page 6]
+
+RFC 6352 CardDAV August 2011
+
+
+4. Address Book Data Model
+
+ As a brief overview, a CardDAV address book is modeled as a WebDAV
+ collection with a well-defined structure; each of these address book
+ collections contains a number of resources representing address
+ objects as their direct child resources. Each resource representing
+ an address object is called an "address object resource". Each
+ address object resource and each address book collection can be
+ individually locked and have individual WebDAV properties.
+ Requirements derived from this model are provided in Sections 5.1 and
+ 5.2.
+
+4.1. Address Book Server
+
+ A CardDAV server is an address-aware engine combined with a WebDAV
+ server. The server may include address data in some parts of its URL
+ namespace and non-address data in other parts.
+
+ A WebDAV server can advertise itself as a CardDAV server if it
+ supports the functionality defined in this specification at any point
+ within the root of its repository. That might mean that address data
+ is spread throughout the repository and mixed with non-address data
+ in nearby collections (e.g., address data may be found in /lisa/
+ addressbook/ as well as in /bernard/addressbook/, and non-address
+ data in /lisa/calendars/). Or, it might mean that address data can
+ be found only in certain sections of the repository (e.g.,
+ /addressbooks/user/). Address book features are only required in the
+ repository sections that are or contain address objects. So, a
+ repository confining address data to the /carddav/ collection would
+ only need to support the CardDAV required features within that
+ collection.
+
+ The CardDAV server is the canonical location for address data and
+ state information. Clients may submit requests to change data or
+ download data. Clients may store address objects offline and attempt
+ to synchronize at a later time. Address data on the server can
+ change between the time of last synchronization and when attempting
+ an update, as address book collections may be shared and accessible
+ via multiple clients. Entity tags and locking help this work.
+
+5. Address Book Resources
+
+5.1. Address Object Resources
+
+ This specification uses vCard as the default format for address or
+ contact information being stored on the server. However, this
+ specification does allow other formats for address data provided that
+ the server advertises support for those additional formats as
+
+
+
+Daboo Standards Track [Page 7]
+
+RFC 6352 CardDAV August 2011
+
+
+ described below. The requirements in this section pertain to vCard
+ address data or formats that follow the semantics of vCard data.
+
+ Address object resources contained in address book collections MUST
+ contain a single vCard component only.
+
+ vCard components in an address book collection MUST have a UID
+ property value that MUST be unique in the scope of the address book
+ collection in which it is contained.
+
+5.1.1. Data Type Conversion
+
+ Servers might support more than one primary media type for address
+ object resources, for example, vCard v3.0 and vCard v4.0. In such
+ cases, servers have to accept all media types that they advertise via
+ the CARDDAV:supported-address-data WebDAV property (see
+ Section 6.2.2).
+
+ However, clients can use standard HTTP content negotiation behavior
+ (the Accept request header defined in Section 14.1 of [RFC2616]) to
+ request that an address object resource's data be returned in a
+ specific media type format. For example, a client merely capable of
+ handling vCard v3.0 would only want to have address object resources
+ returned in v3.0 format.
+
+ Additionally, REPORT requests, defined later in this specification,
+ allow for the return of address object resource data within an XML
+ response body. Again, the client can use content negotiation to
+ request that data be returned in a specific media type by specifying
+ appropriate attributes on the CARDDAV:address-data XML element used
+ in the request body (see Section 10.4).
+
+ In some cases, it might not be possible for a server to convert from
+ one media type to another. When that happens, the server MUST return
+ the CARDDAV:supported-address-data-conversion precondition (see
+ below) in the response body (when the failure to convert applies to
+ the entire response) or use that same precondition code in the
+ DAV:response XML element in the response for the targeted address
+ object resource when one of the REPORTs defined below is used. See
+ Section 8.7.2 for an example of this.
+
+5.1.1.1. Additional Precondition for GET
+
+ This specification creates additional preconditions for the GET
+ method.
+
+
+
+
+
+
+Daboo Standards Track [Page 8]
+
+RFC 6352 CardDAV August 2011
+
+
+ The new precondition is:
+
+ (CARDDAV:supported-address-data-conversion): The resource targeted
+ by the GET request can be converted to the media type specified in
+ the Accept request header included with the request.
+
+5.2. Address Book Collections
+
+ Address book collections appear to clients as a WebDAV collection
+ resource, identified by a URL. An address book collection MUST
+ report the DAV:collection and CARDDAV:addressbook XML elements in the
+ value of the DAV:resourcetype property. The element type declaration
+ for CARDDAV:addressbook is:
+
+ <!ELEMENT addressbook EMPTY>
+
+ An address book collection can be created through provisioning (e.g.,
+ automatically created when a user's account is provisioned), or it
+ can be created with the extended MKCOL method (see Section 6.3.1).
+ This can be used by a user to create additional address books (e.g.,
+ "soccer team members") or for users to share an address book (e.g.,
+ "sales team contacts"). However, note that this document doesn't
+ define what extra address book collections are for. Users must rely
+ on non-standard cues to find out what an address book collection is
+ for, or use the CARDDAV:addressbook-description property defined in
+ Section 6.2.1 to provide such a cue.
+
+ The following restrictions are applied to the resources within an
+ address book collection:
+
+ a. Address book collections MUST only contain address object
+ resources and collections that are not address book collections.
+ That is, the only "top-level" non-collection resources allowed in
+ an address book collection are address object resources. This
+ ensures that address book clients do not have to deal with non-
+ address data in an address book collection, though they do have
+ to distinguish between address object resources and collections
+ when using standard WebDAV techniques to examine the contents of
+ a collection.
+
+ b. Collections contained in address book collections MUST NOT
+ contain address book collections at any depth. That is,
+ "nesting" of address book collections within other address book
+ collections at any depth is not allowed. This specification does
+ not define how collections contained in an address book
+ collection are used or how they relate to any address object
+ resources contained in the address book collection.
+
+
+
+
+Daboo Standards Track [Page 9]
+
+RFC 6352 CardDAV August 2011
+
+
+ Multiple address book collections MAY be children of the same
+ collection.
+
+6. Address Book Feature
+
+6.1. Address Book Support
+
+ A server supporting the features described in this document MUST
+ include "addressbook" as a field in the DAV response header from an
+ OPTIONS request on any resource that supports any address book
+ properties, reports, or methods. A value of "addressbook" in the DAV
+ response header MUST indicate that the server supports all MUST level
+ requirements and REQUIRED features specified in this document.
+
+6.1.1. Example: Using OPTIONS for the Discovery of Support for CardDAV
+
+ >> Request <<
+
+ OPTIONS /addressbooks/users/ HTTP/1.1
+ Host: addressbook.example.com
+
+ >> Response <<
+
+ HTTP/1.1 200 OK
+ Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
+ Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
+ DAV: 1, 2, 3, access-control, addressbook
+ DAV: extended-mkcol
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Length: 0
+
+ In this example, the OPTIONS response indicates that the server
+ supports CardDAV in this namespace; therefore, the '/addressbooks/
+ users/' collection may be used as a parent for address book
+ collections as the extended MKCOL method is available and as a
+ possible target for REPORT requests for address book reports.
+
+6.2. Address Book Properties
+
+6.2.1. CARDDAV:addressbook-description Property
+
+ Name: addressbook-description
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Provides a human-readable description of the address book
+ collection.
+
+
+
+
+Daboo Standards Track [Page 10]
+
+RFC 6352 CardDAV August 2011
+
+
+ Value: Any text.
+
+ Protected: SHOULD NOT be protected so that users can specify a
+ description.
+
+ COPY/MOVE behavior: This property value SHOULD be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: This property contains a description of the address
+ book collection that is suitable for presentation to a user. The
+ xml:lang attribute can be used to add a language tag for the value
+ of this property.
+
+ Definition:
+
+ <!ELEMENT addressbook-description (#PCDATA)>
+ <!-- PCDATA value: string -->
+
+ Example:
+
+ <C:addressbook-description xml:lang="fr-CA"
+ xmlns:C="urn:ietf:params:xml:ns:carddav"
+ >Adresses de Oliver Daboo</C:addressbook-description>
+
+6.2.2. CARDDAV:supported-address-data Property
+
+ Name: supported-address-data
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies what media types are allowed for address object
+ resources in an address book collection.
+
+ Protected: MUST be protected as it indicates the level of support
+ provided by the server.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:supported-address-data property is used to
+ specify the media type supported for the address object resources
+ contained in a given address book collection (e.g., vCard version
+
+
+
+Daboo Standards Track [Page 11]
+
+RFC 6352 CardDAV August 2011
+
+
+ 3.0). Any attempt by the client to store address object resources
+ with a media type not listed in this property MUST result in an
+ error, with the CARDDAV:supported-address-data precondition
+ (Section 6.3.2.1) being violated. In the absence of this
+ property, the server MUST only accept data with the media type
+ "text/vcard" and vCard version 3.0, and clients can assume that is
+ all the server will accept.
+
+ Definition:
+
+ <!ELEMENT supported-address-data (address-data-type+)>
+
+ <!ELEMENT address-data-type EMPTY>
+ <!ATTLIST address-data-type content-type CDATA "text/vcard"
+ version CDATA "3.0">
+ <!-- content-type value: a MIME media type -->
+ <!-- version value: a version string -->
+
+ Example:
+
+ <C:supported-address-data
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <C:address-data-type content-type="text/vcard" version="3.0"/>
+ </C:supported-address-data>
+
+6.2.3. CARDDAV:max-resource-size Property
+
+ Name: max-resource-size
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Provides a numeric value indicating the maximum size in
+ octets of a resource that the server is willing to accept when an
+ address object resource is stored in an address book collection.
+
+ Value: Any text representing a numeric value.
+
+ Protected: MUST be protected as it indicates limits provided by the
+ server.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+
+
+
+
+
+Daboo Standards Track [Page 12]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:max-resource-size is used to specify a
+ numeric value that represents the maximum size in octets that the
+ server is willing to accept when an address object resource is
+ stored in an address book collection. Any attempt to store an
+ address book object resource exceeding this size MUST result in an
+ error, with the CARDDAV:max-resource-size precondition
+ (Section 6.3.2.1) being violated. In the absence of this
+ property, the client can assume that the server will allow storing
+ a resource of any reasonable size.
+
+ Definition:
+
+ <!ELEMENT max-resource-size (#PCDATA)>
+ <!-- PCDATA value: a numeric value (positive decimal integer) -->
+
+ Example:
+
+ <C:max-resource-size xmlns:C="urn:ietf:params:xml:ns:carddav"
+ >102400</C:max-resource-size>
+
+6.3. Creating Resources
+
+ Address book collections and address object resources may be created
+ by either a CardDAV client or the CardDAV server. This specification
+ defines restrictions and a data model that both clients and servers
+ MUST adhere to when manipulating such address data.
+
+6.3.1. Extended MKCOL Method
+
+ An HTTP request using the extended MKCOL method [RFC5689] can be used
+ to create a new address book collection resource. A server MAY
+ restrict address book collection creation to particular collections.
+
+ To create an address book, the client sends an extended MKCOL request
+ to the server and in the body of the request sets the
+ DAV:resourcetype property to the resource type for an address book
+ collection as defined in Section 5.2.
+
+ Support for creating address books on the server is only RECOMMENDED
+ and not REQUIRED because some address book stores only support one
+ address book per user (or principal), and those are typically pre-
+ created for each account. However, servers and clients are strongly
+ encouraged to support address book creation whenever possible to
+ allow users to create multiple address book collections to help
+ organize their data better.
+
+
+
+
+
+
+Daboo Standards Track [Page 13]
+
+RFC 6352 CardDAV August 2011
+
+
+ The DAV:displayname property can be used for a human-readable name of
+ the address book. Clients can either specify the value of the
+ DAV:displayname property in the request body of the extended MKCOL
+ request or, alternatively, issue a PROPPATCH request to change the
+ DAV:displayname property to the appropriate value immediately after
+ using the extended MKCOL request. When displaying address book
+ collections to users, clients SHOULD check the DAV:displayname
+ property and use that value as the name of the address book. In the
+ event that the DAV:displayname property is not set, the client MAY
+ use the last part of the address book collection URI as the name;
+ however, that path segment may be "opaque" and not represent any
+ meaningful human-readable text.
+
+6.3.1.1. Example - Successful MKCOL Request
+
+ This example creates an address book collection called /home/lisa/
+ addressbook/ on the server addressbook.example.com with specific
+ values for the properties DAV:resourcetype, DAV:displayname, and
+ CARDDAV:addressbook-description.
+
+ >> Request <<
+
+ MKCOL /home/lisa/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:mkcol xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:set>
+ <D:prop>
+ <D:resourcetype>
+ <D:collection/>
+ <C:addressbook/>
+ </D:resourcetype>
+ <D:displayname>Lisa's Contacts</D:displayname>
+ <C:addressbook-description xml:lang="en"
+ >My primary address book.</C:addressbook-description>
+ </D:prop>
+ </D:set>
+ </D:mkcol>
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 14]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Response <<
+
+ HTTP/1.1 201 Created
+ Cache-Control: no-cache
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:mkcol-response xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:propstat>
+ <D:prop>
+ <D:resourcetype/>
+ <D:displayname/>
+ <C:addressbook-description/>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:mkcol-response>
+
+6.3.2. Creating Address Object Resources
+
+ Clients populate address book collections with address object
+ resources. The URL for each address object resource is entirely
+ arbitrary and does not need to bear a specific relationship (but
+ might) to the address object resource's vCard properties or other
+ metadata. New address object resources MUST be created with a PUT
+ request targeted at an unmapped URI. A PUT request targeted at a
+ mapped URI updates an existing address object resource.
+
+ When servers create new resources, it's not hard for the server to
+ choose a unique URL. It's slightly tougher for clients, because a
+ client might not want to examine all resources in the collection and
+ might not want to lock the entire collection to ensure that a new one
+ isn't created with a name collision. However, there is an HTTP
+ feature to mitigate this. If the client intends to create a new
+ address resource, the client SHOULD use the HTTP header "If-None-
+ Match: *" on the PUT request. The Request-URI on the PUT request
+ MUST include the target collection, where the resource is to be
+ created, plus the name of the resource in the last path segment. The
+ "If-None-Match" header ensures that the client will not inadvertently
+ overwrite an existing resource even if the last path segment turned
+ out to already be used.
+
+
+
+
+
+
+
+Daboo Standards Track [Page 15]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Request <<
+
+ PUT /lisa/addressbook/newvcard.vcf HTTP/1.1
+ If-None-Match: *
+ Host: addressbook.example.com
+ Content-Type: text/vcard
+ Content-Length: xxx
+
+ BEGIN:VCARD
+ VERSION:3.0
+ FN:Cyrus Daboo
+ N:Daboo;Cyrus
+ ADR;TYPE=POSTAL:;2822 Email HQ;Suite 2821;RFCVille;PA;15213;USA
+ EMAIL;TYPE=INTERNET,PREF:cyrus@example.com
+ NICKNAME:me
+ NOTE:Example VCard.
+ ORG:Self Employed
+ TEL;TYPE=WORK,VOICE:412 605 0499
+ TEL;TYPE=FAX:412 605 0705
+ URL:http://www.example.com
+ UID:1234-5678-9000-1
+ END:VCARD
+
+ >> Response <<
+
+ HTTP/1.1 201 Created
+ Date: Thu, 02 Sep 2004 16:53:32 GMT
+ Content-Length: 0
+ ETag: "123456789-000-111"
+
+ The request to change an existing address object resource without
+ overwriting a change made on the server uses a specific ETag in an
+ "If-Match" header, rather than the "If-None-Match" header.
+
+ File names for vCards are commonly suffixed by ".vcf", and clients
+ may choose to use the same convention for URLs.
+
+6.3.2.1. Additional Preconditions for PUT, COPY, and MOVE
+
+ This specification creates additional preconditions for the PUT,
+ COPY, and MOVE methods. These preconditions apply:
+
+ o When a PUT operation of an address object resource into an address
+ book collection occurs.
+
+ o When a COPY or MOVE operation of an address object resource into
+ an address book collection occurs.
+
+
+
+
+Daboo Standards Track [Page 16]
+
+RFC 6352 CardDAV August 2011
+
+
+ The new preconditions are:
+
+ (CARDDAV:supported-address-data): The resource submitted in the
+ PUT request, or targeted by a COPY or MOVE request, MUST be a
+ supported media type (i.e., vCard) for address object resources.
+
+ (CARDDAV:valid-address-data): The resource submitted in the PUT
+ request, or targeted by a COPY or MOVE request, MUST be valid data
+ for the media type being specified (i.e., MUST contain valid vCard
+ data).
+
+ (CARDDAV:no-uid-conflict): The resource submitted in the PUT
+ request, or targeted by a COPY or MOVE request, MUST NOT specify a
+ vCard UID property value already in use in the targeted address
+ book collection or overwrite an existing address object resource
+ with one that has a different UID property value. Servers SHOULD
+ report the URL of the resource that is already making use of the
+ same UID property value in the DAV:href element.
+
+ <!ELEMENT no-uid-conflict (DAV:href)>
+
+ (CARDDAV:addressbook-collection-location-ok): In a COPY or MOVE
+ request, when the Request-URI is an address book collection, the
+ URI targeted by the Destination HTTP Request header MUST identify
+ a location where an address book collection can be created.
+
+ (CARDDAV:max-resource-size): The resource submitted in the PUT
+ request, or targeted by a COPY or MOVE request, MUST have a size
+ in octets less than or equal to the value of the
+ CARDDAV:max-resource-size property value (Section 6.2.3) on the
+ address book collection where the resource will be stored.
+
+6.3.2.2. Non-Standard vCard Properties and Parameters
+
+ vCard provides a "standard mechanism for doing non-standard things".
+ This extension support allows implementers to make use of non-
+ standard vCard properties and parameters whose names are prefixed
+ with the text "X-".
+
+ Servers MUST support the use of non-standard properties and
+ parameters in address object resources stored via the PUT method.
+
+ Servers may need to enforce rules for their own "private" properties
+ or parameters, so servers MAY reject any attempt by the client to
+ change those or use values for those outside of any restrictions the
+ server may have. A server SHOULD ensure that any "private"
+
+
+
+
+
+Daboo Standards Track [Page 17]
+
+RFC 6352 CardDAV August 2011
+
+
+ properties or parameters it uses follow the convention of including a
+ vendor ID in the "X-" name, as described in Section 3.8 of [RFC2426],
+ e.g., "X-ABC-PRIVATE".
+
+6.3.2.3. Address Object Resource Entity Tag
+
+ The DAV:getetag property MUST be defined and set to a strong entity
+ tag on all address object resources.
+
+ A response to a GET request targeted at an address object resource
+ MUST contain an ETag response header field indicating the current
+ value of the strong entity tag of the address object resource.
+
+ Servers SHOULD return a strong entity tag (ETag header) in a PUT
+ response when the stored address object resource is equivalent by
+ octet equality to the address object resource submitted in the body
+ of the PUT request. This allows clients to reliably use the returned
+ strong entity tag for data synchronization purposes. For instance,
+ the client can do a PROPFIND request on the stored address object
+ resource, have the DAV:getetag property returned, compare that value
+ with the strong entity tag it received on the PUT response, and know
+ that if they are equal, then the address object resource on the
+ server has not been changed.
+
+ In the case where the data stored by a server as a result of a PUT
+ request is not equivalent by octet equality to the submitted address
+ object resource, the behavior of the ETag response header is not
+ specified here, with the exception that a strong entity tag MUST NOT
+ be returned in the response. As a result, a client may need to
+ retrieve the modified address object resource (and ETag) as a basis
+ for further changes, rather than use the address object resource it
+ had sent with the PUT request.
+
+7. Address Book Access Control
+
+ CardDAV servers MUST support and adhere to the requirements of WebDAV
+ ACL [RFC3744]. WebDAV ACL provides a framework for an extensible set
+ of privileges that can be applied to WebDAV collections and ordinary
+ resources.
+
+7.1. Additional Principal Properties
+
+ This section defines additional properties for WebDAV principal
+ resources as defined in [RFC3744].
+
+
+
+
+
+
+
+Daboo Standards Track [Page 18]
+
+RFC 6352 CardDAV August 2011
+
+
+7.1.1. CARDDAV:addressbook-home-set Property
+
+ Name: addressbook-home-set
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies the URL of any WebDAV collections that contain
+ address book collections owned by the associated principal
+ resource.
+
+ Protected: MAY be protected if the server has fixed locations in
+ which address books are created.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:addressbook-home-set property is meant to
+ allow users to easily find the address book collections owned by
+ the principal. Typically, users will group all the address book
+ collections that they own under a common collection. This
+ property specifies the URL of collections that are either address
+ book collections or ordinary collections that have child or
+ descendant address book collections owned by the principal.
+
+ Definition:
+
+ <!ELEMENT addressbook-home-set (DAV:href*)>
+
+ Example:
+
+ <C:addressbook-home-set xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:href>/bernard/addresses/</D:href>
+ </C:addressbook-home-set>
+
+7.1.2. CARDDAV:principal-address Property
+
+ Name: principal-address
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies the URL of an address object resource that
+ corresponds to the user represented by the principal.
+
+
+
+
+
+Daboo Standards Track [Page 19]
+
+RFC 6352 CardDAV August 2011
+
+
+ Protected: MAY be protected if the server provides a fixed location
+ for principal addresses.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:principal-address property is meant to
+ allow users to easily find contact information for users
+ represented by principals on the system. This property specifies
+ the URL of the resource containing the corresponding contact
+ information. The resource could be an address object resource in
+ an address book collection, or it could be a resource in a
+ "regular" collection.
+
+ Definition:
+
+ <!ELEMENT principal-address (DAV:href)>
+
+ Example:
+
+ <C:principal-address xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:href>/system/cyrus.vcf</D:href>
+ </C:principal-address>
+
+8. Address Book Reports
+
+ This section defines the reports that CardDAV servers MUST support on
+ address book collections and address object resources.
+
+ CardDAV servers MUST advertise support for these reports on all
+ address book collections and address object resources with the
+ DAV:supported-report-set property defined in Section 3.1.5 of
+ [RFC3253]. CardDAV servers MAY also advertise support for these
+ reports on ordinary collections.
+
+ Some of these reports allow address data (from possibly multiple
+ resources) to be returned.
+
+8.1. REPORT Method
+
+ The REPORT method (defined in Section 3.6 of [RFC3253]) provides an
+ extensible mechanism for obtaining information about a resource.
+ Unlike the PROPFIND method, which returns the value of one or more
+ named properties, the REPORT method can involve more complex
+
+
+
+Daboo Standards Track [Page 20]
+
+RFC 6352 CardDAV August 2011
+
+
+ processing. REPORT is valuable in cases where the server has access
+ to all of the information needed to perform the complex request (such
+ as a query), and where it would require multiple requests for the
+ client to retrieve the information needed to perform the same
+ request.
+
+ A server that supports this specification MUST support the
+ DAV:expand-property report (defined in Section 3.8 of [RFC3253]).
+
+8.2. Ordinary Collections
+
+ Servers MAY support the reports defined in this document on ordinary
+ collections (collections that are not address book collections) in
+ addition to address book collections or address object resources. In
+ computing responses to the reports on ordinary collections, servers
+ MUST only consider address object resources contained in address book
+ collections that are targeted by the REPORT based on the value of the
+ Depth request header.
+
+8.3. Searching Text: Collations
+
+ Some of the reports defined in this section do text matches of
+ character strings provided by the client and compared to stored
+ address data. Since vCard data is by default encoded in the UTF-8
+ charset and may include characters outside of the US-ASCII charset
+ range in some property and parameter values, there is a need to
+ ensure that text matching follows well-defined rules.
+
+ To deal with this, this specification makes use of the IANA Collation
+ Registry defined in [RFC4790] to specify collations that may be used
+ to carry out the text comparison operations with a well-defined rule.
+
+ Collations supported by the server MUST support "equality" and
+ "substring" match operations as per [RFC4790], Section 4.2, including
+ the "prefix" and "suffix" options for "substring" matching. CardDAV
+ uses these match options for "equals", "contains", "starts-with", and
+ "ends-with" match operations.
+
+ CardDAV servers are REQUIRED to support the "i;ascii-casemap"
+ [RFC4790] and "i;unicode-casemap" [RFC5051] collations and MAY
+ support other collations.
+
+ Servers MUST advertise the set of collations that they support via
+ the CARDDAV:supported-collation-set property defined on any resource
+ that supports reports that use collations.
+
+
+
+
+
+
+Daboo Standards Track [Page 21]
+
+RFC 6352 CardDAV August 2011
+
+
+ In the absence of a collation explicitly specified by the client, or
+ if the client specifies the "default" collation identifier (as
+ defined in [RFC4790], Section 3.1), the server MUST default to using
+ "i;unicode-casemap" as the collation.
+
+ Wildcards (as defined in [RFC4790], Section 3.2) MUST NOT be used in
+ the collation identifier.
+
+ If the client chooses a collation not supported by the server, the
+ server MUST respond with a CARDDAV:supported-collation precondition
+ error response.
+
+8.3.1. CARDDAV:supported-collation-set Property
+
+ Name: supported-collation-set
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies the set of collations supported by the server
+ for text matching operations.
+
+ Protected: MUST be protected as it indicates support provided by the
+ server.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:supported-collation-set property contains
+ two or more CARDDAV:supported-collation elements that specify the
+ identifiers of the collations supported by the server.
+
+ Definition:
+
+ <!ELEMENT supported-collation-set (
+ supported-collation
+ supported-collation
+ supported-collation*)>
+ <!-- Both "i;ascii-casemap" and "i;unicode-casemap"
+ will be present -->
+
+ <!ELEMENT supported-collation (#PCDATA)>
+
+
+
+
+
+
+
+Daboo Standards Track [Page 22]
+
+RFC 6352 CardDAV August 2011
+
+
+ Example:
+
+ <C:supported-collation-set
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <C:supported-collation>i;ascii-casemap</C:supported-collation>
+ <C:supported-collation>i;octet</C:supported-collation>
+ <C:supported-collation>i;unicode-casemap</C:supported-collation>
+ </C:supported-collation-set>
+
+8.4. Partial Retrieval
+
+ Some address book reports defined in this document allow partial
+ retrieval of address object resources. A CardDAV client can specify
+ what information to return in the body of an address book REPORT
+ request.
+
+ A CardDAV client can request particular WebDAV property values, all
+ WebDAV property values, or a list of the names of the resource's
+ WebDAV properties. A CardDAV client can also request address data to
+ be returned and whether all vCard properties should be returned or
+ only particular ones. See CARDDAV:address-data in Section 10.4.
+
+8.5. Non-Standard Properties and Parameters
+
+ Servers MUST support the use of non-standard vCard property or
+ parameter names in the CARDDAV:address-data XML element in address
+ book REPORT requests to allow clients to request that non-standard
+ properties and parameters be returned in the address data provided in
+ the response.
+
+ Servers MAY support the use of non-standard vCard property or
+ parameter names in the CARDDAV:prop-filter and CARDDAV:param-filter
+ XML elements specified in the CARDDAV:filter XML element of address
+ book REPORT requests.
+
+ Servers MUST fail with the CARDDAV:supported-filter precondition if
+ an address book REPORT request uses a CARDDAV:prop-filter or
+ CARDDAV:param-filter XML element that makes reference to a non-
+ standard vCard property or parameter name on which the server does
+ not support queries.
+
+8.6. CARDDAV:addressbook-query Report
+
+ The CARDDAV:addressbook-query REPORT performs a search for all
+ address object resources that match a specified filter. The response
+ of this report will contain all the WebDAV properties and address
+ object resource data specified in the request. In the case of the
+
+
+
+
+Daboo Standards Track [Page 23]
+
+RFC 6352 CardDAV August 2011
+
+
+ CARDDAV:address-data XML element, one can explicitly specify the
+ vCard properties that should be returned in the address object
+ resource data that matches the filter.
+
+ The format of this report is modeled on the PROPFIND method. The
+ request and response bodies of the CARDDAV:addressbook-query report
+ use XML elements that are also used by PROPFIND. In particular, the
+ request can include XML elements to request WebDAV properties to be
+ returned. When that occurs, the response should follow the same
+ behavior as PROPFIND with respect to the DAV:multistatus response
+ elements used to return specific WebDAV property results. For
+ instance, a request to retrieve the value of a WebDAV property that
+ does not exist is an error and MUST be noted with a response XML
+ element that contains a 404 (Not Found) status value.
+
+ Support for the CARDDAV:addressbook-query REPORT is REQUIRED.
+
+ Marshalling:
+
+ The request body MUST be a CARDDAV:addressbook-query XML element
+ as defined in Section 10.3.
+
+ The request MUST include a Depth header. The scope of the query
+ is determined by the value of the Depth header. For example, to
+ query all address object resources in an address book collection,
+ the REPORT would use the address book collection as the Request-
+ URI and specify a Depth of 1 or infinity.
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element (i.e., the response uses the same
+ format as the response for PROPFIND). In the case where there are
+ no response elements, the returned DAV:multistatus XML element is
+ empty.
+
+ The response body for a successful CARDDAV:addressbook-query
+ REPORT request MUST contain a DAV:response element for each
+ address object that matched the search filter. Address data is
+ returned in the CARDDAV:address-data XML element inside the
+ DAV:propstat XML element.
+
+ Preconditions:
+
+ (CARDDAV:supported-address-data): The attributes "content-type"
+ and "version" of the CARDDAV:address-data XML element (see
+ Section 10.4) specify a media type supported by the server for
+ address object resources.
+
+
+
+
+
+Daboo Standards Track [Page 24]
+
+RFC 6352 CardDAV August 2011
+
+
+ (CARDDAV:supported-filter): The CARDDAV:prop-filter (see
+ Section 10.5.1) and CARDDAV:param-filter (see Section 10.5.2) XML
+ elements used in the CARDDAV:filter XML element (see Section 10.5)
+ in the REPORT request only make reference to vCard properties and
+ parameters for which queries are supported by the server. That
+ is, if the CARDDAV:filter element attempts to reference an
+ unsupported vCard property or parameter, this precondition is
+ violated. A server SHOULD report the CARDDAV:prop-filter or
+ CARDDAV:param-filter for which it does not provide support.
+
+ <!ELEMENT supported-filter (prop-filter*,
+ param-filter*)>
+
+ (CARDDAV:supported-collation): Any XML attribute specifying a
+ collation MUST specify a collation supported by the server as
+ described in Section 8.3.
+
+ Postconditions:
+
+ (DAV:number-of-matches-within-limits): The number of matching
+ address object resources must fall within server-specific,
+ predefined limits. For example, this condition might be triggered
+ if a search specification would cause the return of an extremely
+ large number of responses.
+
+8.6.1. Limiting Results
+
+ A client can limit the number of results returned by the server
+ through use of the CARDDAV:limit element in the request body. This
+ is useful when clients are only interested in a few matches or only
+ have limited space to display results to users and thus don't need
+ the overhead of receiving more than that. When the results are
+ truncated by the server, the server MUST follow the rules below for
+ indicating a result set truncation to the client.
+
+8.6.2. Truncation of Results
+
+ A server MAY limit the number of resources in a response, for
+ example, to limit the amount of work expended in processing a query,
+ or as the result of an explicit limit set by the client. If the
+ result set is truncated because of such a limit, the response MUST
+ use status code 207 (Multi-Status), return a DAV:multistatus response
+ body, and indicate a status of 507 (Insufficient Storage) for the
+ Request-URI. That DAV:response element SHOULD include a DAV:error
+ element with the DAV:number-of-matches-within-limits precondition, as
+ defined in [RFC3744], Section 9.2.
+
+
+
+
+
+Daboo Standards Track [Page 25]
+
+RFC 6352 CardDAV August 2011
+
+
+ The server SHOULD also include the partial results in additional
+ DAV:response elements. If a client-requested limit is being applied,
+ the 507 response for the Request-URI MUST NOT be included in
+ calculating the limit (e.g., if the client requests that only a
+ single result be returned, and multiple matches are present, then the
+ DAV:multistatus response will include one DAV:response for the
+ matching resource and one DAV:response for the 507 status on the
+ Request-URI).
+
+8.6.3. Example: Partial Retrieval of vCards Matching NICKNAME
+
+ In this example, the client requests that the server search for
+ address object resources that contain a NICKNAME property whose value
+ equals some specific text and return specific vCard properties for
+ those vCards found. In addition, the DAV:getetag property is also
+ requested and returned as part of the response.
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-query xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:prop>
+ <D:getetag/>
+ <C:address-data>
+ <C:prop name="VERSION"/>
+ <C:prop name="UID"/>
+ <C:prop name="NICKNAME"/>
+ <C:prop name="EMAIL"/>
+ <C:prop name="FN"/>
+ </C:address-data>
+ </D:prop>
+ <C:filter>
+ <C:prop-filter name="NICKNAME">
+ <C:text-match collation="i;unicode-casemap"
+ match-type="equals"
+ >me</C:text-match>
+ </C:prop-filter>
+ </C:filter>
+ </C:addressbook-query>
+
+
+
+
+
+Daboo Standards Track [Page 26]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/v102.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fb"</D:getetag>
+ <C:address-data>BEGIN:VCARD
+ VERSION:3.0
+ NICKNAME:me
+ UID:34222-232@example.com
+ FN:Cyrus Daboo
+ EMAIL:daboo@example.com
+ END:VCARD
+ </C:address-data>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+8.6.4. Example: Partial Retrieval of vCards Matching a Full Name or
+ Email Address
+
+ In this example, the client requests that the server search for
+ address object resources that contain a FN property whose value
+ contains some specific text or that contain an EMAIL property whose
+ value contains other text and return specific vCard properties for
+ those vCards found. In addition, the DAV:getetag property is also
+ requested and returned as part of the response.
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+
+
+
+
+Daboo Standards Track [Page 27]
+
+RFC 6352 CardDAV August 2011
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-query xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:prop>
+ <D:getetag/>
+ <C:address-data>
+ <C:prop name="VERSION"/>
+ <C:prop name="UID"/>
+ <C:prop name="NICKNAME"/>
+ <C:prop name="EMAIL"/>
+ <C:prop name="FN"/>
+ </C:address-data>
+ </D:prop>
+ <C:filter test="anyof">
+ <C:prop-filter name="FN">
+ <C:text-match collation="i;unicode-casemap"
+ match-type="contains"
+ >daboo</C:text-match>
+ </C:prop-filter>
+ <C:prop-filter name="EMAIL">
+ <C:text-match collation="i;unicode-casemap"
+ match-type="contains"
+ >daboo</C:text-match>
+ </C:prop-filter>
+ </C:filter>
+ </C:addressbook-query>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/v102.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fb"</D:getetag>
+ <C:address-data>BEGIN:VCARD
+ VERSION:3.0
+ NICKNAME:me
+ UID:34222-232@example.com
+ FN:David Boo
+ EMAIL:daboo@example.com
+
+
+
+Daboo Standards Track [Page 28]
+
+RFC 6352 CardDAV August 2011
+
+
+ END:VCARD
+ </C:address-data>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/bernard/addressbook/v104.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fc"</D:getetag>
+ <C:address-data>BEGIN:VCARD
+ VERSION:3.0
+ NICKNAME:oliver
+ UID:34222-23222@example.com
+ FN:Oliver Daboo
+ EMAIL:oliver@example.com
+ END:VCARD
+ </C:address-data>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+8.6.5. Example: Truncated Results
+
+ In this example, the client requests that the server search for
+ address object resources that contain a FN property whose value
+ contains some specific text and return the DAV:getetag property for
+ two results only. The server response includes a 507 status for the
+ Request-URI indicating that there were more than two resources that
+ matched the query, but that the server truncated the result set as
+ requested by the client.
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-query xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+
+
+
+
+
+Daboo Standards Track [Page 29]
+
+RFC 6352 CardDAV August 2011
+
+
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ <C:filter test="anyof">
+ <C:prop-filter name="FN">
+ <C:text-match collation="i;unicode-casemap"
+ match-type="contains"
+ >daboo</C:text-match>
+ </C:prop-filter>
+ </C:filter>
+ <C:limit>
+ <C:nresults>2</C:nresults>
+ </C:limit>
+ </C:addressbook-query>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/</D:href>
+ <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
+ <D:error><D:number-of-matches-within-limits/></D:error>
+ <D:responsedescription xml:lang="en">
+ Only two matching records were returned
+ </D:responsedescription>
+ </D:response>
+ <D:response>
+ <D:href>/home/bernard/addressbook/v102.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fb"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/bernard/addressbook/v104.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fc"</D:getetag>
+ </D:prop>
+
+
+
+Daboo Standards Track [Page 30]
+
+RFC 6352 CardDAV August 2011
+
+
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+8.7. CARDDAV:addressbook-multiget Report
+
+ The CARDDAV:addressbook-multiget REPORT is used to retrieve specific
+ address object resources from within a collection, if the Request-URI
+ is a collection, or to retrieve a specific address object resource,
+ if the Request-URI is an address object resource. This report is
+ similar to the CARDDAV:addressbook-query REPORT (see Section 8.6),
+ except that it takes a list of DAV:href elements instead of a
+ CARDDAV:filter element to determine which address object resources to
+ return.
+
+ Support for the addressbook-multiget REPORT is REQUIRED.
+
+ Marshalling:
+
+ The request body MUST be a CARDDAV:addressbook-multiget XML
+ element (see Section 10.7), which MUST contain at least one
+ DAV:href XML element and one optional CARDDAV:address-data element
+ as defined in Section 10.4. If DAV:href elements are present, the
+ scope of the request is the set of resources identified by these
+ elements, which all need to be members (not necessarily internal
+ members) of the resource identified by the Request-URI.
+ Otherwise, the scope is the resource identified by the Request-URI
+ itself.
+
+ The request MUST include a Depth: 0 header; however, the actual
+ scope of the REPORT is determined as described above.
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element.
+
+ The response body for a successful CARDDAV:addressbook-multiget
+ REPORT request MUST contain a DAV:response element for each
+ address object resource referenced by the provided set of DAV:href
+ elements. Address data is returned in the CARDDAV:address-data
+ element inside the DAV:prop element.
+
+ In the case of an error accessing any of the provided DAV:href
+ resources, the server MUST return the appropriate error status
+ code in the DAV:status element of the corresponding DAV:response
+ element.
+
+
+
+
+
+Daboo Standards Track [Page 31]
+
+RFC 6352 CardDAV August 2011
+
+
+ Preconditions:
+
+ (CARDDAV:supported-address-data): The attributes "content-type"
+ and "version" of the CARDDAV:address-data XML elements (see
+ Section 10.4) specify a media type supported by the server for
+ address object resources.
+
+ Postconditions:
+
+ None.
+
+8.7.1. Example: CARDDAV:addressbook-multiget Report
+
+ In this example, the client requests the server to return specific
+ vCard properties of the address components referenced by specific
+ URIs. In addition, the DAV:getetag property is also requested and
+ returned as part of the response. Note that, in this example, the
+ resource at
+ http://addressbook.example.com/home/bernard/addressbook/vcf1.vcf does
+ not exist, resulting in an error status response.
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-multiget xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:prop>
+ <D:getetag/>
+ <C:address-data>
+ <C:prop name="VERSION"/>
+ <C:prop name="UID"/>
+ <C:prop name="NICKNAME"/>
+ <C:prop name="EMAIL"/>
+ <C:prop name="FN"/>
+ </C:address-data>
+ </D:prop>
+ <D:href>/home/bernard/addressbook/vcf102.vcf</D:href>
+ <D:href>/home/bernard/addressbook/vcf1.vcf</D:href>
+ </C:addressbook-multiget>
+
+
+
+
+
+
+Daboo Standards Track [Page 32]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/vcf102.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fb"</D:getetag>
+ <C:address-data>BEGIN:VCARD
+ VERSION:3.0
+ NICKNAME:me
+ UID:34222-232@example.com
+ FN:Cyrus Daboo
+ EMAIL:daboo@example.com
+ END:VCARD
+ </C:address-data>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/bernard/addressbook/vcf1.vcf</D:href>
+ <D:status>HTTP/1.1 404 Resource not found</D:status>
+ </D:response>
+ </D:multistatus>
+
+8.7.2. Example: CARDDAV:addressbook-multiget Report
+
+ In this example, the client requests the server to return vCard v4.0
+ data of the address components referenced by specific URIs. In
+ addition, the DAV:getetag property is also requested and returned as
+ part of the response. Note that, in this example, the resource at
+ http://addressbook.example.com/home/bernard/addressbook/vcf3.vcf
+ exists but in a media type format that the server is unable to
+ convert, resulting in an error status response.
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 33]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-multiget xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:prop>
+ <D:getetag/>
+ <C:address-data content-type='text/vcard' version='4.0'/>
+ </D:prop>
+ <D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
+ </C:addressbook-multiget>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
+ <D:status>HTTP/1.1 415 Unsupported Media Type</D:status>
+ <D:error><C:supported-address-data-conversion/></D:error>
+ <D:responsedescription>Unable to convert from vCard v3.0
+ to vCard v4.0</D:responsedescription>
+ </D:response>
+ </D:multistatus>
+
+9. Client Guidelines
+
+9.1. Restrict the Properties Returned
+
+ Clients may not need all the properties in a vCard object when
+ presenting information to the user, or looking up specific items for
+ their email address, for example. Since some property data can be
+ large (e.g., PHOTO or SOUND with in-line content) clients can choose
+ to ignore those by only requesting the specific items it knows it
+ will use, through use of the CARDDAV:address-data XML element in the
+ relevant reports.
+
+
+
+Daboo Standards Track [Page 34]
+
+RFC 6352 CardDAV August 2011
+
+
+ However, if a client needs to make a change to a vCard, it can only
+ change the entire vCard data via a PUT request. There is no way to
+ incrementally make a change to a set of properties within a vCard
+ object resource. As a result, the client will have to cache the
+ entire set of properties on a resource that is being changed.
+
+9.2. Avoiding Lost Updates
+
+ When resources are accessed by multiple clients, the possibility of
+ clients overwriting each other's changes exists. To alleviate this,
+ clients SHOULD use the If-Match request header on PUT requests with
+ the ETag of the previously retrieved resource data to check whether
+ the resource was modified since it was previously retrieved. If a
+ precondition failure occurs, clients need to reload the resource and
+ go through their own merge or conflict resolution process before
+ writing back the data (again using the If-Match check).
+
+9.3. Client Configuration
+
+ When CardDAV clients need to be configured, the key piece of
+ information that they require is the principal-URL of the user whose
+ address book information is desired. Servers SHOULD support the
+ DAV:current-user-principal-URL property as defined in [RFC5397] to
+ give clients a fast way to locate user principals.
+
+ Given support for SRV records (Section 11) and DAV:current-user-
+ principal-URL [RFC5397], users only need enter a user identifier,
+ host name, and password to configure their client. The client would
+ take the host name and do an SRV lookup to locate the CardDAV server,
+ then execute an authenticated PROPFIND on the root/resource looking
+ for the DAV:current-user-principal-URL property. The value returned
+ gives the client direct access to the user's principal-URL and from
+ there all the related CardDAV properties needed to locate address
+ books.
+
+9.4. Finding Other Users' Address Books
+
+ For use cases of address book sharing, one might wish to find the
+ address book belonging to another user. To find other users' address
+ books on the same server, the DAV:principal-property-search REPORT
+ [RFC3744] can be used to search principals for matching properties
+ and return specified properties for the matching principal resources.
+ To search for an address book owned by a user named "Laurie", the
+ REPORT request body would look like this:
+
+
+
+
+
+
+
+Daboo Standards Track [Page 35]
+
+RFC 6352 CardDAV August 2011
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:principal-property-search xmlns:D="DAV:">
+ <D:property-search>
+ <D:prop>
+ <D:displayname/>
+ </D:prop>
+ <D:match>Laurie</D:match>
+ </D:property-search>
+ <D:prop>
+ <C:addressbook-home-set
+ xmlns:C="urn:ietf:params:xml:ns:carddav"/>
+ <D:displayname/>
+ </D:prop>
+ </D:principal-property-search>
+
+ The server performs a case-sensitive or caseless search for a
+ matching string subset of "Laurie" within the DAV:displayname
+ property. Thus, the server might return "Laurie Dusseault", "Laurier
+ Desruisseaux", or "Wilfrid Laurier" all as matching DAV:displayname
+ values, and the address books for each of these.
+
+10. XML Element Definitions
+
+10.1. CARDDAV:addressbook XML Element
+
+ Name: addressbook
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies the resource type of an address book collection.
+
+ Description: See Section 5.2.
+
+ Definition:
+
+ <!ELEMENT addressbook EMPTY>
+
+10.2. CARDDAV:supported-collation XML Element
+
+ Name: supported-collation
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies a single collation via its collation identifier
+ as defined by [RFC4790].
+
+ Description: The CARDDAV:supported-collation contains the text of a
+ collation identifier as described in Section 8.3.1.
+
+
+
+Daboo Standards Track [Page 36]
+
+RFC 6352 CardDAV August 2011
+
+
+ Definition:
+
+ <!ELEMENT supported-collation (#PCDATA)>
+ <!-- PCDATA value: collation identifier -->
+
+10.3. CARDDAV:addressbook-query XML Element
+
+ Name: addressbook-query
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Defines a report for querying address book data
+
+ Description: See Section 8.6.
+
+ Definition:
+
+ <!ELEMENT addressbook-query ((DAV:allprop |
+ DAV:propname |
+ DAV:prop)?, filter, limit?)>
+
+10.4. CARDDAV:address-data XML Element
+
+ Name: address-data
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies one of the following:
+
+ 1. The parts of an address object resource that should be
+ returned by a given address book REPORT request, and the media
+ type and version for the returned data; or
+
+ 2. The content of an address object resource in a response to an
+ address book REPORT request.
+
+ Description: When used in an address book REPORT request, the
+ CARDDAV:address-data XML element specifies which parts of address
+ object resources need to be returned in the response. If the
+ CARDDAV:address-data XML element doesn't contain any CARDDAV:prop
+ elements, address object resources will be returned in their
+ entirety. Additionally, a media type and version can be specified
+ to request that the server return the data in that format if
+ possible.
+
+ Finally, when used in an address book REPORT response, the
+ CARDDAV:address-data XML element specifies the content of an
+ address object resource. Given that XML parsers normalize the
+
+
+
+Daboo Standards Track [Page 37]
+
+RFC 6352 CardDAV August 2011
+
+
+ two-character sequence CRLF (US-ASCII decimal 13 and US-ASCII
+ decimal 10) to a single LF character (US-ASCII decimal 10), the CR
+ character (US-ASCII decimal 13) MAY be omitted in address object
+ resources specified in the CARDDAV:address-data XML element.
+ Furthermore, address object resources specified in the
+ CARDDAV:address-data XML element MAY be invalid per their media
+ type specification if the CARDDAV:address-data XML element part of
+ the address book REPORT request did not specify required vCard
+ properties (e.g., UID, etc.) or specified a CARDDAV:prop XML
+ element with the "novalue" attribute set to "yes".
+
+ Note: The CARDDAV:address-data XML element is specified in requests
+ and responses inside the DAV:prop XML element as if it were a
+ WebDAV property. However, the CARDDAV:address-data XML element is
+ not a WebDAV property and as such it is not returned in PROPFIND
+ responses nor used in PROPPATCH requests.
+
+ Note: The address data embedded within the CARDDAV:address-data XML
+ element MUST follow the standard XML character data encoding
+ rules, including use of <, >, & etc., entity encoding or
+ the use of a <![CDATA[ ... ]]> construct. In the latter case, the
+ vCard data cannot contain the character sequence "]]>", which is
+ the end delimiter for the CDATA section.
+
+ Definition:
+
+ <!ELEMENT address-data (allprop | prop*)>
+
+ when nested in the DAV:prop XML element in an address book
+ REPORT request to specify which parts of address object
+ resources should be returned in the response;
+
+ <!ELEMENT address-data (#PCDATA)>
+ <!-- PCDATA value: address data -->
+
+ when nested in the DAV:prop XML element in an address book
+ REPORT response to specify the content of a returned
+ address object resource.
+
+ <!ATTLIST address-data content-type CDATA "text/vcard"
+ version CDATA "3.0">
+ <!-- content-type value: a MIME media type -->
+ <!-- version value: a version string -->
+
+ attributes can be used on each variant of the
+ CALDAV:address-data XML element.
+
+
+
+
+
+Daboo Standards Track [Page 38]
+
+RFC 6352 CardDAV August 2011
+
+
+10.4.1. CARDDAV:allprop XML Element
+
+ Name: allprop
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies that all vCard properties shall be returned.
+
+ Description: This element can be used when the client wants all
+ vCard properties of components returned by a report.
+
+ Definition:
+
+ <!ELEMENT allprop EMPTY>
+
+ Note: The CARDDAV:allprop element defined here has the same name as
+ the DAV:allprop element defined in WebDAV. However, the
+ CARDDAV:allprop element defined here uses the
+ "urn:ietf:params:xml:ns:carddav" namespace, as opposed to the "DAV:"
+ namespace used for the DAV:allprop element defined in WebDAV.
+
+10.4.2. CARDDAV:prop XML Element
+
+ Name: prop
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Defines which vCard properties to return in the response.
+
+ Description: The "name" attribute specifies the name of the vCard
+ property to return (e.g., "NICKNAME"). The "novalue" attribute
+ can be used by clients to request that the actual value of the
+ property not be returned (if the "novalue" attribute is set to
+ "yes"). In that case, the server will return just the vCard
+ property name and any vCard parameters and a trailing ":" without
+ the subsequent value data.
+
+ vCard allows a "group" prefix to appear before a property name in
+ the vCard data. When the "name" attribute does not specify a
+ group prefix, it MUST match properties in the vCard data without a
+ group prefix or with any group prefix. When the "name" attribute
+ includes a group prefix, it MUST match properties that have
+ exactly the same group prefix and name. For example, a "name" set
+ to "TEL" will match "TEL", "X-ABC.TEL", and "X-ABC-1.TEL" vCard
+ properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL"
+ vCard property only; it will not match "TEL" or "X-ABC-1.TEL".
+
+
+
+
+
+Daboo Standards Track [Page 39]
+
+RFC 6352 CardDAV August 2011
+
+
+ Definition:
+
+ <!ELEMENT prop EMPTY>
+
+ <!ATTLIST prop name CDATA #REQUIRED
+ novalue (yes | no) "no">
+ <!-- name value: a vCard property name -->
+ <!-- novalue value: "yes" or "no" -->
+
+ Note: The CARDDAV:prop element defined here has the same name as the
+ DAV:prop element defined in WebDAV. However, the CARDDAV:prop
+ element defined here uses the "urn:ietf:params:xml:ns:carddav"
+ namespace, as opposed to the "DAV:" namespace used for the DAV:prop
+ element defined in WebDAV.
+
+10.5. CARDDAV:filter XML Element
+
+ Name: filter
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Determines which matching objects are returned.
+
+ Description: The "filter" element specifies the search filter used
+ to match address objects that should be returned by a report. The
+ "test" attribute specifies whether any (logical OR) or all
+ (logical AND) of the prop-filter tests need to match in order for
+ the overall filter to match.
+
+ Definition:
+
+ <!ELEMENT filter (prop-filter*)>
+
+ <!ATTLIST filter test (anyof | allof) "anyof">
+ <!-- test value:
+ anyof logical OR for prop-filter matches
+ allof logical AND for prop-filter matches -->
+
+10.5.1. CARDDAV:prop-filter XML Element
+
+ Name: prop-filter
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Limits the search to specific vCard properties.
+
+
+
+
+
+
+Daboo Standards Track [Page 40]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:prop-filter XML element specifies search
+ criteria on a specific vCard property (e.g., "NICKNAME"). An
+ address object is said to match a CARDDAV:prop-filter if:
+
+ * A vCard property of the type specified by the "name" attribute
+ exists, and the CARDDAV:prop-filter is empty, or it matches any
+ specified CARDDAV:text-match or CARDDAV:param-filter
+ conditions. The "test" attribute specifies whether any
+ (logical OR) or all (logical AND) of the text-filter and param-
+ filter tests need to match in order for the overall filter to
+ match.
+
+ or:
+
+ * A vCard property of the type specified by the "name" attribute
+ does not exist, and the CARDDAV:is-not-defined element is
+ specified.
+
+ vCard allows a "group" prefix to appear before a property name in
+ the vCard data. When the "name" attribute does not specify a
+ group prefix, it MUST match properties in the vCard data without a
+ group prefix or with any group prefix. When the "name" attribute
+ includes a group prefix, it MUST match properties that have
+ exactly the same group prefix and name. For example, a "name" set
+ to "TEL" will match "TEL", "X-ABC.TEL", "X-ABC-1.TEL" vCard
+ properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL"
+ vCard property only, it will not match "TEL" or "X-ABC-1.TEL".
+
+ Definition:
+
+ <!ELEMENT prop-filter (is-not-defined |
+ (text-match*, param-filter*))>
+
+ <!ATTLIST prop-filter name CDATA #REQUIRED
+ test (anyof | allof) "anyof">
+ <!-- name value: a vCard property name (e.g., "NICKNAME")
+ test value:
+ anyof logical OR for text-match/param-filter matches
+ allof logical AND for text-match/param-filter matches -->
+
+10.5.2. CARDDAV:param-filter XML Element
+
+ Name: param-filter
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Limits the search to specific parameter values.
+
+
+
+
+Daboo Standards Track [Page 41]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:param-filter XML element specifies search
+ criteria on a specific vCard property parameter (e.g., TYPE) in
+ the scope of a given CARDDAV:prop-filter. A vCard property is
+ said to match a CARDDAV:param-filter if:
+
+ * A parameter of the type specified by the "name" attribute
+ exists, and the CARDDAV:param-filter is empty, or it matches
+ the CARDDAV:text-match conditions if specified.
+
+ or:
+
+ * A parameter of the type specified by the "name" attribute does
+ not exist, and the CARDDAV:is-not-defined element is specified.
+
+ Definition:
+
+ <!ELEMENT param-filter (is-not-defined | text-match)?>
+
+ <!ATTLIST param-filter name CDATA #REQUIRED>
+ <!-- name value: a property parameter name (e.g., "TYPE") -->
+
+10.5.3. CARDDAV:is-not-defined XML Element
+
+ Name: is-not-defined
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies that a match should occur if the enclosing vCard
+ property or parameter does not exist.
+
+ Description: The CARDDAV:is-not-defined XML element specifies that a
+ match occurs if the enclosing vCard property or parameter value
+ specified in an address book REPORT request does not exist in the
+ address data being tested.
+
+ Definition:
+
+ <!ELEMENT is-not-defined EMPTY>
+
+10.5.4. CARDDAV:text-match XML Element
+
+ Name: text-match
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies a substring match on a vCard property or
+ parameter value.
+
+
+
+
+Daboo Standards Track [Page 42]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:text-match XML element specifies text used
+ for a substring match against the vCard property or parameter
+ value specified in an address book REPORT request.
+
+ The "collation" attribute is used to select the collation that the
+ server MUST use for character string matching. In the absence of
+ this attribute, the server MUST use the "i;unicode-casemap"
+ collation.
+
+ The "negate-condition" attribute is used to indicate that this
+ test returns a match if the text matches, when the attribute value
+ is set to "no", or return a match if the text does not match, if
+ the attribute value is set to "yes". For example, this can be
+ used to match components with a CATEGORIES property not set to
+ PERSON.
+
+ The "match-type" attribute is used to indicate the type of match
+ operation to use. Possible choices are:
+
+ "equals" - an exact match to the target string
+
+ "contains" - a substring match, matching anywhere within the
+ target string
+
+ "starts-with" - a substring match, matching only at the start
+ of the target string
+
+ "ends-with" - a substring match, matching only at the end of
+ the target string
+
+ Definition:
+
+ <!ELEMENT text-match (#PCDATA)>
+ <!-- PCDATA value: string -->
+
+ <!ATTLIST text-match
+ collation CDATA "i;unicode-casemap"
+ negate-condition (yes | no) "no"
+ match-type (equals|contains|starts-with|ends-with) "contains">
+
+10.6. CARDDAV:limit XML Element
+
+ Name: limit
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies different types of limits that can be applied to
+ the results returned by the server.
+
+
+
+Daboo Standards Track [Page 43]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:limit XML element can be used to specify
+ different types of limits that the client can request the server
+ to apply to the results returned by the server. Currently, only
+ the CARDDAV:nresults limit can be used; other types of limit could
+ be defined in the future.
+
+ Definition:
+
+ <!ELEMENT limit (nresults)>
+
+10.6.1. CARDDAV:nresults XML Element
+
+ Name: nresults
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies a limit on the number of results returned by the
+ server.
+
+ Description: The CARDDAV:nresults XML element contains a requested
+ maximum number of DAV:response elements to be returned in the
+ response body of a query. The server MAY disregard this limit.
+ The value of this element is an unsigned integer.
+
+ Definition:
+
+ <!ELEMENT nresults (#PCDATA)>
+ <!-- nresults value: unsigned integer, must be digits -->
+
+10.7. CARDDAV:addressbook-multiget XML Element
+
+ Name: addressbook-multiget
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: CardDAV report used to retrieve specific address objects
+ via their URIs.
+
+ Description: See Section 8.7.
+
+ Definition:
+
+ <!ELEMENT addressbook-multiget ((DAV:allprop |
+ DAV:propname |
+ DAV:prop)?,
+ DAV:href+)>
+
+
+
+
+
+Daboo Standards Track [Page 44]
+
+RFC 6352 CardDAV August 2011
+
+
+11. Service Discovery via SRV Records
+
+ [RFC2782] defines a DNS-based service discovery protocol that has
+ been widely adopted as a means of locating particular services within
+ a local area network and beyond, using SRV RRs.
+
+ This specification adds two service types for use with SRV records:
+
+ carddav: Identifies a CardDAV server that uses HTTP without TLS
+ [RFC2818].
+
+ carddavs: Identifies a CardDAV server that uses HTTP with TLS
+ [RFC2818].
+
+ Example: non-TLS service record
+
+ _carddav._tcp SRV 0 1 80 addressbook.example.com.
+
+ Example: TLS service
+
+ _carddavs._tcp SRV 0 1 443 addressbook.example.com.
+
+12. Internationalization Considerations
+
+ CardDAV allows internationalized strings to be stored and retrieved
+ for the description of address book collections (see Section 6.2.1).
+
+ The CARDDAV:addressbook-query REPORT (Section 8.6) includes a text
+ searching option controlled by the CARDDAV:text-match element and
+ details of character handling are covered in the description of that
+ element (see Section 10.5.4).
+
+13. Security Considerations
+
+ HTTP protocol transactions are sent in the clear over the network
+ unless protection from snooping is negotiated. This can be
+ accomplished by use of TLS as defined in [RFC2818]. In particular,
+ if HTTP Basic authentication [RFC2617] is available, the server MUST
+ allow TLS to be used at the same time, and it SHOULD prevent use of
+ Basic authentication when TLS is not in use. Clients SHOULD use TLS
+ whenever possible.
+
+ With the ACL extension [RFC3744] present, WebDAV allows control over
+ who can access (read or write) any resource on the WebDAV server. In
+ addition, WebDAV ACL provides for an "inheritance" mechanism, whereby
+ resources may inherit access privileges from other resources. Often,
+ the "other" resource is a parent collection of the resource itself.
+ Servers are able to support address books that are "private"
+
+
+
+Daboo Standards Track [Page 45]
+
+RFC 6352 CardDAV August 2011
+
+
+ (accessible only to the "owner"), "shared" (accessible to the owner
+ and other specified authenticated users), and "public" (accessible to
+ any authenticated or unauthenticated users). When provisioning
+ address books of a particular type, servers MUST ensure that the
+ correct privileges are applied on creation. In particular, private
+ and shared address books MUST NOT be accessible by unauthenticated
+ users (to prevent data from being automatically searched or indexed
+ by web "crawlers").
+
+ Clients SHOULD warn users in an appropriate fashion when they copy or
+ move address data from a private address book to a shared address
+ book or public address book. Clients SHOULD provide a clear
+ indication as to which address books are private, shared, or public.
+ Clients SHOULD provide an appropriate warning when changing access
+ privileges for a private or shared address book with data so as to
+ allow unauthenticated users access.
+
+ This specification currently relies on standard HTTP authentication
+ mechanisms for identifying users. These comprise Basic and Digest
+ authentication [RFC2617] as well as TLS [RFC2818] using client-side
+ certificates.
+
+14. IANA Consideration
+
+ This document uses a URN to describe a new XML namespace conforming
+ to the registry mechanism described in [RFC3688].
+
+14.1. Namespace Registration
+
+ Registration request for the carddav namespace:
+
+ URI: urn:ietf:params:xml:ns:carddav
+
+ Registrant Contact: The IESG <iesg@ietf.org>
+
+ XML: None - not applicable for namespace registrations.
+
+15. Acknowledgments
+
+ Thanks go to Lisa Dusseault and Bernard Desruisseaux for their work
+ on CalDAV, on which CardDAV is heavily based. The following
+ individuals contributed their ideas and support for writing this
+ specification: Mike Douglass, Stefan Eissing, Helge Hess, Arnaud
+ Quillaud, Julian Reschke, Elias Sinderson, Greg Stein, Wilfredo
+ Sanchez, and Simon Vaillancourt.
+
+
+
+
+
+
+Daboo Standards Track [Page 46]
+
+RFC 6352 CardDAV August 2011
+
+
+16. References
+
+16.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
+ RFC 2426, September 1998.
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+ Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
+ Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+ [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
+ Leach, P., Luotonen, A., and L. Stewart, "HTTP
+ Authentication: Basic and Digest Access Authentication",
+ RFC 2617, June 1999.
+
+ [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
+ specifying the location of services (DNS SRV)", RFC 2782,
+ February 2000.
+
+ [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
+
+ [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
+ Whitehead, "Versioning Extensions to WebDAV
+ (Web Distributed Authoring and Versioning)", RFC 3253,
+ March 2002.
+
+ [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
+ January 2004.
+
+ [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
+ Distributed Authoring and Versioning (WebDAV)
+ Access Control Protocol", RFC 3744, May 2004.
+
+ [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
+ Application Protocol Collation Registry", RFC 4790,
+ March 2007.
+
+ [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+
+ [RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation
+ Algorithm", RFC 5051, October 2007.
+
+
+
+
+
+Daboo Standards Track [Page 47]
+
+RFC 6352 CardDAV August 2011
+
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246, August 2008.
+
+ [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
+ Housley, R., and W. Polk, "Internet X.509 Public Key
+ Infrastructure Certificate and Certificate Revocation List
+ (CRL) Profile", RFC 5280, May 2008.
+
+ [RFC5397] Sanchez, W. and C. Daboo, "WebDAV Current Principal
+ Extension", RFC 5397, December 2008.
+
+ [RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring
+ and Versioning (WebDAV)", RFC 5689, September 2009.
+
+ [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
+ August 2011.
+
+ [W3C.REC-xml-20081126]
+ Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and
+ F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
+ Edition)", World Wide Web Consortium Recommendation REC-
+ xml-20081126, November 2008,
+ <http://www.w3.org/TR/2008/REC-xml-20081126>.
+
+16.2. Informative References
+
+ [IMSP] Myers, J., "IMSP - Internet Message Support Protocol",
+ Work in Progress, June 1995.
+
+ [RFC2244] Newman, C. and J. Myers, "ACAP -- Application
+ Configuration Access Protocol", RFC 2244, November 1997.
+
+ [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol
+ (LDAP): Technical Specification Road Map", RFC 4510,
+ June 2006.
+
+Author's Address
+
+ Cyrus Daboo
+ Apple, Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: cyrus@daboo.name
+ URI: http://www.apple.com/
+
+
+
+
+
+Daboo Standards Track [Page 48]
+
diff --git a/docs/rfcs/rfc6578.txt b/docs/rfcs/rfc6578.txt
new file mode 100644
index 0000000..c957ae6
--- /dev/null
+++ b/docs/rfcs/rfc6578.txt
@@ -0,0 +1,1627 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Daboo
+Request for Comments: 6578 Apple Inc.
+Category: Standards Track A. Quillaud
+ISSN: 2070-1721 Oracle
+ March 2012
+
+
+ Collection Synchronization
+ for Web Distributed Authoring and Versioning (WebDAV)
+
+Abstract
+
+ This specification defines an extension to Web Distributed Authoring
+ and Versioning (WebDAV) that allows efficient synchronization of the
+ contents of a WebDAV collection.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6578.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 1]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+Copyright Notice
+
+ Copyright (c) 2012 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+ This document may contain material from IETF Documents or IETF
+ Contributions published or made publicly available before November
+ 10, 2008. The person(s) controlling the copyright in some of this
+ material may not have granted the IETF Trust the right to allow
+ modifications of such material outside the IETF Standards Process.
+ Without obtaining an adequate license from the person(s) controlling
+ the copyright in such materials, this document may not be modified
+ outside the IETF Standards Process, and derivative works of it may
+ not be created outside the IETF Standards Process, except to format
+ it for publication as an RFC or to translate it into languages other
+ than English.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 2]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
+ 3. WebDAV Synchronization . . . . . . . . . . . . . . . . . . . . 5
+ 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.2. DAV:sync-collection Report . . . . . . . . . . . . . . . . 6
+ 3.3. Depth Behavior . . . . . . . . . . . . . . . . . . . . . . 8
+ 3.4. Types of Changes Reported on Initial Synchronization . . . 9
+ 3.5. Types of Changes Reported on Subsequent
+ Synchronizations . . . . . . . . . . . . . . . . . . . . . 10
+ 3.5.1. Changed Member . . . . . . . . . . . . . . . . . . . . 10
+ 3.5.2. Removed Member . . . . . . . . . . . . . . . . . . . . 10
+ 3.6. Truncation of Results . . . . . . . . . . . . . . . . . . 11
+ 3.7. Limiting Results . . . . . . . . . . . . . . . . . . . . . 12
+ 3.8. Example: Initial DAV:sync-collection Report . . . . . . . 12
+ 3.9. Example: DAV:sync-collection Report with Token . . . . . . 14
+ 3.10. Example: Initial DAV:sync-collection Report with
+ Truncation . . . . . . . . . . . . . . . . . . . . . . . . 16
+ 3.11. Example: Initial DAV:sync-collection Report with Limit . . 17
+ 3.12. Example: DAV:sync-collection Report with Unsupported
+ Limit . . . . . . . . . . . . . . . . . . . . . . . . . . 18
+ 3.13. Example: DAV:sync-level Set to Infinite, Initial
+ DAV:sync-collection Report . . . . . . . . . . . . . . . . 19
+ 4. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 22
+ 5. DAV:sync-token Use with If Header . . . . . . . . . . . . . . 22
+ 5.1. Example: If Precondition with PUT . . . . . . . . . . . . 22
+ 5.2. Example: If Precondition with MKCOL . . . . . . . . . . . 23
+ 6. XML Element Definitions . . . . . . . . . . . . . . . . . . . 24
+ 6.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 24
+ 6.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 24
+ 6.3. DAV:sync-level XML Element . . . . . . . . . . . . . . . . 24
+ 6.4. DAV:multistatus XML Element . . . . . . . . . . . . . . . 25
+ 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25
+ 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . . 25
+ 9.2. Informative References . . . . . . . . . . . . . . . . . . 26
+ Appendix A. Backwards-Compatible Handling of Depth . . . . . . . 27
+ Appendix B. Example of a Client Synchronization Approach . . . . 27
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 3]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+1. Introduction
+
+ WebDAV [RFC4918] defines the concept of 'collections', which are
+ hierarchical groupings of WebDAV resources on an HTTP [RFC2616]
+ server. Collections can be of arbitrary size and depth (i.e.,
+ collections within collections). WebDAV clients that cache resource
+ content need a way to synchronize that data with the server (i.e.,
+ detect what has changed and update their cache). Currently, this can
+ be done using a WebDAV PROPFIND request on a collection to list all
+ members of a collection along with their DAV:getetag property values,
+ which allows the client to determine which were changed, added, or
+ deleted. However, this does not scale well to large collections, as
+ the XML response to the PROPFIND request will grow with the
+ collection size.
+
+ This specification defines a new WebDAV report that results in the
+ server returning to the client only information about those member
+ URLs that were added or deleted, or whose mapped resources were
+ changed, since a previous execution of the report on the collection.
+
+ Additionally, a new property is added to collection resources that is
+ used to convey a "synchronization token" that is guaranteed to change
+ when the collection's member URLs or their mapped resources have
+ changed.
+
+2. Conventions Used in This Document
+
+ 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 [RFC2119].
+
+ This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section
+ 3.2) as a purely notational convention. WebDAV request and response
+ bodies cannot be validated by a DTD due to the specific extensibility
+ rules defined in Section 17 of [RFC4918] and due to the fact that all
+ XML elements defined by this specification use the XML namespace name
+ "DAV:". In particular:
+
+ 1. Element names use the "DAV:" namespace.
+
+ 2. Element ordering is irrelevant unless explicitly stated
+ otherwise.
+
+ 3. Extension elements (elements not already defined as valid child
+ elements) may be added anywhere, except when explicitly stated
+ otherwise.
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 4]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ 4. Extension attributes (attributes not already defined as valid for
+ this element) may be added anywhere, except when explicitly
+ stated otherwise.
+
+ 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.
+
+ This document inherits, and sometimes extends, DTD productions from
+ Section 14 of [RFC4918].
+
+3. WebDAV Synchronization
+
+3.1. Overview
+
+ One way to synchronize data between two entities is to use some form
+ of synchronization token. The token defines the state of the data
+ being synchronized at a particular point in time. It can then be
+ used to determine what has changed between one point in time and
+ another.
+
+ This specification defines a new WebDAV report that is used to enable
+ client-server collection synchronization based on such a token.
+
+ In order to synchronize the contents of a collection between a server
+ and client, the server provides the client with a synchronization
+ token each time the synchronization report is executed. That token
+ represents the state of the data being synchronized at that point in
+ time. The client can then present that same token back to the server
+ at some later time, and the server will return only those items that
+ are new, have changed, or were deleted since that token was
+ generated. The server also returns a new token representing the new
+ state at the time the report was run.
+
+ Typically, the first time a client connects to the server it will
+ need to be informed of the entire state of the collection (i.e., a
+ full list of all member URLs that are currently in the collection).
+ That is done by the client sending an empty token value to the
+ server. This indicates to the server that a full listing is
+ required.
+
+ As an alternative, the client might choose to do its first
+ synchronization using some other mechanism on the collection (e.g.,
+ some other form of batch resource information retrieval such as
+ PROPFIND, SEARCH [RFC5323], or specialized REPORTs such as those
+ defined in CalDAV [RFC4791] and CardDAV [RFC6352]) and ask for the
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 5]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ DAV:sync-token property to be returned. This property (defined in
+ Section 4) contains the same token that can be used later to issue a
+ DAV:sync-collection report.
+
+ In some cases, a server might only wish to maintain a limited amount
+ of history about changes to a collection. In that situation, it will
+ return an error to the client when the client presents a token that
+ is "out of date". At that point, the client has to fall back to
+ synchronizing the entire collection by re-running the report request
+ using an empty token value.
+
+ Typically, a client will use the synchronization report to retrieve
+ the list of changes and will follow that with requests to retrieve
+ the content of changed resources. It is possible that additional
+ changes to the collection could occur between the time of the
+ synchronization report and resource content retrieval, which could
+ result in an inconsistent view of the collection. When clients use
+ this method of synchronization, they need to be aware that such
+ additional changes could occur and track them, e.g., by differences
+ between the ETag values returned in the synchronization report and
+ those returned when actually fetching resource content, by using
+ conditional requests as described in Section 5, or by repeating the
+ synchronization process until no changes are returned.
+
+3.2. DAV:sync-collection Report
+
+ If the DAV:sync-collection report is implemented by a WebDAV server,
+ then the server MUST list the report in the
+ "DAV:supported-report-set" property on any collection that supports
+ synchronization.
+
+ To implement the behavior for this report, a server needs to keep
+ track of changes to any member URLs and their mapped resources in a
+ collection (as defined in Section 3 of [RFC4918]). This includes
+ noting the addition of new member URLs, the changes to the mapped
+ resources of existing member URLs, and the removal of member URLs.
+ The server will track each change and provide a synchronization
+ "token" to the client that describes the state of the server at a
+ specific point in time. This "token" is returned as part of the
+ response to the "sync-collection" report. Clients include the last
+ token they got from the server in the next "sync-collection" report
+ that they execute, and the server provides the changes from the
+ previous state (represented by the token) to the current state
+ (represented by the new token returned).
+
+ The synchronization token itself MUST be treated as an "opaque"
+ string by the client, i.e., the actual string data has no specific
+ meaning or syntax. However, the token MUST be a valid URI to allow
+
+
+
+Daboo & Quillaud Standards Track [Page 6]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ its use in an If precondition request header (see Section 5). For
+ example, a simple implementation of such a token could be a numeric
+ counter that counts each change as it occurs and relates that change
+ to the specific object that changed. The numeric value could be
+ appended to a "base" URI to form the valid sync-token.
+
+ Marshalling:
+
+ The request-URI MUST identify a collection. The request body MUST
+ be a DAV:sync-collection XML element (see Section 6.1), which MUST
+ contain one DAV:sync-token XML element, one DAV:sync-level
+ element, and one DAV:prop XML element, and MAY contain a DAV:limit
+ XML element.
+
+ This report is only defined when the Depth header has value "0";
+ other values result in a 400 (Bad Request) error response. Note
+ that [RFC3253], Section 3.6, states that if the Depth header is
+ not present, it defaults to a value of "0".
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element, which MUST contain one DAV:sync-token
+ element in addition to one DAV:response element for each member
+ URL that was added, has had its mapped resource changed, or was
+ deleted since the last synchronization operation as specified by
+ the DAV:sync-token provided in the request. A given member URL
+ MUST appear only once in the response. In the case where multiple
+ member URLs of the request-URI are mapped to the same resource, if
+ the resource is changed, each member URL MUST be returned in the
+ response.
+
+ The content of each DAV:response element differs depending on how
+ the member was altered:
+
+ For members that have changed (i.e., are new or have had their
+ mapped resource modified), the DAV:response MUST contain at
+ least one DAV:propstat element and MUST NOT contain any
+ DAV:status element.
+
+ For members that have been removed, the DAV:response MUST
+ contain one DAV:status with a value set to '404 Not Found' and
+ MUST NOT contain any DAV:propstat element.
+
+ For members that are collections and are unable to support the
+ DAV:sync-collection report, the DAV:response MUST contain one
+ DAV:status with a value set to '403 Forbidden', a DAV:error
+ containing DAV:supported-report or DAV:sync-traversal-supported
+ (see Section 3.3 for which is appropriate) and MUST NOT contain
+ any DAV:propstat element.
+
+
+
+Daboo & Quillaud Standards Track [Page 7]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ The conditions under which each type of change can occur are
+ further described in Section 3.5.
+
+ Preconditions:
+
+ (DAV:valid-sync-token): The DAV:sync-token element value MUST be a
+ valid token previously returned by the server for the collection
+ targeted by the request-URI. Servers might need to invalidate
+ tokens previously returned to clients. Doing so will cause the
+ clients to fall back to doing full synchronization using the
+ report, though that will not require clients to download resources
+ that are already cached and have not changed. Even so, servers
+ MUST limit themselves to invalidating tokens only when absolutely
+ necessary. Specific reasons include:
+
+ * Servers might be unable to maintain all of the change data for
+ a collection due to storage or performance reasons, e.g.,
+ servers might only be able to maintain up to 3 weeks worth of
+ changes to a collection, or only up to 10,000 total changes, or
+ not wish to maintain changes for a deleted collection.
+
+ * Change to server implementation: servers might be upgraded to a
+ new implementation that tracks the history in a different
+ manner, and thus previous synchronization history is no longer
+ valid.
+
+ Postconditions:
+
+ (DAV:number-of-matches-within-limits): The number of changes
+ reported in the response must fall within the client-specified
+ limit. This condition might be triggered if a client requests a
+ limit on the number of responses (as per Section 3.7), but the
+ server is unable to truncate the result set at or below that
+ limit.
+
+3.3. Depth Behavior
+
+ Servers MUST support only Depth:0 behavior with the
+ DAV:sync-collection report, i.e., the report targets only the
+ collection being synchronized in a single request. However, clients
+ do need to "scope" the synchronization to different levels within
+ that collection -- specifically, immediate children (level "1") and
+ all children at any depth (level "infinite"). To specify which level
+ to use, clients MUST include a DAV:sync-level XML element in the
+ request.
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 8]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ o When the client specifies the DAV:sync-level XML element with a
+ value of "1", only appropriate internal member URLs (immediate
+ children) of the collection specified as the request-URI are
+ reported.
+
+ o When the client specifies the DAV:sync-level XML element with a
+ value of "infinite", all appropriate member URLs of the collection
+ specified as the request-URI are reported, provided child
+ collections themselves also support the DAV:sync-collection
+ report.
+
+ o DAV:sync-token values returned by the server are not specific to
+ the value of the DAV:sync-level XML element used in the request.
+ As such, clients MAY use a DAV:sync-token value from a request
+ with one DAV:sync-level XML element value for a similar request
+ with a different DAV:sync-level XML element value; however, the
+ utility of this is limited.
+
+ Note that when a server supports a DAV:sync-level XML element with a
+ value of "infinite", it might not be possible to synchronize some
+ child collections within the collection targeted by the report. When
+ this occurs, the server MUST include a DAV:response element for the
+ child collection with status 403 (Forbidden). The 403 response MUST
+ be sent once, when the collection is first reported to the client.
+ In addition, the server MUST include a DAV:error element in the
+ DAV:response element, indicating one of two possible causes for this:
+
+ The DAV:sync-collection report is not supported at all on the
+ child collection. The DAV:error element MUST contain the
+ DAV:supported-report element.
+
+ The server is unwilling to report results for the child collection
+ when a DAV:sync-collection report with the DAV:sync-level XML
+ element set to "infinite" is executed on a parent resource. This
+ might happen when, for example, the synchronization state of the
+ collection resource is controlled by another subsystem. In such
+ cases clients can perform the DAV:sync-collection report directly
+ on the child collection instead. The DAV:error element MUST
+ contain the DAV:sync-traversal-supported element.
+
+3.4. Types of Changes Reported on Initial Synchronization
+
+ When the DAV:sync-collection request contains an empty DAV:sync-token
+ element, the server MUST return all member URLs of the collection
+ (taking account of the DAV:sync-level XML element value as per
+ Section 3.3, and optional truncation of the result set as per
+ Section 3.6) and it MUST NOT return any removed member URLs. All
+ types of member (collection or non-collection) MUST be reported.
+
+
+
+Daboo & Quillaud Standards Track [Page 9]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+3.5. Types of Changes Reported on Subsequent Synchronizations
+
+ When the DAV:sync-collection request contains a valid value for the
+ DAV:sync-token element, two types of member URL state changes can be
+ returned (changed or removed). This section defines what triggers
+ each of these to be returned. It also clarifies the case where a
+ member URL might have undergone multiple changes between two
+ synchronization report requests. In all cases, the DAV:sync-level
+ XML element value (as per Section 3.3) and optional truncation of the
+ result set (as per Section 3.6) are taken into account by the server.
+
+3.5.1. Changed Member
+
+ A member URL MUST be reported as changed if it has been newly mapped
+ as a member of the target collection since the request sync-token was
+ generated (e.g., when a new resource has been created as a child of
+ the collection). For example, this includes member URLs that have
+ been newly mapped as the result of a COPY, MOVE, BIND [RFC5842], or
+ REBIND [RFC5842] request. All types of member URL (collection or
+ non-collection) MUST be reported.
+
+ In the case where a mapping between a member URL and the target
+ collection was removed, then a new mapping with the same URI was
+ created, the member URL MUST be reported as changed and MUST NOT be
+ reported as removed.
+
+ A member URL MUST be reported as changed if its mapped resource's
+ entity tag value (defined in Section 3.11 of [RFC2616]) has changed
+ since the request sync-token was generated.
+
+ A member URL MAY be reported as changed if the user issuing the
+ request was granted access to this member URL, due to access control
+ changes.
+
+ Collection member URLs MUST be returned as changed if they are mapped
+ to an underlying resource (i.e., entity body) and if the entity tag
+ associated with that resource changes. There is no guarantee that
+ changes to members of a collection will result in a change in any
+ entity tag of that collection, so clients cannot rely on a series of
+ reports using the DAV:sync-level XML element value set to "1" at
+ multiple levels to track all changes within a collection. Instead, a
+ DAV:sync-level XML element with a value of "infinite" has to be used.
+
+3.5.2. Removed Member
+
+ A member MUST be reported as removed if its mapping under the target
+ collection has been removed since the request sync-token was
+ generated, and it has not been remapped since it was removed. For
+
+
+
+Daboo & Quillaud Standards Track [Page 10]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ example, this includes members that have been unmapped as the result
+ of a MOVE, UNBIND [RFC5842], or REBIND [RFC5842] operation. This
+ also includes collection members that have been removed, including
+ ones that themselves do not support the DAV:sync-collection report.
+
+ If a member was added (and its mapped resource possibly modified),
+ then removed between two synchronization report requests, it MUST be
+ reported as removed. This ensures that a client that adds a member
+ is informed of the removal of the member, if the removal occurs
+ before the client has had a chance to execute a synchronization
+ report.
+
+ A member MAY be reported as removed if the user issuing the request
+ no longer has access to this member, due to access control changes.
+
+ For a report with the DAV:sync-level XML element value set to
+ "infinite", where a collection is removed, the server MUST NOT report
+ the removal of any members of the removed collection. Clients MUST
+ assume that if a collection is reported as being removed, then all
+ members of that collection have also been removed.
+
+3.6. Truncation of Results
+
+ A server MAY limit the number of member URLs in a response, for
+ example, to limit the amount of work expended in processing a
+ request, or as the result of an explicit limit set by the client. If
+ the result set is truncated, the response MUST use status code 207
+ (Multi-Status), return a DAV:multistatus response body, and indicate
+ a status of 507 (Insufficient Storage) for the request-URI. That
+ DAV:response element SHOULD include a DAV:error element with the
+ DAV:number-of-matches-within-limits precondition, as defined in
+ [RFC3744] (Section 9.2). DAV:response elements for all the changes
+ being reported are also included.
+
+ When truncation occurs, the DAV:sync-token value returned in the
+ response MUST represent the correct state for the partial set of
+ changes returned. That allows the client to use the returned
+ DAV:sync-token to fetch the next set of changes. In this way, the
+ client can effectively "page" through the entire set of changes in a
+ consistent manner.
+
+ Clients MUST handle the 507 status on the request-URI in the response
+ to the report.
+
+ For example, consider a server that records changes using a strictly
+ increasing integer to represent a "revision number" and uses that
+ quantity as the DAV:sync-token value (appropriately encoded as a
+ URI). Assume the last DAV:sync-token used by the client was
+
+
+
+Daboo & Quillaud Standards Track [Page 11]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ "http://example.com/sync/10", and since then 15 additional changes to
+ different resources have occurred. If the client executes a
+ DAV:sync-collection request with a DAV:sync-token of
+ "http://example.com/sync/10", without a limit, the server would
+ return 15 DAV:response elements and a DAV:sync-token with value
+ "http://example.com/sync/25". But if the server chooses to limit
+ responses to at most 10 changes, then it would return only 10
+ DAV:response elements and a DAV:sync-token with value
+ "http://example.com/sync/20", together with an additional
+ DAV:response element for the request-URI with a status code of 507.
+ Subsequently, the client can reissue the request with the
+ DAV:sync-token value returned from the server and fetch the remaining
+ 5 changes.
+
+3.7. Limiting Results
+
+ A client can limit the number of results returned by the server
+ through use of the DAV:limit element ([RFC5323], Section 5.17) in the
+ request body. This is useful when clients have limited space or
+ bandwidth for the results. If a server is unable to truncate the
+ result at or below the requested number, then it MUST fail the
+ request with a DAV:number-of-matches-within-limits postcondition
+ error. When the results can be correctly limited by the server, the
+ server MUST follow the rules above for indicating a result set
+ truncation to the client.
+
+3.8. Example: Initial DAV:sync-collection Report
+
+ In this example, the client is making its first synchronization
+ request to the server, so the DAV:sync-token element in the request
+ is empty. It also asks for the DAV:getetag property and for a
+ proprietary property. The server responds with the items currently
+ in the targeted collection. The current synchronization token is
+ also returned.
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 0
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token/>
+ <D:sync-level>1</D:sync-level>
+
+
+
+Daboo & Quillaud Standards Track [Page 12]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <D:prop xmlns:R="urn:ns.example.com:boxschema">
+ <D:getetag/>
+ <R:bigbox/>
+ </D:prop>
+ </D:sync-collection>
+
+
+ >> 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://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00002-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/calendar.ics</D:href>
+
+
+
+Daboo & Quillaud Standards Track [Page 13]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00003-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
+ </D:multistatus>
+
+3.9. Example: DAV:sync-collection Report with Token
+
+ In this example, the client is making a synchronization request to
+ the server and is using the DAV:sync-token element returned from the
+ last report it ran on this collection. The server responds, listing
+ the items that have been added, changed, or removed. The (new)
+ current synchronization token is also returned.
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
+ <D:sync-level>1</D:sync-level>
+ <D:prop xmlns:R="urn:ns.example.com:boxschema">
+ <D:getetag/>
+ <R:bigbox/>
+ </D:prop>
+ </D:sync-collection>
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 14]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ >> 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://webdav.example.com/home/cyrusdaboo/file.xml</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00004-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00002-abcd2"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:response>
+ <D:sync-token>http://example.com/ns/sync/1238</D:sync-token>
+ </D:multistatus>
+
+
+
+Daboo & Quillaud Standards Track [Page 15]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+3.10. Example: Initial DAV:sync-collection Report with Truncation
+
+ In this example, the client is making its first synchronization
+ request to the server, so the DAV:sync-token element in the request
+ is empty. It also asks for the DAV:getetag property. The server
+ responds with the items currently in the targeted collection but
+ truncated at two items. The synchronization token for the truncated
+ result set is returned.
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 0
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token/>
+ <D:sync-level>1</D:sync-level>
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ </D:sync-collection>
+
+
+ >> 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://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+
+
+
+Daboo & Quillaud Standards Track [Page 16]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00002-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/</D:href>
+ <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
+ <D:error><D:number-of-matches-within-limits/></D:error>
+ </D:response>
+ <D:sync-token>http://example.com/ns/sync/1233</D:sync-token>
+ </D:multistatus>
+
+3.11. Example: Initial DAV:sync-collection Report with Limit
+
+ In this example, the client is making its first synchronization
+ request to the server, so the DAV:sync-token element in the request
+ is empty. It requests a limit of 1 for the responses returned by the
+ server. It also asks for the DAV:getetag property. The server
+ responds with the items currently in the targeted collection, but
+ truncated at one item. The synchronization token for the truncated
+ result set is returned.
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 0
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token/>
+ <D:sync-level>1</D:sync-level>
+ <D:limit>
+ <D:nresults>1</D:nresults>
+ </D:limit>
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ </D:sync-collection>
+
+
+
+Daboo & Quillaud Standards Track [Page 17]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ >> 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://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/</D:href>
+ <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
+ <D:error><D:number-of-matches-within-limits/></D:error>
+ </D:response>
+ <D:sync-token>http://example.com/ns/sync/1232</D:sync-token>
+ </D:multistatus>
+
+3.12. Example: DAV:sync-collection Report with Unsupported Limit
+
+ In this example, the client is making a synchronization request to
+ the server with a valid DAV:sync-token element value. It requests a
+ limit of 100 for the responses returned by the server. It also asks
+ for the DAV:getetag property. The server is unable to limit the
+ results to the maximum specified by the client, so it responds with a
+ 507 status code and appropriate postcondition error code.
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 0
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 18]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token>http://example.com/ns/sync/1232</D:sync-token>
+ <D:sync-level>1</D:sync-level>
+ <D:limit>
+ <D:nresults>100</D:nresults>
+ </D:limit>
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ </D:sync-collection>
+
+
+ >> Response <<
+
+
+ HTTP/1.1 507 Insufficient Storage
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:number-of-matches-within-limits/>
+ </D:error>
+
+3.13. Example: DAV:sync-level Set to Infinite, Initial
+ DAV:sync-collection Report
+
+ In this example, the client is making its first synchronization
+ request to the server, so the DAV:sync-token element in the request
+ is empty, and it is using DAV:sync-level set to "infinite". It also
+ asks for the DAV:getetag property and for a proprietary property.
+ The server responds with the items currently in the targeted
+ collection. The current synchronization token is also returned.
+
+ The collection /home/cyrusdaboo/collection1/ exists and has one child
+ resource that is also reported. The collection /home/cyrusdaboo/
+ collection2/ exists but has no child resources. The collection
+ /home/cyrusdaboo/shared/ is returned with a 403 status indicating
+ that a collection exists, but it is unable to report on changes
+ within it in the scope of the current DAV:sync-level "infinite"
+ report. Instead, the client can try a DAV:sync-collection report
+ directly on the collection URI.
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 19]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 0
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token/>
+ <D:sync-level>infinite</D:sync-level>
+ <D:prop xmlns:R="urn:ns.example.com:boxschema">
+ <D:getetag/>
+ <R:bigbox/>
+ </D:prop>
+ </D:sync-collection>
+
+
+ >> 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>/home/cyrusdaboo/collection1/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/cyrusdaboo/collection1/test.doc</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
+ <R:BoxType>Box type A</R:BoxType>
+
+
+
+Daboo & Quillaud Standards Track [Page 20]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ </R:bigbox>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/cyrusdaboo/collection2/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/cyrusdaboo/calendar.ics</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00003-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/cyrusdaboo/shared/</D:href>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ <D:error><D:sync-traversal-supported/></D:error>
+ </D:response>
+ <D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
+ </D:multistatus>
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 21]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+4. DAV:sync-token Property
+
+ Name: sync-token
+
+ Namespace: DAV:
+
+ Purpose: Contains the value of the synchronization token as it would
+ be returned by a DAV:sync-collection report.
+
+ Value: Any valid URI.
+
+ Protected: MUST be protected because this value is created and
+ controlled by the server.
+
+ COPY/MOVE behavior: This property value is dependent on the final
+ state of the destination resource, not the value of the property
+ on the source resource.
+
+ Description: The DAV:sync-token property MUST be defined on all
+ resources that support the DAV:sync-collection report. It
+ contains the value of the synchronization token as it would be
+ returned by a DAV:sync-collection report on that resource at the
+ same point in time. It SHOULD NOT be returned by a PROPFIND
+ DAV:allprop request (as defined in Section 14.2 of [RFC4918]).
+
+ Definition:
+
+ <!ELEMENT sync-token #PCDATA>
+
+ <!-- Text MUST be a valid URI -->
+
+5. DAV:sync-token Use with If Header
+
+ WebDAV provides an If precondition header that allows for "state
+ tokens" to be used as preconditions on HTTP requests (as defined in
+ Section 10.4 of [RFC4918]). This specification allows the
+ DAV:sync-token value to be used as one such token in an If header.
+ By using this, clients can ensure requests only complete when there
+ have been no changes to the content of a collection, by virtue of an
+ unchanged DAV:sync-token value. Servers MUST support use of
+ DAV:sync-token values in If request headers.
+
+5.1. Example: If Precondition with PUT
+
+ In this example, the client has already used the DAV:sync-collection
+ report to synchronize the collection /home/cyrusdaboo/collection/.
+ Now it wants to add a new resource to the collection, but only if
+ there have been no other changes since the last synchronization.
+
+
+
+Daboo & Quillaud Standards Track [Page 22]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ Note that because the DAV:sync-token is defined on the collection and
+ not on the resource targeted by the request, the If header value
+ needs to use the "Resource_Tag" construct for the header syntax to
+ correctly identify that the supplied state token refers to the
+ collection resource.
+
+ >> Request <<
+
+
+ PUT /home/cyrusdaboo/collection/newresource.txt HTTP/1.1
+ Host: webdav.example.com
+ If: </home/cyrusdaboo/collection/>
+ (<http://example.com/ns/sync/12345>)
+ Content-Type: text/plain; charset="utf-8"
+ Content-Length: xxxx
+
+ Some content here...
+
+
+ >> Response <<
+
+
+ HTTP/1.1 201 Created
+
+5.2. Example: If Precondition with MKCOL
+
+ In this example, the client has already used the DAV:sync-collection
+ report to synchronize the collection /home/cyrusdaboo/collection/.
+ Now, it wants to add a new collection to the collection, but only if
+ there have been no other changes since the last synchronization.
+ Note that because the DAV:sync-token is defined on the collection and
+ not on the resource targeted by the request, the If header value
+ needs to use the "Resource_Tag" construct for the header syntax to
+ correctly identify that the supplied state token refers to the
+ collection resource. In this case, the request fails as another
+ change has occurred to the collection corresponding to the supplied
+ DAV:sync-token.
+
+ >> Request <<
+
+
+ MKCOL /home/cyrusdaboo/collection/child/ HTTP/1.1
+ Host: webdav.example.com
+ If: </home/cyrusdaboo/collection/>
+ (<http://example.com/ns/sync/12346>)
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 23]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ >> Response <<
+
+
+ HTTP/1.1 412 Precondition Failed
+
+6. XML Element Definitions
+
+6.1. DAV:sync-collection XML Element
+
+ Name: sync-collection
+
+ Namespace: DAV:
+
+ Purpose: WebDAV report used to synchronize data between client and
+ server.
+
+ Description: See Section 3.
+
+ <!ELEMENT sync-collection (sync-token, sync-level, limit?, prop)>
+
+ <!-- DAV:limit defined in RFC 5323, Section 5.17 -->
+ <!-- DAV:prop defined in RFC 4918, Section 14.18 -->
+
+6.2. DAV:sync-token XML Element
+
+ Name: sync-token
+
+ Namespace: DAV:
+
+ Purpose: The synchronization token provided by the server and
+ returned by the client.
+
+ Description: See Section 3.
+
+ <!ELEMENT sync-token CDATA>
+
+ <!-- Text MUST be a URI -->
+
+6.3. DAV:sync-level XML Element
+
+ Name: sync-level
+
+ Namespace: DAV:
+
+ Purpose: Indicates the "scope" of the synchronization report
+ request.
+
+ Description: See Section 3.3.
+
+
+
+Daboo & Quillaud Standards Track [Page 24]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <!ELEMENT sync-level CDATA>
+
+ <!-- Text MUST be either "1" or "infinite" -->
+
+6.4. DAV:multistatus XML Element
+
+ Name: multistatus
+
+ Namespace: DAV:
+
+ Purpose: Extends the DAV:multistatus element to include
+ synchronization details.
+
+ Description: See Section 3.
+
+ <!ELEMENT multistatus (response*, responsedescription?,
+ sync-token?) >
+
+ <!-- DAV:multistatus originally defined in RFC 4918, Section 14.16
+ but overridden here to add the DAV:sync-token element -->
+ <!-- DAV:response defined in RFC 4918, Section 14.24 -->
+ <!-- DAV:responsedescription defined in RFC 4918, Section 14.25 -->
+
+7. Security Considerations
+
+ This extension does not introduce any new security concerns beyond
+ those already described in HTTP and WebDAV.
+
+8. Acknowledgments
+
+ The following individuals contributed their ideas and support for
+ writing this specification: Bernard Desruisseaux, Werner Donne, Mike
+ Douglass, Ciny Joy, Andrew McMillan, Julian Reschke, and Wilfredo
+ Sanchez. We would like to thank the Calendaring and Scheduling
+ Consortium for facilitating interoperability testing for early
+ implementations of this specification.
+
+9. References
+
+9.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+ Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
+ Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+
+
+
+Daboo & Quillaud Standards Track [Page 25]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
+ Whitehead, "Versioning Extensions to WebDAV
+ (Web Distributed Authoring and Versioning)", RFC 3253,
+ March 2002.
+
+ [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
+ Distributed Authoring and Versioning (WebDAV)
+ Access Control Protocol", RFC 3744, May 2004.
+
+ [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+
+ [RFC5323] Reschke, J., Reddy, S., Davis, J., and A. Babich, "Web
+ Distributed Authoring and Versioning (WebDAV) SEARCH",
+ RFC 5323, November 2008.
+
+ [W3C.REC-xml-20081126]
+ Sperberg-McQueen, C., Yergeau, F., Paoli, J., Maler, E.,
+ and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
+ Edition)", World Wide Web Consortium
+ Recommendation REC-xml-20081126, November 2008,
+ <http://www.w3.org/TR/2008/REC-xml-20081126>.
+
+9.2. Informative References
+
+ [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
+ "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
+ March 2007.
+
+ [RFC5842] Clemm, G., Crawford, J., Reschke, J., and J. Whitehead,
+ "Binding Extensions to Web Distributed Authoring and
+ Versioning (WebDAV)", RFC 5842, April 2010.
+
+ [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 6352, August 2011.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 26]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+Appendix A. Backwards-Compatible Handling of Depth
+
+ In prior draft versions of this specification, the Depth request
+ header was used instead of the DAV:sync-level element to indicate the
+ "scope" of the synchronization request. Servers that wish to be
+ backwards compatible with clients conforming to the older
+ specification should do the following: if a DAV:sync-level element is
+ not present in the request body, use the Depth header value as the
+ equivalent value for the missing DAV:sync-level element.
+
+Appendix B. Example of a Client Synchronization Approach
+
+ This appendix gives an example of how a client might accomplish
+ collection synchronization using the WebDAV sync report defined in
+ this specification. Note that this is provided purely as an example,
+ and is not meant to be treated as a normative "algorithm" for client
+ synchronization.
+
+ This example assumes a WebDAV client interacting with a WebDAV server
+ supporting the sync report. The client keeps a local cache of
+ resources in a targeted collection, "/collection/". Local changes
+ are assumed to not occur. The client is only tracking changes to the
+ immediate children of the collection resource.
+
+ ** Initial State **
+
+ The client starts out with an empty local cache.
+
+ The client starts out with no DAV:sync-token stored for
+ "/collection/".
+
+
+ ** Initial Synchronization **
+
+ The client issues a sync report request to the server with an
+ empty DAV:sync-token element, and DAV:sync-level set to "1". The
+ request asks for the server to return the DAV:getetag WebDAV
+ property for each resource it reports.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 27]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ The server returns a response containing the list of current
+ resources (with their associated DAV:getetag properties) as well
+ as a new DAV:sync-token value.
+
+ The client associates the new DAV:sync-token value with the
+ collection.
+
+ For each reported resource, the client creates a set of (resource
+ path, DAV:getetag) tuples.
+
+ For each tuple, the client issues an HTTP GET request to the
+ server to retrieve its content, and updates the (resource path,
+ DAV:getetag) entry in its local cache for that resource with the
+ ETag response header value returned in the GET request.
+
+
+ ** Routine Synchronization **
+
+ The client issues a sync report request to the server with the
+ DAV:sync-token set to the current cached value from the last sync,
+ and DAV:sync-level set to "1". The request asks for the server to
+ return the DAV:getetag WebDAV property for each resource it
+ reports.
+
+ The server returns a response containing the list of changes as
+ well as a new DAV:sync-token value.
+
+ The client associates the new DAV:sync-token value with the
+ collection.
+
+ * Process Removed Resources *
+
+ For each resource reported with a 404 response status, the client
+ removes the corresponding resource from its local cache.
+
+ * Process Resources *
+
+ For each remaining reported resource, the client creates a new set
+ of (resource path, DAV:getetag) tuples.
+
+ The client then determines which resources are in the new set but
+ not in the current cache, and which resources are in the new set
+ and the current cache but have a different DAV:getetag value. For
+ each of those, the client issues an HTTP GET request to the server
+ to retrieve the resource content, and updates the (resource path,
+ DAV:getetag) entry in its local cache for that resource with the
+ ETag response header value returned in the GET request.
+
+
+
+
+Daboo & Quillaud Standards Track [Page 28]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+Authors' Addresses
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: cyrus@daboo.name
+ URI: http://www.apple.com/
+
+
+ Arnaud Quillaud
+ Oracle Corporation
+ 180, Avenue de l'Europe
+ Saint Ismier cedex 38334
+ France
+
+ EMail: arnaud.quillaud@oracle.com
+ URI: http://www.oracle.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 29]
+
diff --git a/docs/rfcs/rfc6764.txt b/docs/rfcs/rfc6764.txt
new file mode 100644
index 0000000..aed17a8
--- /dev/null
+++ b/docs/rfcs/rfc6764.txt
@@ -0,0 +1,787 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Daboo
+Request for Comments: 6764 Apple Inc.
+Updates: 4791, 6352 February 2013
+Category: Standards Track
+ISSN: 2070-1721
+
+
+ Locating Services for Calendaring Extensions to
+ WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)
+
+Abstract
+
+ This specification describes how DNS SRV records, DNS TXT records,
+ and well-known URIs can be used together or separately to locate
+ CalDAV (Calendaring Extensions to Web Distributed Authoring and
+ Versioning (WebDAV)) or CardDAV (vCard Extensions to WebDAV)
+ services.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6764.
+
+Copyright Notice
+
+ Copyright (c) 2013 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+
+
+Daboo Standards Track [Page 1]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+Table of Contents
+
+ 1. Introduction ....................................................2
+ 2. Conventions Used in This Document ...............................3
+ 3. CalDAV SRV Service Labels .......................................3
+ 4. CalDAV and CardDAV Service TXT Records ..........................4
+ 5. CalDAV and CardDAV Service Well-Known URI .......................4
+ 5.1. Example: Well-Known URI Redirects to Actual
+ "Context Path" .............................................5
+ 6. Client "Bootstrapping" Procedures ...............................5
+ 7. Guidance for Service Providers ..................................8
+ 8. Security Considerations .........................................9
+ 9. IANA Considerations .............................................9
+ 9.1. Well-Known URI Registrations ...............................9
+ 9.1.1. caldav Well-Known URI Registration .................10
+ 9.1.2. carddav Well-Known URI Registration ................10
+ 9.2. Service Name Registrations ................................10
+ 9.2.1. caldav Service Name Registration ...................10
+ 9.2.2. caldavs Service Name Registration ..................11
+ 9.2.3. carddav Service Name Registration ..................11
+ 9.2.4. carddavs Service Name Registration .................12
+ 10. Acknowledgments ...............................................12
+ 11. References ....................................................12
+ 11.1. Normative References .....................................12
+ 11.2. Informative References ...................................14
+
+1. Introduction
+
+ [RFC4791] defines the CalDAV calendar access protocol, based on HTTP
+ [RFC2616], for accessing calendar data stored on a server. CalDAV
+ clients need to be able to discover appropriate CalDAV servers within
+ their local area network and at other domains, e.g., to minimize the
+ need for end users to know specific details such as the fully
+ qualified domain name (FQDN) and port number for their servers.
+
+ [RFC6352] defines the CardDAV address book access protocol based on
+ HTTP [RFC2616], for accessing contact data stored on a server. As
+ with CalDAV, clients also need to be able to discover CardDAV
+ servers.
+
+ [RFC2782] defines a DNS-based service discovery protocol that has
+ been widely adopted as a means of locating particular services within
+ a local area network and beyond, using DNS SRV Resource Records
+ (RRs). This has been enhanced to provide additional service meta-
+ data by use of DNS TXT RRs as per [RFC6763].
+
+
+
+
+
+
+Daboo Standards Track [Page 2]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+ This specification defines new SRV service types for the CalDAV
+ protocol and gives an example of how clients can use this together
+ with other protocol features to enable simple client configuration.
+ SRV service types for CardDAV are already defined in Section 11 of
+ [RFC6352].
+
+ Another issue with CalDAV or CardDAV service discovery is that the
+ service might not be located at the "root" URI of the HTTP server
+ hosting it. Thus, a client needs to be able to determine the
+ complete path component of the Request-URI to use in HTTP requests:
+ the "context path". For example, if CalDAV is implemented as a
+ "servlet" in a web server "container", the servlet "context path"
+ might be "/caldav/". So the URI for the CalDAV service would be,
+ e.g., "http://caldav.example.com/caldav/" rather than
+ "http://caldav.example.com/". SRV RRs by themselves only provide an
+ FQDN and port number for the service, not a path. Since the client
+ "bootstrapping" process requires initial access to the "context path"
+ of the service, there needs to be a simple way for clients to also
+ discover what that path is.
+
+ This specification makes use of the "well-known URI" feature
+ [RFC5785] of HTTP servers to provide a well-known URI for CalDAV or
+ CardDAV services that clients can use. The well-known URI will point
+ to a resource on the server that is simply a "stub" resource that
+ provides a redirect to the actual "context path" resource
+ representing the service endpoint.
+
+2. Conventions Used in This Document
+
+ 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 [RFC2119].
+
+3. CalDAV SRV Service Labels
+
+ This specification adds two SRV service labels for use with CalDAV:
+
+ _caldav: Identifies a CalDAV server that uses HTTP without
+ Transport Layer Security (TLS) [RFC2818].
+
+ _caldavs: Identifies a CalDAV server that uses HTTP with TLS
+ [RFC2818].
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 3]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+ Clients MUST honor Priority and Weight values in the SRV RRs, as
+ described by [RFC2782].
+
+ Example: service record for server without TLS
+
+ _caldav._tcp SRV 0 1 80 calendar.example.com.
+
+ Example: service record for server with TLS
+
+ _caldavs._tcp SRV 0 1 443 calendar.example.com.
+
+4. CalDAV and CardDAV Service TXT Records
+
+ When SRV RRs are used to advertise CalDAV and CardDAV services, it is
+ also convenient to be able to specify a "context path" in the DNS to
+ be retrieved at the same time. To enable that, this specification
+ uses a TXT RR that follows the syntax defined in Section 6 of
+ [RFC6763] and defines a "path" key for use in that record. The value
+ of the key MUST be the actual "context path" to the corresponding
+ service on the server.
+
+ A site might provide TXT records in addition to SRV records for each
+ service. When present, clients MUST use the "path" value as the
+ "context path" for the service in HTTP requests. When not present,
+ clients use the ".well-known" URI approach described next.
+
+ Example: text record for service with TLS
+
+ _caldavs._tcp TXT path=/caldav
+
+5. CalDAV and CardDAV Service Well-Known URI
+
+ Two ".well-known" URIs are registered by this specification for
+ CalDAV and CardDAV services, "caldav" and "carddav" respectively (see
+ Section 9). These URIs point to a resource that the client can use
+ as the initial "context path" for the service they are trying to
+ connect to. The server MUST redirect HTTP requests for that resource
+ to the actual "context path" using one of the available mechanisms
+ provided by HTTP (e.g., using a 301, 303, or 307 response). Clients
+ MUST handle HTTP redirects on the ".well-known" URI. Servers MUST
+ NOT locate the actual CalDAV or CardDAV service endpoint at the
+ ".well-known" URI as per Section 1.1 of [RFC5785].
+
+ Servers SHOULD set an appropriate Cache-Control header value (as per
+ Section 14.9 of [RFC2616]) in the redirect response to ensure caching
+ occurs or does not occur as needed or as required by the type of
+ response generated. For example, if it is anticipated that the
+
+
+
+
+Daboo Standards Track [Page 4]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+ location of the redirect might change over time, then a "no-cache"
+ value would be used.
+
+ To facilitate "context paths" that might differ from user to user,
+ the server MAY require authentication when a client tries to access
+ the ".well-known" URI (i.e., the server would return a 401 status
+ response to the unauthenticated request from the client, then return
+ the redirect response only after a successful authentication by the
+ client).
+
+5.1. Example: Well-Known URI Redirects to Actual "Context Path"
+
+ A CalDAV server has a "context path" that is "/servlet/caldav". The
+ client will use "/.well-known/caldav" as the path for its
+ "bootstrapping" process after it has first found the FQDN and port
+ number via an SRV lookup or via manual entry of information by the
+ user, from which the client can parse suitable information. When the
+ client makes an HTTP request against "/.well-known/caldav", the
+ server would issue an HTTP redirect response with a Location response
+ header using the path "/servlet/caldav". The client would then
+ "follow" this redirect to the new resource and continue making HTTP
+ requests there to complete its "bootstrapping" process.
+
+6. Client "Bootstrapping" Procedures
+
+ This section describes a procedure that CalDAV or CardDAV clients
+ SHOULD use to do their initial configuration based on minimal user
+ input. The goal is to determine an http: or https: URI that
+ describes the full path to the user's principal-URL [RFC3744].
+
+ 1. Processing user input:
+
+ * For a CalDAV server:
+
+ + Minimal input from a user would consist of a calendar user
+ address and a password. A calendar user address is defined
+ by iCalendar [RFC5545] to be a URI [RFC3986]. Provided a
+ user identifier and a domain name can be extracted from the
+ URI, this simple "bootstrapping" configuration can be done.
+
+ + If the calendar user address is a "mailto:" [RFC6068] URI,
+ the "mailbox" portion of the URI is examined, and the
+ "local-part" and "domain" portions are extracted.
+
+ + If the calendar user address is an "http:" [RFC2616] or
+ "https:" [RFC2818] URI, the "userinfo" and "host" portion
+ of the URI [RFC3986] is extracted.
+
+
+
+
+Daboo Standards Track [Page 5]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+ * For a CardDAV server:
+
+ + Minimal input from a user would consist of their email
+ address [RFC5322] for the domain where the CardDAV service
+ is hosted, and a password. The "mailbox" portion of the
+ email address is examined, and the "local-part" and
+ "domain" portions are extracted.
+
+ 2. Determination of service FQDN and port number:
+
+ * An SRV lookup for _caldavs._tcp (for CalDAV) or _carddavs._tcp
+ (for CardDAV) is done with the extracted "domain" as the
+ service domain.
+
+ * If no result is found, the client can try _caldav._tcp (for
+ CalDAV) or _carddav._tcp (for CardDAV) provided non-TLS
+ connections are appropriate.
+
+ * If an SRV record is returned, the client extracts the target
+ FQDN and port number. If multiple SRV records are returned,
+ the client MUST use the Priority and Weight fields in the
+ record to determine which one to pick (as per [RFC2782]).
+
+ * If an SRV record is not found, the client will need to prompt
+ the user to enter the FQDN and port number information
+ directly or use some other heuristic, for example, using the
+ extracted "domain" as the FQDN and default HTTPS or HTTP port
+ numbers. In this situation, clients MUST first attempt an
+ HTTP connection with TLS.
+
+ 3. Determination of initial "context path":
+
+ * When an SRV lookup is done and a valid SRV record returned,
+ the client MUST also query for a corresponding TXT record and
+ check for the presence of a "path" key in its response. If
+ present, the value of the "path" key is used for the initial
+ "context path".
+
+ * When an initial "context path" has not been determined from a
+ TXT record, the initial "context path" is taken to be
+ "/.well-known/caldav" (for CalDAV) or "/.well-known/carddav"
+ (for CardDAV).
+
+ * If the initial "context path" derived from a TXT record
+ generates HTTP errors when targeted by requests, the client
+ SHOULD repeat its "bootstrapping" procedure using the
+ appropriate ".well-known" URI instead.
+
+
+
+
+Daboo Standards Track [Page 6]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+ 4. Determination of user identifier:
+
+ * The client will need to make authenticated HTTP requests to
+ the service. Typically, a "user identifier" is required for
+ some form of user/password authentication. When a user
+ identifier is required, clients MUST first use the "mailbox"
+ portion of the calendar user address provided by the user in
+ the case of a "mailto:" address and, if that results in an
+ authentication failure, SHOULD fall back to using the "local-
+ part" extracted from the "mailto:" address. For an "http:" or
+ "https:" calendar user address, the "userinfo" portion is used
+ as the user identifier for authentication. This is in line
+ with the guidance outlined in Section 7. If these user
+ identifiers result in authentication failure, the client
+ SHOULD prompt the user for a valid identifier.
+
+ 5. Connecting to the service:
+
+ * Subsequent to configuration, the client will make HTTP
+ requests to the service. When using "_caldavs" or "_carddavs"
+ services, a TLS negotiation is done immediately upon
+ connection. The client MUST do certificate verification using
+ the procedure outlined in Section 6 of [RFC6125] in regard to
+ verification with an SRV RR as the starting point.
+
+ * The client does a "PROPFIND" [RFC4918] request with the
+ request URI set to the initial "context path". The body of
+ the request SHOULD include the DAV:current-user-principal
+ [RFC5397] property as one of the properties to return. Note
+ that clients MUST properly handle HTTP redirect responses for
+ the request. The server will use the HTTP authentication
+ procedure outlined in [RFC2617] or use some other appropriate
+ authentication schemes to authenticate the user.
+
+ * If the server returns a 404 ("Not Found") HTTP status response
+ to the request on the initial "context path", clients MAY try
+ repeating the request on the "root" URI "/" or prompt the user
+ for a suitable path.
+
+ * If the DAV:current-user-principal property is returned on the
+ request, the client uses that value for the principal-URL of
+ the authenticated user. With that, it can execute a
+ "PROPFIND" request on the principal-URL and discover
+ additional properties for configuration (e.g., calendar or
+ address book "home" collections).
+
+
+
+
+
+
+Daboo Standards Track [Page 7]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+ * If the DAV:current-user-principal property is not returned,
+ then the client will need to request the principal-URL path
+ from the user in order to continue with configuration.
+
+ Once a successful account discovery step has been done, clients
+ SHOULD cache the service details that were successfully used (user
+ identity, principal-URL with full scheme/host/port details) and reuse
+ those when connecting again at a later time.
+
+ If a subsequent connection attempt fails, or authentication fails
+ persistently, clients SHOULD retry the SRV lookup and account
+ discovery to "refresh" the cached data.
+
+7. Guidance for Service Providers
+
+ Service providers wanting to offer CalDAV or CardDAV services that
+ can be configured by clients using SRV records need to follow certain
+ procedures to ensure proper operation.
+
+ o CalDAV or CardDAV servers SHOULD be configured to allow
+ authentication with calendar user addresses (just taking the
+ "mailbox" portion of any "mailto:" URI) or email addresses
+ respectively, or with "user identifiers" extracted from them. In
+ the former case, the addresses MUST NOT conflict with other forms
+ of a permitted user login name. In the latter case, the extracted
+ "user identifiers" need to be unique across the server and MUST
+ NOT conflict with any login name on the server.
+
+ o Servers MUST force authentication for "PROPFIND" requests that
+ retrieve the DAV:current-user-principal property to ensure that
+ the value of the DAV:current-user-principal property returned
+ corresponds to the principal-URL of the user making the request.
+
+ o If the service provider uses TLS, the service provider MUST ensure
+ a certificate is installed that can be verified by clients using
+ the procedure outlined in Section 6 of [RFC6125] in regard to
+ verification with an SRV RR as the starting point. In particular,
+ certificates SHOULD include SRV-ID and DNS-ID identifiers as
+ appropriate, as described in Section 8.
+
+ o Service providers should install the appropriate SRV records for
+ the offered services and optionally include TXT records.
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 8]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+8. Security Considerations
+
+ Clients that support TLS as defined by [RFC2818] SHOULD try the
+ "_caldavs" or "_carddavs" services first before trying the "_caldav"
+ or "_carddav" services respectively. If a user has explicitly
+ requested a connection with TLS, the client MUST NOT use any service
+ information returned for the "_caldav" or "_carddav" services.
+ Clients MUST follow the certificate-verification process specified in
+ [RFC6125].
+
+ A malicious attacker with access to the DNS server data, or that is
+ able to get spoofed answers cached in a recursive resolver, can
+ potentially cause clients to connect to any server chosen by the
+ attacker. In the absence of a secure DNS option, clients SHOULD
+ check that the target FQDN returned in the SRV record matches the
+ original service domain that was queried. If the target FQDN is not
+ in the queried domain, clients SHOULD verify with the user that the
+ SRV target FQDN is suitable for use before executing any connections
+ to the host. Alternatively, if TLS is being used for the service,
+ clients MUST use the procedure outlined in Section 6 of [RFC6125] to
+ verify the service. When the target FQDN does not match the original
+ service domain that was queried, clients MUST check the SRV-ID
+ identifier in the server's certificate. If the FQDN does match,
+ clients MUST check any SRV-ID identifiers in the server's certificate
+ or, if no SRV-ID identifiers are present, MUST check the DNS-ID
+ identifiers in the server's certificate.
+
+ Implementations of TLS [RFC5246], used as the basis for TLS
+ ([RFC2818]), typically support multiple versions of the protocol as
+ well as the older SSL (Secure Sockets Layer) protocol. Because of
+ known security vulnerabilities, clients and servers MUST NOT request,
+ offer, or use SSL 2.0. See Appendix E.2 of [RFC5246] for further
+ details.
+
+9. IANA Considerations
+
+9.1. Well-Known URI Registrations
+
+ This document defines two ".well-known" URIs using the registration
+ procedure and template from Section 5.1 of [RFC5785].
+
+
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 9]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+9.1.1. caldav Well-Known URI Registration
+
+ URI suffix: caldav
+
+ Change controller: IETF
+
+ Specification document(s): This RFC
+
+ Related information: See also [RFC4791].
+
+9.1.2. carddav Well-Known URI Registration
+
+ URI suffix: carddav
+
+ Change controller: IETF
+
+ Specification document(s): This RFC
+
+ Related information: See also [RFC6352].
+
+9.2. Service Name Registrations
+
+ This document registers four new service names as per [RFC6335]. Two
+ are defined in this document, and two are defined in [RFC6352],
+ Section 11.
+
+9.2.1. caldav Service Name Registration
+
+ Service Name: caldav
+
+ Transport Protocol(s): TCP
+
+ Assignee: IESG <iesg@ietf.org>
+
+ Contact: IETF Chair <chair@ietf.org>
+
+ Description: Calendaring Extensions to WebDAV (CalDAV) - non-TLS
+
+ Reference: [RFC6764]
+
+ Assignment Note: This is an extension of the http service. Defined
+ TXT keys: path=<context path>
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 10]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+9.2.2. caldavs Service Name Registration
+
+ Service Name: caldavs
+
+ Transport Protocol(s): TCP
+
+ Assignee: IESG <iesg@ietf.org>
+
+ Contact: IETF Chair <chair@ietf.org>
+
+ Description: Calendaring Extensions to WebDAV (CalDAV) - over TLS
+
+ Reference: [RFC6764]
+
+ Assignment Note: This is an extension of the https service. Defined
+ TXT keys: path=<context path>
+
+9.2.3. carddav Service Name Registration
+
+ Service Name: carddav
+
+ Transport Protocol(s): TCP
+
+ Assignee: IESG <iesg@ietf.org>
+
+ Contact: IETF Chair <chair@ietf.org>
+
+ Description: vCard Extensions to WebDAV (CardDAV) - non-TLS
+
+ Reference: [RFC6352]
+
+ Assignment Note: This is an extension of the http service. Defined
+ TXT keys: path=<context path>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 11]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+9.2.4. carddavs Service Name Registration
+
+ Service Name: carddavs
+
+ Transport Protocol(s): TCP
+
+ Assignee: IESG <iesg@ietf.org>
+
+ Contact: IETF Chair <chair@ietf.org>
+
+ Description: vCard Extensions to WebDAV (CardDAV) - over TLS
+
+ Reference: [RFC6352]
+
+ Assignment Note: This is an extension of the https service. Defined
+ TXT keys: path=<context path>
+
+10. Acknowledgments
+
+ This specification was suggested by discussion that took place within
+ the Calendaring and Scheduling Consortium's CalDAV Technical
+ Committee. The author thanks the following for their contributions:
+ Stuart Cheshire, Bernard Desruisseaux, Eran Hammer-Lahav, Helge Hess,
+ Arnaud Quillaud, Wilfredo Sanchez, and Joe Touch.
+
+11. References
+
+11.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+ Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
+ Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+ [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
+ Leach, P., Luotonen, A., and L. Stewart, "HTTP
+ Authentication: Basic and Digest Access Authentication",
+ RFC 2617, June 1999.
+
+ [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
+ specifying the location of services (DNS SRV)", RFC 2782,
+ February 2000.
+
+ [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
+
+
+
+
+
+Daboo Standards Track [Page 12]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+ [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
+ Distributed Authoring and Versioning (WebDAV)
+ Access Control Protocol", RFC 3744, May 2004.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+ Resource Identifier (URI): Generic Syntax", STD 66,
+ RFC 3986, January 2005.
+
+ [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
+ "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
+ March 2007.
+
+ [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246, August 2008.
+
+ [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
+ October 2008.
+
+ [RFC5397] Sanchez, W. and C. Daboo, "WebDAV Current Principal
+ Extension", RFC 5397, December 2008.
+
+ [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
+ Uniform Resource Identifiers (URIs)", RFC 5785,
+ April 2010.
+
+ [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto'
+ URI Scheme", RFC 6068, October 2010.
+
+ [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
+ Verification of Domain-Based Application Service Identity
+ within Internet Public Key Infrastructure Using X.509
+ (PKIX) Certificates in the Context of Transport Layer
+ Security (TLS)", RFC 6125, March 2011.
+
+ [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
+ Cheshire, "Internet Assigned Numbers Authority (IANA)
+ Procedures for the Management of the Service Name and
+ Transport Protocol Port Number Registry", BCP 165,
+ RFC 6335, August 2011.
+
+ [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 6352, August 2011.
+
+ [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service
+ Discovery", RFC 6763, February 2013.
+
+
+
+Daboo Standards Track [Page 13]
+
+RFC 6764 SRV for CalDAV & CardDAV February 2013
+
+
+11.2. Informative References
+
+ [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
+ Core Object Specification (iCalendar)", RFC 5545,
+ September 2009.
+
+Author's Address
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: cyrus@daboo.name
+ URI: http://www.apple.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 14]
+