draft-ietf-webdav-protocol-04.txt   draft-ietf-webdav-protocol-05.txt 
WEBDAV Working Group Y. Y. Goland, Microsoft WEBDAV Working Group Y. Y. Goland, Microsoft
INTERNET-DRAFT E. J. Whitehead, Jr., U.C. Irvine
<draft-ietf-webdav-protocol-04> A. Faizi, Netscape INTERNET DRAFT E.J. Whitehead, Jr., UC Irvine
S. R Carter, Novell <draft-ietf-webdav-protocol-05> A. Faizi, Netscape
S.R. Carter, Novell
D. Jensen, Novell D. Jensen, Novell
Expires April 20, 1998 October 12, 1997 Expires April, 1998 November 19, 1997
Extensions for Distributed Authoring and Versioning Extensions for Distributed Authoring on the World Wide Web -- WEBDAV
on the
World Wide Web -- WEBDAV
Status of this Memo Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its documents of the Internet Engineering Task Force (IETF), its areas,
areas, and its working groups. Note that other groups may also and its working groups. Note that other groups may also distribute
distribute working documents as Internet-Drafts. working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or made obsolete by other months and may be updated, replaced, or made obsolete by other
documents at any time. It is inappropriate to use Internet-Drafts documents at any time. It is inappropriate to use Internet-Drafts as
as reference material or to cite them other than as "work in reference material or to cite them other than as "work in progress".
progress".
To learn the current status of any Internet-Draft, please check To learn the current status of any Internet-Draft, please check the
the "1id-abstracts.txt" listing contained in the Internet-Drafts "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
(Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
Coast), or ftp.isi.edu (US West Coast). ftp.isi.edu (US West Coast).
Distribution of this document is unlimited. Please send comments Distribution of this document is unlimited. Please send comments to
to the Distributed Authoring and Versioning (WEBDAV) working the Distributed Authoring and Versioning (WEBDAV) working group at
group at <w3c-dist-auth@w3.org>, which may be joined by sending a <w3c-dist-auth@w3.org>, which may be joined by sending a message
message with subject "subscribe" to <w3c-dist-auth- with subject "subscribe" to <w3c-dist-auth-request@w3.org>.
request@w3.org>.
Discussions of the WEBDAV working group are archived at Discussions of the WEBDAV working group are archived at
<URL:http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth>. <URL:http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth>.
Abstract Abstract
This Document specifies a set of methods and content-types This document specifies a set of methods, headers, and content-types
ancillary to HTTP/1.1 for the management of resource properties, ancillary to HTTP/1.1 for the management of resource properties,
simple name space manipulation, simple resource locking creation and management of resource collections, namespace
(collision avoidance) and resource version control. manipulation, resource locking (collision avoidance), and efficient
transmission of resource changes.
Table of Contents Changes
Abstract
1 Terminology
2 Data Model and Methods for DAV Properties
2.1 Introduction
2.1.1 The DAV Property
2.1.2 Existing Metadata Proposals
2.1.3 Properties and HTTP Headers
2.2 A Property Model for HTTP Resources
2.2.1 Overview
2.2.2 Property Namespace
2.3 Schemas
2.3.1 PropSchema XML Element
2.3.2 DTD XML Element
2.3.3 DefinedProps XML Element
2.3.4 PropEntries XML Element 1.1. Changes since draft-ietf-webdav-protocol-04.txt
2.3.5 Live XML Element
2.4 DAV Schema
2.4.1 DAV Property
2.4.2 Level XML Element
2.4.3 Prop XML element
2.4.4 PropLoc XML Attribute
2.4.5 Example
2.5 Property Identifiers
2.5.1 Problem Definition
2.6 Link XML Element
2.6.1 Problem Description
2.6.2 Solution Requirements
2.6.3 Link XML Element
2.6.4 Src XML Element
2.6.5 Dst XML Element
2.6.6 Example
2.7 Multi-Status Response
2.7.1 Problem Definition
2.7.2 Solution Requirements
2.7.3 Multi-Status Response
2.8 Properties and Methods
2.8.1 DELETE
2.8.2 GET
2.8.3 PROPPATCH
2.8.4 PUT
2.8.5 PROPFIND
3 A Proposal for Collections of Web Resources and Name Space
Operations
3.1 Observations on the HTTP Object Model
3.1.1 Collection Resources
3.1.2 Creation and Retrieval of Collection
Resources
3.1.3 Source Resources and Output Resources
3.2 MKCOL Method
3.2.1 Problem Description
3.2.2 Solution Requirements
3.2.3 Request
3.2.4 Response
3.2.5 Example
3.3 Standard DAV Properties
3.3.1 IsCollection Property
3.3.2 DisplayName Property
3.3.3 CreationDate Property
3.3.4 GETentity Property
3.3.5 INDEXentity Property
3.3.6 Content-Type XML Element
3.3.7 Content-Length XML Element
3.3.8 Content-Language XML Element
3.3.9 Last-Modified XML Element
3.3.10 Etag XML Element
3.4 INDEX Method
3.4.1 Problem Description
3.4.2 Solution Requirements
3.4.3 The Request
3.4.4 The Response
3.4.5 ResInfo XML Element
3.4.6 Members XML Element
3.4.7 Href XML Element
3.4.8 Example
3.5 Behavior of RFC 2068 Methods on Collections
3.5.1 GET, HEAD for Collections
3.5.2 POST for Collections
3.5.3 PUT for Collections
3.5.4 DELETE for Collections
3.5.5 DELETE Method for Non-Collection [Editor's note: This section will not appear in the final form of
Resources this document. Its purpose is to provide a concise list of changes
3.6 COPY Method from the previous revision of the draft for use by reviewers.]
3.6.1 Problem Description
3.6.2 Solution Requirements
3.6.3 The Request
3.6.4 The Response
3.6.5 Examples
3.7 MOVE Method
3.7.1 Problem Description
3.7.2 Solution Requirements
3.7.3 The Request
3.7.4 The Response
3.7.5 Examples
3.8 ADDREF Method
3.8.1 Problem Definition
3.8.2 Solution Requirements
3.8.3 The Request
3.8.4 Example
3.9 DELREF Method
3.9.1 Problem Definition
3.9.2 Solution Requirements
3.9.3 The Request
3.9.4 Example
3.10 PATCH Method
3.10.1 Problem Definition
3.10.2 Solution Requirements
3.10.3 The Request
3.10.4 text/xml elements for PATCH
3.10.5 The Response
3.10.6 Examples
3.11 Headers
3.11.1 Destination Header
3.11.2 Enforce-Live-Properties Header
3.11.3 Overwrite Header
3.11.4 Destroy Header
3.11.5 Collection-Member Header
3.12 Links
3.12.1 Source Link Property Type
4 State Tokens
4.1 Overview
4.1.1 Problem Description
4.1.2 Solution Requirements
4.2 State Token Syntax
4.3 State Token Conditional Headers
4.3.1 If-State-Match
4.3.2 If-None-State-Match
4.4 State Token Header
4.5 E-Tag
5 Locking
5.1 Locking: Introduction
5.1.1 Exclusive Vs. Shared Locks
5.1.2 Required Support
5.2 LOCK Method
5.2.1 Operation
5.2.2 The Effect of Locks on Properties and
Containers
5.2.3 Locking Replicated Resources
5.2.4 Locking Multiple Resources
5.2.5 Interaction with other Methods
5.2.6 Lock Compatibility Table
5.2.7 Status Codes
5.2.8 Lock-Info Request Header
5.2.9 Owner Request Header
5.2.10 Time-Out Header
5.2.11 Lock Response
5.2.12 Example - Simple Lock Request Added this change section.
5.2.13 Example - Multi-Resource Lock Request
5.3 Write Lock
5.3.1 Methods Restricted by Write Locks
5.3.2 Write Locks and Properties
5.3.3 Write Locks and Null Resources
5.3.4 Write Locks and Collections
5.3.5 Write Locks and COPY/MOVE
5.3.6 Re-issuing Write Locks
5.3.7 Write Locks and The State-Token Header
5.4 Lock Tokens
5.4.1 Problem Description
5.4.2 Lock Token Introduction
5.4.3 Generic Lock Tokens
5.4.4 OpaqueLockToken Lock Token
5.5 UNLOCK Method
5.5.1 Problem Definition
5.5.2 Example
5.6 Discovery Mechanisms
5.6.1 Lock Capability Discovery
5.6.2 Active Lock Discovery
6 Version Control
7 Internationalization Support
8 Security Considerations
9 Copyright
10 Acknowledgements
11 References
12 Authors' Addresses
1 Terminology Removed scoping for namespaces so the namespace for
every element is explicitly stated.
Collection - A resource that contains member resources. Changed the syntax from <?XML:Namespace.../> to <?namespace...?>.
Member Resource - a resource referred to by a collection. There Removed propfindresult, this was left over from the old search
are two types of member resources: external and internal. format.
Internal Member Resource - the name given to a member resource of Changed all the DAV XML element names to lower case.
a collection whose URI is relative to the URI of the collection.
External Member Resource - a member resource with an absolute URI Changed the property format to use Name and Namespace rather than
that is not relative to its parentís URI. name and schema.
Properties - A set of name/value pairs that contain descriptive Removed proploc attribute and removed section on GETting, DELETEing,
information about a resource. and PUTing properties since we do not provide a mechanism for
getting a URI for properties. Also removed the requirement that
properties be URI addressable.
Live Properties - Properties whose semantics and syntax are Removed quoted string choice from owner header, it is just XML.
enforced by the server. For example, a live "read-only" property
that is enforced by the server would disallow PUTs to the
associated resource.
Dead properties - Properties whose semantics and syntax are not Made all the HTTP error codes use the same format.
enforced by the server. A dead "read-only" property would not be
enforced by the server and thus would not be used by the server
as a reason to disallow a PUT on the associated resource.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL Changed the name of the create element in PROPPATCH to set, the new
NOT", "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and name seems to cause less confusion.
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119 [Bradner, 1997].
2 Data Model and Methods for DAV Properties Moved all headers in the draft to a single section.
2.1 Introduction Deleted the state token section of the draft and moved the state
token headers to the header section of the draft. Removed the state
token header.
2.1.1 The DAV Property Changed the write lock section to state that a Lock-Token request
header, not a state-token request header, is to be submitted on
request for write locked resources.
Properties are pieces of data that describe the state of a Created a "generic" XML element section for XML elements that get
resource. Properties are data about data. The term property is repeatedly re-used throughout the spec. I moved LINK XML element to
used within this specification to disambiguate the concept from this section.
the overloaded terms "metadata" and "attribute".
Properties are used within distributed authoring environments to Made multistatus and Schema discovery their own level one sections.
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.
2.1.2 Existing Metadata Proposals Collected all the properties together.
Properties have a long played an essential role in the Removed all references to the possibility of properties have their
maintenance of large document repositories, and many current own URIs. This includes removing the property identifier section.
proposals contain some notion of a property. These include PICS
[Miller et al., 1996], PICS-NG, the Rel/Rev draft [Maloney,
1996], Web Collections, XML [Bray, Sperberg-McQueen, 1997],
several proposals on representing relationships within HTML,
digital signature manifests (DCMF), and a position paper on Web
metadata architecture [Berners-Lee, 1997].
Some proposals come from a digital library perspective. These Separated the section on web collections and namespaces into two
include the Dublin Core [Weibel et al., 1995] metadata set and separate sections.
the Warwick Framework [Lagoze, 1996], a container architecture
for different metadata schemas. The literature includes many
examples of metadata, including MARC [MARC, 1994], a
bibliographic metadata format, RFC 1807 [Lasher, Cohen, 1995], a
technical report bibliographic format employed by the Dienst
system, and the proceedings from the first IEEE Metadata
conference describe many community-specific metadata sets.
Participants of the 1996 Metadata II Workshop in Warwick, UK Collected all the new response codes together into their own
[Lagoze, 1996], noted that, "new metadata sets will develop as section.
the networked infrastructure matures" and "different communities
will propose, design, and be responsible for different types of
metadata." These observations can be corroborated by noting that
many community-specific sets of metadata already exist, and there
is significant motivation for the development of new forms of
metadata as many communities increasingly make their data
available in digital form, requiring a metadata format to assist
data location and cataloging.
2.1.3 Properties and HTTP Headers Changed the XML multiresponse element name to multistatus.
Properties already exist, in a limited sense, within HTTP through Added a stand alone section on levels of DAV compliance. I also went
the use of message headers. However, in distributed authoring method by method, property by property, to specify compliance
environments a relatively large number of properties are needed requirements.
to describe the state of a resource, and setting/returning them
all through HTTP headers is inefficient. Thus a mechanism is
needed which allows a principal to identify a set of properties
in which the principal is interested and to then set or retrieve
just those properties.
2.2 A Property Model for HTTP Resources Added an introduction.
2.2.1 Overview Changed all the "True" and "False" to "T" and "F".
The DAV property model is based on name/value doubles. The name Altered the first two paragraphs of the Property Names section to
of a property identifies the property's syntax and semantics, and make the relationship between a property's name and its schema a
provides an address with which to refer to a property. The name little clearer. I also added some text in the same section defining
and value of a property is expressed as a well-formed XML a property name as a namespace and element.
element, where the name of the property is the name of the XML
element, and the value of the property MUST be either blank, or a
well-formed XML element value.
2.2.2 Property Namespace Added a second paragraph to property model for http resources -
overview. This paragraph clarifies why XML was chosen.
2.2.2.1 Problem Definition Added a 409 Conflict error to move to cover attempts to move a
collection with members.
The requirement is to be able to associate a value with a Changed the collection requirement to read the collections SHOULD
property name on a resource. It must be possible to associate a end with "/". Also added a SHOULD about returning a location header
URL with the property name. if the client submits a URL for a collection without a trailing "/".
2.2.2.2 Solution Requirement Moved the owner header into the body due to size concerns.
Ideally a property namespace should work well with extant Replaced the iscollection xml element with resourcetype.
property implementations as well as database systems. The DAV
property namespace has been specified with the following two
facts in mind:
∑ Namespaces associated with flat file systems are ubiquitous.
∑ The majority of databases use a fixed schema mechanism.
The last point makes efficient implementation of hierarchical
properties difficult. Specifically, each property has a random
set of children; the best a relational database can do is provide
a table with name and value, where the value is a series of
indexes into other tables and each index represents a specific
value. However most RDBS do not provide for table pointers, only
index values. Such a system would have to be jury-rigged to
handle table pointers. In addition, indexing systems are
optimized for a small set of relatively large tables;
hierarchical property systems tend toward many properties, each
with different numbers and types of children, thus potentially
requiring a table for each child.
It would seem best to implement a flat property namespace, Moved the DAV property to the DAV header that is returned with
inducing a natural isomorphism between DAV and most native file OPTIONS.
systems. Adopting such a model will not restrict RDBS from taking
full advantage of their search facilities.
However, it seems that future trends might be toward hierarchical Folded the tree draft into this draft. Changed the DELETE, COPY,
properties. Therefore, DAV requirements [Slein et al.] stipulate and MOVE sections to include their effect on collections as taken
that the design of the flat property system MUST be such that it from the tree draft. Created a Depth header section and put in the
will be possible to add true hierarchical properties later general rules that were in the introduction to the tree draft. I
without breaking downlevel clients. Specifically, a flat client also added the 102 response and response-status header.
MUST be able to speak to a hierarchical server and a hierarchical
client MUST be able to speak to a flat server. Worst case either
way MUST be that the request fails.
2.2.2.3 Property Names Removed the versioning section.
A property name identifies both the syntax and semantics of the Put all the methods into a single section.
property's value. It is critical that property names do not
collide, e.g., two principals defining the same property name
with two different meanings.
The URI framework provides a mechanism to prevent namespace Replaced the PROPFIND request body with a propfind header. Now the
response can be cached just using vary.
collision and for varying degrees of administrative control. Nuked resinfo for INDEX and combined it with multistatus which is
Rather than reinvent these desirable features, DAV properties now used for both INDEX and PROPFIND. Stripped down INDEX as
make use of them by requiring that all DAV property names MUST be agreed.
URIs. Since a property is also an XML element, the name of the
XML element is a URI.
The property namespace is flat, that is, it is not possible to Removed the problem definition and proposed solution sections. We
string together a series of property names in order to refer to a can always cut and paste them together from the older version if we
hierarchy of properties. Thus it is possible to refer to a feel we need them but this draft is supposed to be a dry run for
property B but not a property A/B, where A is also a property last call and last call documents do not have problem
defined on the resource. definition/proposed solution sections.
Finally, it is not possible to define the same property twice as Killed the section on schema discovery, it is controversial and we
this would cause a collision in the resource's property aren't going to be able to require it. We should specify it in a
namespace. different spec.
2.3 Schemas Added a section on notational conventions used within the document.
A schema is a group of property names and XML elements. Moved the terminology section to the end of the document to provide
better flow from the high-level introduction to the specific
introduction sections.
Schema discovery is used to determine if a system supports a Increased the numeric value of the 4xx status codes introduced in
group of properties or XML elements. A property does not this specification to avoid conflicts with the new revision of the
necessarily contain sufficient information to identify any HTTP/1.1 specification, which introduces two new 4xx status codes.
schema(s) to which it may belong.
As with property names, schemas MUST use URIs as their names. Wrote internationalization concerns section.
A resource declares its support for a schema by defining a Added XML version number to all examples.
property whose name is the same as the schema's. The property
SHOULD contain the PropSchema XML element.
2.3.1 PropSchema XML Element Contents
Name: http://www.ietf.org/standards/dav/PropSchema STATUS OF THIS MEMO...................................................1
Purpose: To provide information about properties ABSTRACT..............................................................1
Schema: http://www.ietf.org/standards/dav/ CHANGES...............................................................1
Parent: Any
Values= [DTD] [DefinedProps]
Description:This property contains the definition of the schema.
This definition consists of two parts. A DTD element that
contains a DTD that declares all XML elements and DefinedProps
that defines any properties associated with the schema. As with
all XML it is possible to add extra XML elements. Therefore
schemas may define extra XML elements which are to be included
with their values.
2.3.2 DTD XML Element 1.1. Changes since draft-ietf-webdav-protocol-04.txt..................1
CONTENTS..............................................................5
2. INTRODUCTION.......................................................8
3. DATA MODEL FOR RESOURCE PROPERTIES.................................9
3.1. The Resource Property Model......................................9
3.2. Existing Metadata Proposals.....................................10
3.3. Properties and HTTP Headers.....................................10
3.4. Property Values.................................................10
Name: http://www.ietf.org/standards/dav/DTD 3.5. Property Names..................................................11
Purpose: To contain the DTD for XML elements associated with the 4. COLLECTIONS OF WEB RESOURCES......................................11
schema. 4.1. Collection Resources............................................11
Schema: http://www.ietf.org/standards/dav/ 4.2. Creation and Retrieval of Collection Resources..................12
Parent: Any 4.3. HTTP URL Namespace Model........................................13
Values: XML Declaration statements 4.4. Source Resources and Output Resources...........................13
5. LOCKING...........................................................14
2.3.3 DefinedProps XML Element 5.1. Exclusive Vs. Shared Locks......................................14
5.2. Required Support................................................15
5.3. Lock Tokens.....................................................16
5.4. opaquelocktoken Lock Token URI Scheme...........................16
5.5. Lock Capability Discovery.......................................16
5.6. Active Lock Discovery...........................................17
6. WRITE LOCK........................................................17
6.1. Methods Restricted by Write Locks...............................17
Name: http://www.ietf.org/standards/dav/DefinedProps 6.2. Write Locks and Properties......................................17
Purpose: To contain a list of properties defined by the schema. 6.3. Write Locks and Null Resources..................................17
Schema: http://www.ietf.org/standards/dav/ 6.4. Write Locks and Collections.....................................18
Parent: Any 6.5. Write Locks and COPY/MOVE.......................................18
Values= 1*PropEntries 6.6. Re-issuing Write Locks..........................................18
6.7. Write Locks and The Lock-Token Request Header...................18
7. NOTATIONAL CONVENTIONS............................................19
2.3.4 PropEntries XML Element 8. HTTP METHODS FOR DISTRIBUTED AUTHORING............................19
8.1. PROPFIND........................................................19
8.2. PROPPATCH.......................................................23
8.3. MKCOL Method....................................................25
8.4. INDEX Method....................................................26
8.5. DELREF Method...................................................28
8.6. ADDREF Method...................................................28
8.7. GET, HEAD for Collections.......................................29
Name: http://www.ietf.org/standards/dav/PropEntries 8.8. POST for Collections............................................29
Purpose: To contain the name of a defined property, the DTD of 8.9. DELETE..........................................................29
its value, and its live/dead status. 8.10. PUT............................................................31
Schema: http://www.ietf.org/standards/dav/
Parent: DefinedProps
Values= Prop [DTD] [Live]
Description:Prop contains the name of the property. The DTD
contains the DTD of the property's value. Live, if defined,
indicates that the property has semantics and syntax that are
enforced by the server.
2.3.5 Live XML Element 8.11. COPY Method....................................................31
8.12. MOVE Method....................................................35
8.13. LOCK Method....................................................38
Name: http://www.ietf.org/standards/dav/Live 8.14. UNLOCK Method..................................................42
Purpose: If present this indicates the server MUST enforce the 8.15. PATCH Method...................................................43
syntax and semantics of the property. 9. DAV HEADERS.......................................................47
Schema: http://www.ietf.org/standards/dav/ 9.1. Collection-Member Header........................................47
Parent: PropEntries 9.2. DAV Header......................................................47
9.3. Depth Header....................................................47
9.4. Destination Header..............................................48
9.5. Destroy Header..................................................48
2.4 DAV Schema 9.6. Enforce-Live-Properties Header..................................49
9.7. If-None-State-Match.............................................49
9.8. If-State-Match..................................................50
9.9. Lock-Info Request Header........................................50
9.10. Lock-Token Request Header......................................51
9.11. Lock-Token Response Header.....................................51
9.12. Overwrite Header...............................................52
The DAV Schema is specified as 9.13. Propfind Request Header........................................52
http://www.ietf.org/standards/dav/. This schema is used to 9.14. Status-URI Response Header.....................................52
indicate support for 9.15. Timeout Header.................................................52
∑ properties that may be defined on a resource and 10. RESPONSE CODE EXTENSIONS TO RFC 2068.............................54
∑ XML elements that may be returned in responses. 10.1. 102 Processing.................................................54
10.2. 207 Multi-Status...............................................54
10.3. 418 Unprocessable Entity.......................................54
10.4. 419 Insufficient Space on Resource.............................54
2.4.1 DAV Property 10.5. 420 Method Failure.............................................54
11. MULTI-STATUS RESPONSE............................................54
11.1. multistatus XML Element........................................55
11.2. response XML Element...........................................55
11.3. status XML Element.............................................55
11.4. responsedescription XML Element................................55
12. GENERIC DAV XML ELEMENTS.........................................55
Name: http://www.ietf.org/standards/dav 12.1. href XML Element...............................................56
Purpose: Defines support for the DAV schema and protocol. 12.2. link XML Element...............................................56
Schema: http://www.ietf.org/standards/dav/ 12.3. prop XML element...............................................57
Values= PropSchema Level 13. DAV PROPERTIES...................................................57
Description:This property indicates that the resource supports 13.1. creationdate Property..........................................57
the DAV schema and protocol to the level indicated. THE VALUE IN 13.2. displayname Property...........................................57
PROPSCHEMA IS TBD, WE NEED TO PROVIDE IT IN AN APPENDIX. 13.3. get-content-language Property..................................58
13.4. get-content-length Property....................................58
2.4.2 Level XML Element 13.5. get-content-type Property......................................58
13.6. get-etag Property..............................................58
13.7. get-last-modified Property.....................................59
13.8. index-content-language Property................................59
Name: http://www.ietf.org/standards/dav/level 13.9. index-content-length Property..................................59
Purpose: To indicate the level of DAV compliance the resource 13.10. index-content-type Property...................................59
meets. 13.11. index-etag Property...........................................59
Schema: http://www.ietf.org/standards/dav/
Parent: DAV
Values= "1" | "2" | "3"
Description:A value of 1 for level indicates that the resource
supports the property and namespace sections of the DAV
specification. Level 2 indicates that the resource supports level
1 and the lock section of the specification, with a minimum
locking capability of the write lock. Level 3 indicates support
for levels 1 and 2 as well as support for the versioning section
of the DAV specification.
2.4.3 Prop XML element 13.12. index-last-modified Property..................................60
13.13. lockdiscovery Property........................................60
13.14. resourcetype Property.........................................62
13.15. Source Link Property Type.....................................62
13.16. supportedlock Property........................................63
14. DAV COMPLIANCE LEVELS............................................64
14.1. Level 1........................................................64
14.2. Level 2........................................................64
Name: http://www.ietf.org/standards/dav/prop 15. INTERNATIONALIZATION SUPPORT.....................................65
16. SECURITY CONSIDERATIONS..........................................66
17. TERMINOLOGY......................................................66
18. COPYRIGHT........................................................66
19. ACKNOWLEDGEMENTS.................................................67
20. REFERENCES.......................................................69
21. AUTHORS' ADDRESSES...............................................71
Purpose: Contains properties related to a resource. 2. Introduction
Schema: http://www.ietf.org/standards/dav/
Parent: Any
Values: XML Elements
Description:The Prop XML element is a generic container for
properties defined on resources. All elements inside Prop MUST
define properties related to the resource. No other elements may
be used inside of a Prop element.
2.4.4 PropLoc XML Attribute 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:
Name: http://www.ietf.org/standards/dav/PropLoc Properties: The ability to create, remove, and query information
Purpose: To specify the location of the associated property. about Web pages, such as its author, creation date, etc. Also, the
Schema: http://www.ietf.org/standards/dav/ ability to link pages of any media type to related pages.
Values= URL
Description:This attribute is used with elements inside of Props
contained in responses to specify the URL of the property on the
associated resource. The PropLoc attribute MUST NOT be used in
requests.
2.4.5 Example Collections: The ability to create sets of related documents, and to
receive a listing of pages at a particular hierarchy level (like a
directory listing in a file system).
<?XML:Namespace href="http://www.ietf.org/standards/dav/" Locking: The ability to keep more than one person from working on a
AS="D"/> document at the same time. This prevents the "lost update problem"
<?XML:Namespace href="AIIM:Dublin:" AS="A"/> in which modifications are lost as first one author, then another
<D:Prop> writes their changes without merging the other author's changes
<A:Author
D:PropLoc="http://www.foo.com/resource/props/Author">
Larry Masinter
</A:Author>
</D:Prop>
The previous specifies that the property author exists on some Namespace Operations: The ability to copy and move Web resources
unspecified resource and that the property can be directly
referenced at http://www.foo.com/resource/props/Author. The
resource upon which the property is defined must be determined
from context.
2.5 Property Identifiers Efficient Update: The ability to send changes which are proportional
to the size of the change rather than retransmitting the entire
resource.
2.5.1 Problem Definition 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" [Slein et al., 1997].
DAV properties are resources and thus may have a URI where the The sections below provide a detailed introduction to resource
value of an instance of the property may be retrieved. This URI properties (Section 3), collections of resources (Section 4), and
is separate from the URI name of the property, which identifies locking operations (Section 5). These sections introduce the
the syntax and semantics of the property, but which does not give abstractions manipulated by the WebDAV-specific HTTP methods
information on how to access the value of an instance of the described in Section 8, "HTTP Methods for Distributed Authoring".
property.
A server is free to assign whatever URI it chooses to identify an In HTTP/1.1, method parameter information was exclusively encoded in
instance of a property defined on a resource. In fact, a server HTTP headers. Unlike HTTP/1.1, WebDAV, encodes method parameter
is free not to reveal the URI of an instance of a particular information either in an Extensible Markup Language (XML) [Bray,
resource and instead require that the client access the property Sperberg-McQueen, 1997] request entity body, or in an HTTP header.
through PROPFIND and PROPPATCH. However, many servers will want The use of XML to encode method parameters was motivated by the
to allow clients to directly manipulate properties. On these ability to add extra XML elements to existing structures, providing
servers, a client can discover the URI of an instance of a extensibility, and by XML's ability to encode information in ISO
property by performing a PROPFIND and examining the PropLoc 10646 character sets, providing internationalization support. As a
attribute, if returned, of each property. rule of thumb, parameters are encoded in XML entity bodies when they
have unbounded length, or when they may be shown to a human user and
hence require encoding in an ISO 10646 character set. Otherwise,
parameters are encoded within an HTTP header. Section 9 describes
the new HTTP headers used with WebDAV methods.
2.6 Link XML Element 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. XML elements used in this specification are defined in
Section 12.
2.6.1 Problem Description While the response codes provided by HTTP/1.1 are sufficient to
describe the preponderance of error conditions encountered by WebDAV
methods, there are some errors that do not fall neatly into the
existing categories. New status codes developed for the WebDAV
methods are defined in Section 10. Since some WebDAV methods may
operate over many resources, the multiresponse status type has been
introduced to return status information for multiple resources.
Multiresponse status is described in Section 11.
A mechanism is needed to associate resources with other The properties mechanism is employed by WebDAV to store information
resources. These associations, known as links, consist of three about the current state of the resource. For example, when a lock
values, a type describing the nature of the association, the is taken out on a resource, a lock information property describes
source of the link, and the destination of the link. In the case the current state of the lock. Section 13 defines the properties
of annotation, neither the source nor the destination of a link used within the WebDAV specification.
need be the resource upon which the link is recorded.
2.6.2 Solution Requirements Finishing off the specification are sections on what it means to be
compliant with this specification (Section 14), on
internationalization support (Section 15), and on security (Section
16).
The association mechanism MUST make use of the DAV property 3. Data Model for Resource Properties
mechanism in order to make the existence of the associations
searchable.
2.6.3 Link XML Element 3.1. The Resource Property Model
Name: http://www.ietf.org/standards/dav/link Properties are pieces of data that describe the state of a resource.
Purpose: To identify a property as a link and to contain the Properties are data about data.
source and destination of that link.
Schema: http://www.ietf.org/standards/dav/
Values= 1*Src 1*Dst
Description:Link is used to provide the sources and destinations
of a link. The type of the property containing the Link XML
element provides the type of the link. Link is a multi-valued
element, so multiple Links may be used together to indicate
multiple links with the same type.
2.6.4 Src XML Element 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.
Name: http://www.ietf.org/standards/dav/src The DAV property model consists of name/value pairs. The name of a
Purpose: To indicate the source of a link. property identifies the property's syntax and semantics, and
Schema: http://www.ietf.org/standards/dav/ provides an address by which to refer to that syntax and semantics.
Parent: http://www.ietf.org/standards/dav/link
Values= URI
2.6.5 Dst XML Element There are two categories of properties: "live" and "non-live". A
live property has its syntax and semantics enforced by the server.
This represents the two cases of a) the value of a property is read-
only, maintained by the server, and b) the value of the property is
maintained by the client, but server performs syntax checking on
submitted values. A non-live property has its syntax and semantics
enforced by the client; the server merely records the value of the
property verbatim.
Name: http://www.ietf.org/standards/dav/Dst 3.2. Existing Metadata Proposals
Purpose: To indicate the destination of a link
Schema: http://www.ietf.org/standards/dav/
Parent: http://www.ietf.org/standards/dav/link
Values= URI
2.6.6 Example Properties have long played an essential role in the maintenance of
large document repositories, and many current proposals contain some
notion of a property, or discuss web metadata more generally. These
include PICS [Miller et al., 1996], PICS-NG, the Rel/Rev draft
[Maloney, 1996], Web Collections, XML [Bray, Sperberg-McQueen,
1997], several proposals on representing relationships within HTML,
digital signature manifests (DCMF), and a position paper on Web
metadata architecture [Berners-Lee, 1997]. Work on PICS-NG and Web
Collections has been subsumed by the Resource Definition Framework
(RDF) metadata activity of the World Wide Web Consortium, which
consists of a network-based data model and an XML representation of
that model.
<?XML:Namespace Some proposals come from a digital library perspective. These
href = "http://www.ietf.org/standards/dav/" AS = "D"/> include the Dublin Core [Weibel et al., 1995] metadata set and the
<?XML:Namespace Warwick Framework [Lagoze, 1996], a container architecture for
href = "http://www.foocorp.com/Project/" AS = "F"/> different metadata schemas. The literature includes many examples
<D:Prop> of metadata, including MARC [MARC, 1994], a bibliographic metadata
<Source> format, and RFC 1807 [Lasher, Cohen, 1995], a technical report
<Link> bibliographic format employed by the Dienst system. Additionally,
<F:ProjFiles>Source</F:ProjFiles> the proceedings from the first IEEE Metadata conference describe
<src>http://foo.bar/program</src> many community-specific metadata sets.
<dst>http://foo.bar/src/main.c</dst>
</Link>
<Link>
<F:ProjFiles>Library</F:ProjFiles>
<src>http://foo.bar/program</src> Participants of the 1996 Metadata II Workshop in Warwick, UK
<dst>http://foo.bar/src/main.lib</dst> [Lagoze, 1996], noted that, "new metadata sets will develop as the
</Link> networked infrastructure matures" and "different communities will
<Link> propose, design, and be responsible for different types of
<F:ProjFiles>Makefile</F:ProjFiles> metadata." These observations can be corroborated by noting that
<src>http://foo.bar/program</src> many community-specific sets of metadata already exist, and there is
<dst>http://foo.bar/src/makefile</dst> significant motivation for the development of new forms of metadata
<Link> as many communities increasingly make their data available in
</Source> digital form, requiring a metadata format to assist data location
</D:Prop> and cataloging.
In this example the resource http://foo.bar/program has a source 3.3. Properties and HTTP Headers
property defined which contains three links. Each link contains
three elements, two of which, src and dst, are part of the DAV
schema defined in this document, and one which is defined by the
schema http://www.foocorp.com/project/ (Source, Library, and
Makefile). A client which only implements the elements in the DAV
spec will not understand the foocorp elements and will ignore
them, thus seeing the expected source and destination links. An
enhanced client may know about the foocorp elements and be able
to present the user with additional information about the links.
2.7 Multi-Status Response 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 which allows a
principal to identify a set of properties in which the principal is
interested and to then set or retrieve just those properties.
2.7.1 Problem Definition 3.4. Property Values
Some methods effect more than one resource. The effect of the The value of a property is expressed as a well-formed XML document.
method on each of the scoped resources may be different, as such
a return format that can specify the effect of the method on each
resource is needed.
2.7.2 Solution Requirements 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 new elements. Older clients will not break because they will
still have the data specified in the original schema and will ignore
elements they do not understand. XML's support for multiple
character sets allows human-readable properties to be encoded and
read in a character set familiar to the user.
The solution must: 3.5. Property Names
- communicate the status code and reason
- give the URI of the resource on which the method was invoked
- be consistent with other return body formats
2.7.3 Multi-Status Response 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.
The default multi-status response body is an text/xml HTTP entity Because a property's name is universally unique, clients can depend
that contains a single XML element called multiresponse, which upon consistent behavior for a particular property across multiple
contains a set of XML elements called response, one for each 200, resources, so long as that property is "live" on the resources in
300, 400, and 500 series status code generated during the method question.
invocation. 100 series status codes MUST NOT be recorded in a
response XML element.
2.7.3.1 MultiResponse The XML namespace mechanism, which is based on URIs, is used to name
properties because it provides a mechanism to prevent namespace
collisions and for varying degrees of administrative control.
Name: http://www.ietf.org/standards/dav/multiresponse The property namespace is flat; that is, no hierarchy of properties
Purpose: Contains multiple response messages. is explicitly recognized. Thus, if a property A and a property A/B
Schema: http://www.ietf.org/standards/dav/ exist on a resource, there is no recognition of any relationship
Parent: Any between the two properties. It is expected that a separate
Value: 1*Response [ResponseDescription] specification will eventually be produced which will address issues
Description:The ResponseDescription at the top level is used to relating to hierarchical properties.
provide a general message describing the over arching nature of
the response. If this value is available an application MAY use
it instead of presenting the individual response descriptions
contain within the responses.
2.7.3.2 Response 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.
Name: http://www.ietf.org/standards/dav/response 4. Collections of Web Resources
Purpose: Holds a single response
Schema: http://www.ietf.org/standards/dav/
Parent: Any
Value: (Prop | HREF) Status [ResponseDescription]
Description: Prop MUST contain one or more empty XML elements
representing the name of properties. Multiple properties may be
included if the same response applies to them all. If HREF is
used then the response refers to a problem with the referenced
resource, not a property.
2.7.3.3 Status This section provides a description of a new type of Web resource,
the collection, and discusses its interactions with the HTTP URL
namespace. The purpose of a collection resource is to model
collection-like objects (e.g., filesystem directories) within a
server's namespace.
Name: http://www.ietf.org/standards/dav/status All DAV compliant resources MUST support the HTTP URL namespace
Purpose: Holds a single HTTP status-line model specified herein.
Schema: http://www.ietf.org/standards/dav/
Parent: Response
Value: status-line ;status-line defined in [Fielding et al.,
1997]
2.7.3.4 ResponseDescription 4.1. Collection Resources
Name: A collection is a resource whose state consists of an unordered list
http://www.ietf.org/standards/dav/ResponseDescription of internal members, an unordered list of external members, and a
Purpose: Contains a message that can be displayed to the user set of properties. An internal member resource MUST have a URI that
explaining the nature of the response. is immediately relative to the base URI of the collection, that is,
Schema: http://www.ietf.org/standards/dav/ a relative URI in which "../" is illegal, which MUST begin with "./"
Parent: Multiresponse and/or Response and which SHOULD contain a "/" at the end of the URI if the internal
Value: Any member resource is itself a collection.
Description: This XML element provides information suitable to
be presented to a user.
2.8 Properties and Methods An external member resource MUST be an absolute URI that is not an
internal URI. Any given internal or external URI MUST only belong
to the collection once, i.e., it is illegal to have multiple
instances of the same URI in a collection. Properties defined on
collections behave exactly as do properties on non-collection
resources.
2.8.1 DELETE There is a standing convention that when a collection is referred to
by its name without a trailing slash, the trailing slash is
automatically appended. Due to this, a resource MAY accept a URI
without a trailing "/" to point to a collection. In this case it
SHOULD return a location header in the response pointing to the URL
ending with the "/". For example, if a client performs an INDEX on
http://foo.bar/blah (no trailing slash), the resource
http://foo.bar/blah/ (trailing slash) MAY respond as if the
operation were invoked on it, and SHOULD return a location header
with http://foo.bar/blah/ in it.
As properties are resources, the deletion of a property causes 4.2. Creation and Retrieval of Collection Resources
the same result as the deletion of any resource. It is worth
pointing out that the deletion of a property effects both direct
manipulation, that is by the property's URL, as well as indirect
discovery and manipulation, that is PROPPATCH and PROPFIND.
2.8.2 GET This document specifies the MKCOL method to create new collection
resources, rather than using the existing HTTP/1.1 PUT or POST
method, for the following reasons
A GET with a Request-URI that identifies a property returns the In HTTP/1.1, the PUT method is defined to store the request body at
name and value of that property. Accept types may be used to the location specified by the Request-URI. While a description
specify the format of the return value, but all DAV compliant format for a collection can readily be constructed for use with PUT,
servers MUST at minimum support a return type of text/xml. If the implications of sending such a description to the server are
text/xml is used as the response format then it MUST return the undesirable. For example, if a description of a collection that
name and value of the property using the Prop XML element. omitted some existing resources were PUT to a server, this might be
interpreted as a command to remove those members. This would extend
PUT to perform DELETE functionality, which is undesirable since it
changes the semantics of PUT, and makes it difficult to control
DELETE functionality with an access control scheme based on methods.
2.8.2.1 Example While the POST method is sufficiently open-ended that a _create a
collection_ POST command could be constructed, this is undesirable
because it would be difficult to separate access control for
collection creation from other uses of POST.
The following example assumes that the property's URL, originally This document specifies the INDEX method for listing the contents of
generated by the server, was discovered by examining the proploc a collection, rather than relying on the existing HTTP/1.1 GET
XML attribute returned on a result from a FINDPROP. method. This is to avoid conflict with the de-facto standard
practice of redirecting a GET request on a directory to its
index.html resource.
GET /bar.html;prop=z39.50_authors HTTP/1.1 The exact definition of the behavior of GET and PUT on collections
Host: foo.com is defined later in this document.
HTTP/1.1 200 OK 4.3. HTTP URL Namespace Model
Content-Type: text/xml
Content-Length: xxxx
E-tag: "1234"
Last-Modified: xxxx
<?XML:Namespace The HTTP URL Namespace is a hierarchical namespace where the
href = "http://www.ietf.org/standards/dav/" AS = "D"/> hierarchy is delimited with the "/" character. DAV compliant
<?XML:Namespace resources MUST maintain the consistency of the HTTP URL namespace.
href = "http://www.w3.com/standards/z39.50/"AS = "Z"/> Any attempt to create a resource (excepting the root member of a
<D:prop> namespace) that would not be the internal member of a collection
<Z:Authors> MUST fail. For example, if the collection http://www.foo.bar.org/a/
<Z:Author>Jane Doe</Z:Author> exists, but http://www.foo.bar.org/a/b/does not exist, an attempt to
<Z:Author>Joe Doe</Z:Author> create http://www.foo.bar.org/a/b/c must fail.
<Z:Author>Lots o'Doe</Z:Author>
</Z:Authors>
</D:prop>
2.8.3 PROPPATCH 4.4. Source Resources and Output Resources
The PROPPATCH method processes instructions specified in the For many resources, the entity returned by a GET method exactly
request body to create and/or remove properties defined on the matches the persistent state of the resource, for example, a GIF
resource identified by Request-URI. file stored on a disk. For this simple case, the URL at which a
resource is accessed is identical to the URL at which the source
(the persistent state) of the resource is accessed. This is also
the case for HTML source files that are not processed by the server
prior to transmission.
All DAV compliant servers MUST process instructions which are However, the server can sometimes process HTML resources before they
specified using the PropertyUpdate, Create, and Remove XML are transmitted as a return entity body. For example, server-side-
elements of the DAV schema. The request message body MUST include directives within an HTML file instruct a server to replace
contain at least one PropertyUpdate XML element. Instruction the directive with another value, such as the current date. In this
processing MUST occur in the order instructions are received case, what is returned by GET (HTML plus date) differs from the
(i.e., from top to bottom), and MUST be performed atomically. persistent state of the resource (HTML plus directive). Typically
there is no way to access the HTML resource containing the
unprocessed directive.
2.8.3.1 PropertyUpdate XML element Sometimes the entity returned by GET is the output of a data-
producing process that is described by one or more source resources
(that may not even have a location in the URL namespace). A single
data-producing process may dynamically generate the state of a
potentially large number of output resources. An example of this is
a CGI script that describes a "finger" gateway process that maps
part of the namespace of a server into finger requests, such as
http://www.foo.bar.org/finger_gateway/user@host.
Name: http://www.ietf.org/standards/dav/PropertyUpdate In the absence of distributed authoring capabilities, it is
Purpose: To contain a request to alter the properties on a acceptable to have no mapping of source resource(s) to the URI
namespace. In fact, preventing access to the source resource(s) has
desirable security benefits. However, if remote editing of the
source resource(s) is desired, the source resource(s) should be
given a location in the URI namespace. This source location should
not be one of the locations at which the generated output is
retrievable, since in general it is impossible for the server to
differentiate requests for source resources from requests for
process output resources. There is often a many-to-many
relationship between source resources and output resources.
On WebDAV compliant servers, for all output resources which have a
single source resource (and that source resource has a URI), the URI
of the source resource SHOULD be stored in a link on the output
resource with type http://www.ietf.org/standards/dav/source. Note
that by storing the source URIs in links on the output resources,
the burden of discovering the source is placed on the authoring
client.
5. 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. Furthermore, this document
only provides the definition of locking for one lock access type,
the write lock. However, the syntax is extensible, and permits the
eventual specification of other access types.
5.1. Exclusive Vs. Shared Locks
The most basic form of lock is an exclusive lock. This is a lock
where the access right in question is only granted to a single
principal. The need for this arbitration results from a desire to
avoid having to constantly merge results.
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 right. Shared locks are provided for this case. A
shared lock allows multiple principals to receive a lock. Hence any
principal with appropriate access can get the lock.
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 the
resource. Those who are not, don't. Among those who have access
permission to write 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 is potentially working on the
resource. resource.
Schema: http://www.ietf.org/standards/dav/
Parent: Any
Values= *(Create | Remove)
Description:This XML element is a container for the information
required to modify the properties on the resource. This XML
element is multi-valued.
2.8.3.2 Create XML element 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 is potentially working on a
resource.
Name: http://www.ietf.org/standards/dav/create Shared locks are included because experience from web distributed
Purpose: To create the DAV properties specified inside the authoring systems has indicated that exclusive write locks are often
Create XML element. too rigid. An exclusive write lock is used to enforce a particular
Schema: http://www.ietf.org/standards/dav/ editing process: take out exclusive write lock, read the resource,
Parent: http://www.ietf.org/standards/dav/PropertyUpdate perform edits, write the resource, release the lock. This editing
Values= Prop process has the problem that locks are not always properly released,
Description:This XML element MUST contain only a Prop XML for example when a program crashes, or when a lock owner leaves
element. The elements contained by Prop specify the name and without unlocking a resource. While both timeouts and
value of properties that are created on Request-URI. If a administrative action can be used to remove an offending lock,
property already exists then its value is replaced. The Prop XML neither mechanism may be available when needed; the timeout may be
element MUST NOT contain a PropLoc XML attribute. long or the administrator may not be available.
2.8.3.3 Remove XML element Despite their potential problems, exclusive write locks are
extremely useful, since often a guarantee of freedom from overwrite
conflicts is what is needed. This specification provides both
exclusive write locks and the less strict mechanism of shared locks.
Name: http://www.ietf.org/standards/dav/remove 5.2. Required Support
Purpose: To remove the DAV properties specified inside the
Remove XML element.
Schema: http://www.ietf.org/standards/dav/
Parent: http://www.ietf.org/standards/dav/PropertyUpdate
Values= Prop
Description:Remove specifies 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 elements in Prop MUST be
empty, as only the names of properties to be removed are
required.
2.8.3.4 Response A WebDAV compliant server is not required to support locking in any
form. If the server does support locking it MAY choose to support
any combination of exclusive and shared locks for any access types.
The response MUST have a response body that contains a The reason for this flexibility is that locking policy strikes to
multiresponse identifying the results for each property. 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.
2.8.3.5 Response Codes 5.3. Lock Tokens
200 OK - The command succeeded. As there can be a mixture of A lock token is a URI that identifies a particular lock. A lock
Create and Removes in a body, a 201 Create seems inappropriate. token is returned by every successful LOCK operation in the lock-
403 Forbidden - The client, for reasons the server chooses not to token response header, and can also be discovered through lock
specify, can not alter one of the properties. discovery on a resource.
405 Conflict - The client has provided a value whose semantics
are not appropriate for the property. This includes trying to set
read only properties.
413 Request Entity Too Long - If a particular property is too
long to be recorded then a composite XML error will be returned
indicating the offending property.
417 Insufficient Space on Resource - The resource does not have
sufficient space to record the state of the resource after the
execution of this method.
418 Atomicity Failure - The command was not executed because of
an atomicity failure elsewhere the caused the entire command to
be aborted.
2.8.3.6 Example Lock token URIs are required to 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.
PROPPATCH /bar.html HTTP/1.1 This specification provides a lock token URI scheme called
Host: www.foo.com opaquelocktoken that meets the uniqueness requirements. However
Content-Type: text/xml resources are free to return any URI scheme so long as it meets the
Content-Length: xxxx uniqueness requirements.
<?XML:Namespace 5.4. opaquelocktoken Lock Token URI Scheme
href = "http://www.ietf.org/standards/dav/" AS = "D"/>
<?XML:Namespace
href = "http://www.w3.com/standards/z39.50/" AS = "Z"/>
<D:PropertyUpdate>
<Create>
<prop>
<Z:authors>
<Z:Author>Jim Whitehead</Z:Author>
<Z:Author>Roy Fielding</Z:Author>
</Z:authors>
</Prop>
</Create>
<Remove>
<prop><Z:Copyright-Owner/></prop>
</Remove>
</D:PropertyUpdate>
HTTP/1.1 405 Conflict The opaquelocktoken URI scheme is designed to be unique across all
Content-Type: text/xml resources for all time. Due to this uniqueness quality, a client
Content-Length: xxxxx MAY submit an opaque lock token in a Lock-Token request header and
an if-state[-not]-match header on a resource other than the one that
returned it.
<?XML:Namespace All resources MUST recognize the opaquelocktoken scheme and, at
href="http://www.ietf.org/standards/dav/" AS = "D"/> minimum, recognize that the lock token was not generated by the
<?XML:Namespace resource. Note, however, that resources are not required to
href="http://www.w3.com/standards/z39.50/" AS = "Z"/> generate opaquelocktokens in LOCK method responses.
<D:MultiResponse>
<ResponseDescription> Copyright Owner can not be deleted or
altered.</ResponseDescription>
<Response>
<Prop><Z:authors/></Prop>
<Status>HTTP/1.1 418 Atomicity Failure</Status>
</Response>
<Response>
<Prop><Z:Copyright-Owner/></Prop>
<Status>HTTP/1.1 405 Conflict</Status>
</Response>
</D:MultiResponse>
2.8.4 PUT In order to guarantee uniqueness across all resources for all time
the opaquelocktoken requires the use of the GUID mechanism.
A PUT is specified in order to control what is returned by a GET. Opaquelocktoken generators, however, have a choice of how they
However a GET on a property always returns a predefined property create these tokens. They can either generate a new GUID for every
containment format. Therefore PUT can not be used if the Request- lock token they create, which is potentially very expensive, or they
URI refers to a property. can create a single GUID and then add extension characters. If the
second method is selected then the program generating the extensions
MUST guarantee that the same extension will never be used twice with
the associated GUID.
2.8.5 PROPFIND Opaque-Lock-Token = "opaquelocktoken" ":" GUID [Extension]
GUID = ; As defined in [Leach, Salz, 1997]
Extension = *urlc ;urlc is defined in [Berners-Lee et al., 1997]
(draft-fielding-url-syntax-07.txt)
The PROPFIND method retrieves properties defined on Request-URI. 5.5. Lock Capability Discovery
The request message body is an XML document that MUST contain
only one PropFind XML element, which specifies the type of
property find action to be performed. The XML element contained
by PropFind specifies the type of action to be performed:
retrieve all property names and values (AllProp), retrieve only
specified property names and values (Prop), or retrieve only a
list of all property names (Propname). When a Prop XML element
is present, it specifies a list of the names of properties whose
name and value are to be returned. The Prop element, when used
within a FINDPROP request body MUST be empty.
The response is a text/xml message body that contains a Since server lock support is optional, a client trying to lock a
MultiResponse XML element which describes the results of the resource on a server can either try the lock and hope for the best,
attempts to retrieve the various properties. If a property was or perform some form of discovery to determine what lock
successfully retrieved then its value MUST be returned in the capabilities the server supports. This is known as lock capability
prop XML element. In the case of Allprop and Findprop, if a discovery. Lock capability discovery differs from discovery of
principal does not have the right to know if a particular supported access control types, since there may be access control
property exists, an error MUST NOT be returned. The results of types without corresponding lock types. A client can determine what
this method SHOULD NOT be cached. lock types the server supports by retrieving the supportedlock
property.
2.8.5.1 Propfind XML element Any DAV compliant resource that supports the LOCK method MUST
support the supportedlock property.
Name: http://www.ietf.org/standards/dav/Propfind 5.6. Active Lock Discovery
Purpose: To specify the set of matching properties
Schema: http://www.ietf.org/standards/dav/
Parent: Any
Values= (Prop | Allprop | Propname)
Description: Propfind is a container element for the exact
specification of a PROPFIND request.
2.8.5.2 Allprop 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 lockdiscovery
property is provided. This property lists all outstanding locks,
describes their type, and provides their lock token.
Name: http://www.ietf.org/standards/dav/Allprop Any DAV compliant resource that supports the LOCK method MUST
Purpose: To specify that all properties are to be returned support the lockdiscovery property.
Schema: http://www.ietf.org/standards/dav/
Parent: Propfind
Description: Its presence in a PROPFIND request specifies the
name and value of all properties defined on the resource MUST be
returned.
2.8.5.3 Propname 6. Write Lock
Name: http://www.ietf.org/standards/dav/Propname This section describes the semantics specific to the write access
Purpose: To specify that the names of all properties defined on type for locks. The write lock is a specific instance of a lock
the resource are to be returned. type, and is the only lock type described in this specification. A
Schema: http://www.ietf.org/standards/dav/ DAV compliant resource MAY support the write lock.
Parent: Propfind
Description: Its presence in a PROPFIND request specifies the
name of all properties defined on the resource MUST be returned.
2.8.5.4 PropFindResult XML element 6.1. Methods Restricted by Write Locks
Name: http://www.ietf.org/standards/dav/PropFindResult A write lock prevents a principal without the lock from successfully
Purpose: To contain the results of a SEARCH request executing a PUT, POST, PATCH, PROPPATCH, MOVE, DELETE, MKCOL, ADDREF
Schema: http://www.ietf.org/standards/dav/ or DELREF on the locked resource. All other current methods, GET in
Parent: Any particular, function independent of the lock.
Values: Prop
2.8.5.5 Example 1 - Prop Note, however, that as new methods are created it will be necessary
to specify how they interact with a write lock.
PROPFIND /container/ HTTP/1.1 6.2. Write Locks and Properties
Host: www.foo.bar
Content-Length: xxxx
Content-Type: text/xml
<?XML:Namespace href = While those without a write lock may not alter a property on a
"http://www.ietf.org/standards/dav/" AS = "G"/> resource it is still possible for the values of live properties to
<?XML:Namespace href = change, even while locked, due to the requirements of their schemas.
"http://www.foo.bar/boxschema/" AS = "B"/> Only dead properties and live properties defined to respect locks
<G:PROPFIND> are guaranteed not to change while write locked.
<prop>
<B:bigbox>
<B:author>
<B:DingALing>
<B:Random>
</prop>
</G:PROPFIND>
HTTP/1.1 207 Multi-Response 6.3. Write Locks and Null Resources
Content-Type: text/xml
Content-Length: xxxxx
<?XML:Namespace It is possible to assert a write lock on a null resource in order to
href ="http://www.ietf.org/standards/dav/" AS = "S"> lock the name. Please note, however, that locking a null resource
<?XML:Namespace href = "http://www.foo.bar/boxschema" AS = R"> effectively makes the resource non-null, as the resource now has
<D:MultiResponse> lock related properties defined on it.
<ResponseDescription> There has been an access violation
error. </ResponseDescription>
<Response>
<Prop>
<R:bigbox D:Proploc="http://prop.com/BoxType">
<BoxType>Box type A</BoxType> 6.4. Write Locks and Collections
</R:bigbox>
<R:author D:Proploc="http://prop.com/Author">
<Name>J.J. Dingleheimerschmidt</Name>
</R:author>
</Prop>
<Status>HTTP/1.1 200 Success</Status>
</Response>
<Response>
<Prop><R:DingALing/><R:Random/></>
<Status>HTTP/1.1 403 Forbidden</Status>
<ResponseDescription> The user does not have access to
the DingALink property. </ResponseDescription>
</Response>
</D:MultiResponse>
The result will return all properties on the container. In this A write lock on a collection prevents the addition or removal of
case only two properties were found. The principal did not have members of the collection. As a consequence, when a principal
sufficient access rights to see the third and fourth properties issues a request to create a new internal member of a collection
so an error was returned. using PUT or POST, or to remove an existing internal member of a
collection using DELETE, this request MUST fail if the principal
does not have a write lock on the collection.
2.8.5.6 Example 2 - Allprop However, if a write lock request is issued to a collection
containing internal member resources that are currently locked in a
manner which conflicts with the write lock, the request MUST fail
with a 409 Conflict status code.
PROPFIND /container/ HTTP/1.1 6.5. Write Locks and COPY/MOVE
Host: www.foo.bar
Content-Length: xxxx
Content-Type: text/xml
<?XML:Namespace href = The owner of a write lock MUST NOT execute a MOVE method on a
"http://www.ietf.org/standards/dav/" AS = "G"/> resource he has locked. This specification intentionally does not
<G:PROPFIND> define what happens if a MOVE method request is made on a locked
<Allprop/> resource by the lock's owner.
</G:PROPFIND>
HTTP/1.1 200 Success A COPY method invocation MUST NOT duplicate any write locks active
on the source.
6.6. Re-issuing Write Locks
If a principal already owns a write lock on a resource, any future
requests for the same type of write lock, on the same resource,
while the principal's previous write lock is in effect, MUST result
in a successful response with the same lock token as provided for
the currently existing lock. Two lock requests are defined to be
identical if their Lock-Info headers are identical.
6.7. Write Locks and The Lock-Token Request Header
If a user agent is not required to have knowledge about a lock when
requesting an operation on a locked resource, the following scenario
might occur. 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 the lock token request header
is introduced. Please refer to the Lock Token Request Header
section for details and requirements.
6.7.1. Write Lock Token Example
COPY /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/users/f/fielding/index.html
Lock-Token: <opaquelocktoken:123AbcEfg1284h23h2>
<opaquelocktoken:AAAASDFcalkjfdas12312>
HTTP/1.1 200 OK
In this example, both the source and destination are locked so two
lock tokens must be submitted. If only one of the two resources was
locked, then only one token would have to be submitted.
7. 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 RFC
2068, _Hypertext Transfer Protocol -- HTTP/1.1_ [Fielding et al.,
1997]. Since this augmented BNF uses the basic production rules
provided in Section 2.2 of RFC 2068, these rules apply to this
document as well.
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 [Bradner,
1997].
8. HTTP Methods for Distributed Authoring
8.1. PROPFIND
The PROPFIND method retrieves properties defined on the Request-URI,
if it is a non-collection resource, or on the Request-URI and
potentially its member resources, if the resource is a collection.
All DAV compliant resources MUST support the PROPFIND method.
A client MAY submit a Depth header with a PROPFIND on a collection
with a value of "0", "1" or "infinity". DAV compliant servers MUST
support the "0", "1" and "infinity" behaviors. By default, the
PROPFIND method on a collection without a Depth header MUST act as
if a Depth = infinity header was included.
A client MUST submit a Propfind request header describing what
information is being requested. It is possible to request
particular property values, all property values, or a list of the
names of the resource's properties.
The response is a text/xml message body that contains a multistatus
XML element that describes the results of the attempts to retrieve
the various properties. If a property was successfully retrieved
then its value MUST be returned in a prop XML element. If the scope
of PROPFIND covers more than a single resource, as is the case with
Depth values of "1" and "infinity", each response XML element MUST
contain an href XML element which identifies the resource on which
the properties in the prop XML element are defined. In the case of
allprop and propname, if a principal does not have the right to know
if a particular property exists, an error MUST NOT be returned. The
results of this method SHOULD NOT be cached.
8.1.1. Example: Retrieving Named Properties
PROPFIND /files/ HTTP/1.1
Host: www.foo.bar
Depth: 0
Propfind: <http://www.foo.bar/boxschema/bigbox> <http://www.foo.bar/
boxschema/author> <http://www.foo.bar/boxschema/DingALing> <http://w
ww.foo.bar/boxschema/Random>
HTTP/1.1 207 Multi-Status
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxxxx Content-Length: xxxxx
<?XML:Namespace href = <?XML version="1.0">
"http://www.ietf.org/standards/dav/" As = "S"> <?namespace href ="http://www.ietf.org/standards/dav/" AS = "D"?>
<?XML:Namespace href = "http://www.foo.bar/boxschema" AS = R"> <?namespace href = "http://www.foo.bar/boxschema" AS = R"?>
<S:MultiResponse> <D:multistatus>
<Prop> <D:response>
<R:bigbox D:Proploc="http://prop.com/BigBox"> <D:prop>
<BoxType>Box type A</BoxType> <R:bigbox>
<R:BoxType>Box type A</R:BoxType>
</R:bigbox> </R:bigbox>
<R:author D:Proploc="http://prop.com/Author"> <R:author>
<Name>Hadrian</Name> <R:Name>J.J. Dingleheimerschmidt</R:Name>
</R:author> </R:author>
</Prop> </D:prop>
<Status>HTTP/1.1 200 Success</Status> <D:status>HTTP/1.1 200 OK</D:status>
</S:MultiResponse> </D:response>
<D:response>
<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:response>
<D:responsedescription> There has been an access violation error.
</D:responsedescription>
</D:multistatus>
This particular client only had the right to see two properties, In this example, PROPFIND is executed on the collection
BoxType and Author. No error is returned for the remaining http://www.foo.bar/files/. The specified depth is zero, hence the
properties, as the client does not even have sufficient rights to PROPFIND applies only to the collection itself, and not to any of
know they exist. If the client did have the right to know they its members. The Propfind header specifies the name of four
existed but did not have the right to see their value, a 207 properties whose values are being requested. In this case only two
multi-response with a multiresponse, as used in the previous properties were returned, since the principal issuing the request
example, would have been returned. did not have sufficient access rights to see the third and fourth
properties.
2.8.5.7 Example 3 - Propname 8.1.2. Example: Using allprop to Retrieve All Properties
PROPFIND /container/ HTTP/1.1 PROPFIND /container/ HTTP/1.1
Host: www.foo.bar Host: www.foo.bar
Content-Length: xxxx Depth: 1
Content-Type: text/xml Propfind: allprop
<?XML:Namespace
href = "http://www.ietf.org/standards/dav/" AS = "G"/>
<G:PROPFIND>
<Propname/>
</G:PROPFIND>
HTTP/1.1 200 Success HTTP/1.1 200 OK
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxxxx Content-Length: xxxxx
<?XML:Namespace <?XML version="1.0">
href = "http://www.ietf.org/standards/dav/" As = "S"> <?namespace href = "http://www.ietf.org/standards/dav/" As = "S"?>
<?XML:Namespace <?namespace href = "http://www.foo.bar/boxschema/" AS = R"?>
href = "http://www.foo.bar/boxschema" AS = "R"> <S:multistatus>
<S:MultiResponse> <S:response>
<Prop> <S:href>http://www.foo.bar/container/</S:href>
<R:bigbox D:Proploc="http://prop.com/BigBox"/> <S:prop>
<R:author D:Proploc="http://prop.com/Author"/> <R:bigbox>
<R:DingALing/> <R:BoxType>Box type A</R:BoxType>
<R:Random/> </R:bigbox>
</Prop> <R:author>
<Status>HTTP/1.1 200 Success</Status> <R:Name>Hadrian</R:Name>
</S:MultiResponse> </R:author>
</S:prop>
In this case only two of the properties have direct URLs <S:status>HTTP 1.1 200 OK</S:status>
available, while the other two properties can only be referenced </S:response>
via PROPFIND and PROPPATCH. <S:response>
<S:href>http://www.foo.bar/container/index.html</S:href>
3 A Proposal for Collections of Web Resources and Name Space <S:prop>
Operations <R:bigbox>
<R:BoxType>Box type B</R:BoxType>
3.1 Observations on the HTTP Object Model </R:bigbox>
</S:prop>
<S:status>HTTP 1.1 200 OK</S:status>
</S:response>
</S:multistatus>
In this example, PROPFIND was invoked on the resource
http://www.foo.bar/container/ with a Depth header of 1, meaning the
request applies to the resource and its children, and a Propfind
header of "allprop", meaning the request should return the name and
value of all properties defined on each resource.
This section provides a description of a new type of Web The resource http://www.foo.bar/container/ has two properties
resource, the collection, and discusses its interactions with the defined on it, named http://www.foo.bar/boxschema/bigbox, and
HTTP URL namespace. This discussion is a prerequisite for the http://www.foo.bar/boxschema/author, while resource
specification of methods that operate on collections, given later http://www.foo.bar/container/index.html has only a single resource
in this document. defined on it, named http://www.foo.bar/boxschema/bigbox, another
instance of the "bigbox" property type.
3.1.1 Collection Resources 8.1.3. Example: Using propname to Retrieve all Property Names
A collection is a resource whose state consists of a list of PROPFIND /container/ HTTP/1.1
internal members, a list of external members, and a set of Host: www.foo.bar
properties. An internal member resource MUST have a URI that is Propfind: propname
immediately relative to the base URI of the collection, that is,
a relative URI in which "../" is illegal, which must begin with
"./" and which MAY contain only one other "/" at the end of the
URI. An external member resource MUST be an absolute URI that is
not an internal URI. Any given internal or external URI MUST
only belong to the collection once, i.e., multiple instances of
URIs in a collection are illegal. Properties defined on
collections have no special distinction, and behave exactly as do
properties on non-collection resources.
The purpose of a collection resource is to model collection-like HTTP/1.1 200 OK
objects (e.g., a filesystem directory) within a server's Content-Type: text/xml
namespace. Once these objects have been modeled with Content-Length: xxxx
collections, a client may perform an INDEX, add and remove
external members using ADDREF and DELREF, and perform recursive <?XML version="1.0">
operations, such as a full hierarchy copy. <?namespace href = "http://www.ietf.org/standards/dav/" As = "D"?>
<?namespace href = "http://www.foo.bar/boxschema/" AS = "R"?>
<D:multistatus>
<D:response>
<D:href>http://www.foo.bar/container/</D:href>
<D:prop>
<R:bigbox/>
<R:author/>
</D:prop>
<D:status>HTTP 1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.foo.bar/container/index.html</D:href>
<D:prop>
<R:bigbox/>
</D:prop>
<D:status>HTTP 1.1 200 OK</D:status>
</D:response>
</D:multistatus>
To support methods which operate on collections, a server SHOULD In this example, PROPFIND is invoked on the collection resource
model its collection-like objects with collection resources. For http://www.foo.bar/container/, with a Propfind header set to
example, a server which is implemented on top of a filesystem "propname", meaning the name of all properties should be returned.
SHOULD treat all filesystem directories exposed by the server as Since no depth header is present, it assumes its default value of
collection resources. "infinity", meaning the name of the properties on the collection and
all its progeny should be returned.
3.1.2 Creation and Retrieval of Collection Resources Consistent with the previous example, resource
http://www.foo.bar/container/ has two properties defined on it,
http://www.foo.bar/boxschema/bigbox, and
http://www.foo.bar/boxschema/author. The resource
http://www.foo.bar/container/index.html, a member of the "container"
collection, has only one property defined on it,
http://www.foo.bar/boxschema/bigbox.
This document specifies the MKCOL method to create new collection 8.2. PROPPATCH
resources, and the INDEX method to list their contents.
In HTTP/1.1, the PUT method is defined to store the request body The PROPPATCH method processes instructions specified in the request
at the location specified by Request-URI. While a description body to set and/or remove properties defined on the resource
format for a collection can readily be constructed that could be identified by Request-URI.
used with PUT, the implications of sending such a description to
the server are undesirable. For example, if a description of a
collection that omitted some existing resources were PUT to a
server, this might be interpreted as a command to remove those
members. This would extend PUT to perform DELETE functionality,
which is undesirable since it changes the semantics of PUT, and
makes it difficult to control DELETE functionality with an access
control scheme based on methods.
While the POST method is sufficiently open-ended that a "create a All DAV compliant resources MUST support the PROPPATCH method and
collection" POST command could be constructed, this is MUST process instructions that are specified using the
undesirable because it would be difficult to separate access propertyupdate, set, and remove XML elements of the DAV schema.
control for collection creation from other uses of POST if they Execution of the directives in this method is, of course, subject to
both use the same method. access control constraints. DAV compliant resources MUST support
the setting of arbitrary dead properties.
While it might seem desirable to have GET return a listing of the The request message body of a PROPPATCH method MUST contain at least
members of a collection, this is foiled by the existence of the one propertyupdate XML element. Instruction processing MUST occur
"index.html" de-facto standard namespace redirection, in which a in the order instructions are received (i.e., from top to bottom),
GET request on a collection is automatically redirected to the and MUST be performed atomically.
index.html resource.
The exact definition of the behavior of GET and PUT on 8.2.1. propertyupdate XML element
collections is defined later in this document.
3.1.2.1 Example Name: propertyupdate
Namespace: http://www.ietf.org/standards/dav/
Purpose: To contain a request to alter the properties on a
resource.
Parent: None
Values= 1*(set | remove)
Description: This XML element is a container for the information
required to modify the properties on the resource. This XML element
is multi-valued.
The structured resource http://foo/bar is created with a PUT. Bar 8.2.2. set XML element
is a multipart/related file with two members http://foo/bar/a and
http://foo/bar/b. If bar were deleted then both a and b would
also be deleted since they are all really just one resource. If
http://foo/bar/a/c was PUT then a DELETE on http://foo/bar/a
would also delete http://foo/bar/a/c as c was created with a PUT
not a MKCOL.
If http://foo/bar/b/d is created with a MKCOL and Name: set
http://foo/bar/b/d/e was created then a DELETE on d would fail Namespace: http://www.ietf.org/standards/dav/
because d is a collection with an internal member. However the Purpose: To set the DAV properties specified inside the set XML
existence of the collection d is something of an illusion. If a element.
DELETE was executed on http://foo/bar then everything would be Parent: propertyupdate
deleted, even though http://foo/bar/b/d was created with a MKCOL. Values= prop
Description: This XML element MUST contain only a prop XML element.
The elements contained by prop specify the name and value of
properties that are set on the Request-URI. If a property already
exists then its value is replaced.
Thus the effect of a MKCOL within a composite resourceís 8.2.3. remove XML element
namespace is felt on its children, not its ancestors. The
children of d MUST be treated as members of a collection when a
method is executed on d. But a method executed on b or a is
treated as if there only existed a non-collection resource.
3.1.3 Source Resources and Output Resources Name: remove
Namespace: http://www.ietf.org/standards/dav/
Purpose: To remove the DAV properties specified inside the remove
XML element.
Parent: propertyupdate
Values= prop
Description: Remove specifies 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 elements in prop MUST be empty,
as only the names of properties to be removed are required.
For many resources, the entity returned by GET exactly matches 8.2.4. Response Codes
the persistent state of the resource, for example, a GIF file
stored on a disk. For this simple case, the URL at which a
resource is accessed is identical to the URL at which the source
(the persistent state) of the resource is accessed. This is also
the case for HTML source files that are not processed by the
server prior to transmission.
However, the server can sometimes process HTML resources before 200 OK - The command succeeded. As there can be a mixture of sets
they are transmitted as a return entity body. For example, and removes in a body, a 201 Create seems inappropriate.
server-side-include directives within an HTML file instruct a
server to replace the directive with another value, such as the
current date. In this case, what is returned by GET (HTML plus
date) differs from the persistent state of the resource (HTML
plus directive). Typically there is no way to access the HTML
resource containing the unprocessed directive.
Sometimes the entity returned by GET is the output of a data- 403 Forbidden - The client, for reasons the server chooses not to
producing process that is described by one or more source specify, cannot alter one of the properties.
resources (that may not even have a location in the URL
namespace). A single data-producing process may dynamically
generate the state of a potentially large number of output
resources. An example of this is a CGI script that describes a
"finger" gateway process that maps part of the namespace of a
server into finger requests, such as
http://www.foo.bar.org/finger_gateway/user@host.
In the absence of distributed authoring capability, it is 405 Conflict - The client has provided a value whose semantics are
acceptable to have no mapping of source resource(s) to the URI not appropriate for the property. This includes trying to set read-
namespace, and in fact has desirable security benefits. However, only properties.
if remote editing of the source resource(s) is desired, the
source resource(s) should be given a location in the URI
namespace. This source location should not be one of the
locations at which the generated output is retrievable, since in
general it is impossible for the server to differentiate requests
for source resources from requests for process output resources.
There is often a many-to-many relationship between source
resources and output resources.
For DAV compliant servers all output resources which have a 413 Request Entity Too Long - If a particular property is too long
single source resource (and that source resource has a URI), the to be recorded then a composite XML error will be returned
URI of the source resource SHOULD be stored in a single link on indicating the offending property.
the output resource with type
http://www.ietf.org/standards/dav/source. Note that by storing
the source URI in links on the output resources, the burden of
discovering the source is placed on the authoring client.
3.2 MKCOL Method 8.2.5. Example
3.2.1 Problem Description PROPPATCH /bar.html HTTP/1.1
Host: www.foo.com
Content-Type: text/xml
Content-Length: xxxx
A client must be able to create a collection. <?XML version="1.0">
<?namespace href = "http://www.ietf.org/standards/dav/" AS = "D"?>
<?namespace href = "http://www.w3.com/standards/z39.50/" AS = "Z"?>
<D:propertyupdate>
<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>
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxxx
3.2.2 Solution Requirements <?XML version="1.0">
<?namespace href="http://www.ietf.org/standards/dav/" AS = "D"?>
<?namespace href="http://www.w3.com/standards/z39.50/" AS = "Z"?>
<D:multistatus>
<D:response>
<D:prop><Z:Authors/></D:prop>
<D:status>HTTP/1.1 420 Method Failure</D:status>
</D:response>
<D:response>
<D:prop><Z:Copyright-Owner/></D:prop>
<D:status>HTTP/1.1 409 Conflict</D:status>
</D:response>
<D:responsedescription> Copyright Owner can not be deleted or
altered.</D:responsedescription>
</D:multistatus>
The solution must ensure that a collection has been made (i.e. In this example, the client requests the server to set the value of
that it responds to the INDEX method) as opposed to a non- the http://www.w3.com/standards/z39.50/Authors property, and to
remove the property http://www.w3.com/standards/z39.50/Copyright-
Owner. Since the Copyright-Owner property could not be removed, no
property modifications occur. The Method Failure response code for
the Authors property indicates this action would have succeeded if
it were not for the conflict with removing the Copyright-Owner
property.
collection resource. If a collection could not be made, it must 8.3. MKCOL Method
indicate this failure to the user-agent.
3.2.3 Request The MKCOL method is used to create a new collection. All DAV
compliant resources MUST support the MKCOL method.
MKCOL creates a new collection resource at the location specified 8.3.1. Request
by the Request-URI. If the Request-URI exists, then MKCOL must
fail. During MKCOL processing, a server MUST make the Request-URI
a member of its parent collection. If no such an 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 neither
/a/b/ nor /a/b/c/ exist, the request MUST fail.
3.2.3.1 MKCOL Without Request Body MKCOL creates a new collection resource at the location specified by
the Request-URI. If the Request-URI exists, then MKCOL must fail.
During MKCOL processing, a server MUST make the Request-URI a member
of its parent collection. 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 neither /a/b/ nor /a/b/c/
exists, the request MUST fail.
When MKCOL is invoked without a request body, the newly created When MKCOL is invoked without a request body, the newly created
collection has no members. collection has no members.
3.2.3.2 MKCOL With Request Body A MKCOL request message MAY contain a message body. The behavior of
a MKCOL request when the body is present is limited to creating
A MKCOL request message MAY contain a message body. The behavior collections, members of a collection, bodies of members and
of a MKCOL request when the body is present is limited to properties on the collections or members. If the server receives a
creating collections, members of a collection, bodies of members MKCOL request entity type it does not support or understand it MUST
and properties on the collections or members. If the server respond with a 415 Unsupported Media Type status code. The exact
receives a MKCOL request entity type it does not support or behavior of MKCOL for various request media types is undefined in
understand it MUST respond with a 415 (Unsupported Media Type) this document, and will be specified in separate documents.
status code. The exact behavior of MKCOL for various request
media types is undefined in this document, and will be specified
in separate documents.
3.2.4 Response 8.3.2. Response Codes
Responses from a MKCOL request are not cacheable, since MKCOL has Responses from a MKCOL request are not cacheable, since MKCOL has
non-idempotent semantics. non-idempotent semantics.
201 (Created) - The collection or structured resource was created
in its entirety.
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 namespace, and 2) The parent collection of
the Request-URI exists but cannot accept members.
409 (Conflict) - A collection cannot be made at the Request-URI
until one or more intermediate collections have been created.
415 (Unsupported Media Type)- The server does not support the
request type of the body.
417 (Insufficient Space on Resource) - The resource does not have
sufficient space to record the state of the resource after the
execution of this method.
3.2.5 Example
This example creates a container collection called 201 Created - The collection or structured resource was created in
/webdisc/xfiles/ on the server www.server.org. its entirety.
MKCOL /webdisc/xfiles/ HTTP/1.1
Host: www.server.org
HTTP/1.1 201 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 namespace, and 2) The parent collection of the
Request-URI exists but cannot accept members.
3.3 Standard DAV Properties 405 Method Not Allowed - MKCOL can only be executed on a
deleted/non-existent resource.
The following properties are defined on DAV compliant resources. 409 Conflict - A collection cannot be made at the Request-URI until
All enclosed properties are part of the DAV Schema. one or more intermediate collections have been created.
3.3.1 IsCollection Property 415 Unsupported Media Type- The server does not support the request
type of the body.
Name: http://www.ietf.org/standards/dav/iscollection 419 Insufficient Space on Resource - The resource does not have
Purpose: This property contains a Boolean value that is set to sufficient space to record the state of the resource after the
"true" if the resource is a collection execution of this method.
Schema: http://www.ietf.org/standards/dav/
Value: ("true" | "false")
Description: This property MUST be defined on all DAV compliant
resources.
3.3.2 DisplayName Property 8.3.3. Example
Name: http://www.ietf.org/standards/dav/displayname This example creates a collection called /webdisc/xfiles/ on the
Purpose: A name for the resource that is suitable for server www.server.org.
presentation to a user.
Schema: http://www.ietf.org/standards/dav/
Value: Any valid XML character data (as defined in [Bray,
Sperberg-McQueen, 1997])
Description: This property SHOULD be defined on all DAV compliant
resources. If present, the property contains a description of the
resource that is suitable for presentation to a user.
3.3.3 CreationDate Property MKCOL /webdisc/xfiles/ HTTP/1.1
Host: www.server.org
Name: http://www.ietf.org/standards/dav/creationdate HTTP/1.1 201 Created
Purpose: The time and date the resource was created.
Schema: http://www.ietf.org/standards/dav/
Value: The time and date MUST be given in ISO 8601 format
[ISO8601]
Description: This property SHOULD be defined on all DAV compliant
resources. If present, it contains a timestamp of the moment when
the resource was created (i.e., the moment it had non-null
state).
3.3.4 GETentity Property 8.4. INDEX Method
Name: http://www.ietf.org/standards/dav/GETentity The INDEX method is used to enumerate the members of a resource.
Purpose: Contains the value of headers that are returned by a All DAV compliant resources MUST support the INDEX method if they
GET without Accept headers. have members.
Schema: http://www.ietf.org/standards/dav/
Value: Content-Type Content-Length Content-Language Last-
Modified Etag Creation-Date
Description: This property MUST be defined on all DAV compliant
resources unless GET is not supported, in which case this
property MUST NOT be defined. This property MUST contain at most
one instance of each element in its Value, if they are defined.
3.3.5 INDEXentity Property 8.4.1. The Request
Name: http://www.ietf.org/standards/dav/INDEXentity For a collection, INDEX MUST return a list of its members. All
Purpose: Contains the value of headers that are returned by an WebDAV compliant resources MUST support the text/xml response entity
INDEX. described below. The INDEX result for a collection MAY also return
Schema: http://www.ietf.org/standards/dav/ a list of the members of child collections, to any depth.
Value: Content-Type Content-Length Content-Language Last-
Modified Etag Creation-Date
Description: This property MUST be defined on all DAV compliant Collections that respond to an INDEX method with a text/xml entity
resources unless INDEX is not supported, in which case this MUST contain a single multistatus XML element which contains a
property MUST NOT be defined. This property MUST contain at most response XML element for each member.
one instance of each element in its Value, if they are defined.
3.3.6 Content-Type XML Element A resource that supports INDEX MUST return the resourcetype property
for each member.
Name: http://www.ietf.org/standards/dav/content-type Note that the prop XML element MAY contain additional properties.
Purpose: The content-type of the member resource.
Schema: http://www.ietf.org/standards/dav/
Parent: GETentity or INDEXentity
Value: media-type ; defined in Section 3.7 of [Fielding et
al., 1997]
Description: If the parent of this element is GETentity, the
value MUST be identical to the content-type returned by a GET on
the resource without Accept headers. If the parent is
INDEXentity, the value MUST be identical to the content-type
returned by an INDEX on the resource. If no content-type is
available, this element MUST NOT be defined.
3.3.7 Content-Length XML Element 8.4.2. Example
Name: http://www.ietf.org/standards/dav/content-length INDEX /user/yarong/dav_drafts/ HTTP/1.1
Purpose: Describes the default content-length of the resource. Host: www.microsoft.com
Schema: http://www.ietf.org/standards/dav/
Value: content-length ; see section 14.14 of RFC 2068
Description: If the parent of this element is GETentity, this
element MUST have a value equal to the content-length header
returned by a GET on the resource without Accept headers. If the
parent is INDEXentity, the value MUST be identical to the
content-length returned by an INDEX on the resource. If no
content-length is available, this element MUST NOT be defined.
3.3.8 Content-Language XML Element HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: xxx
Last-Modified: Thu, 11 Sep 1997 23:45:12 GMT
ETag: _fooyyybar_
Name: http://www.ietf.org/standards/dav/content-language <?XML version="1.0">
Purpose: Describes the default natural language of a resource. <?namespace href = _http://www.ietf.org/standards/dav/_ as = _D_?>
Schema: http://www.ietf.org/standards/dav/ <D:multistatus>
Value: language-tag ;language-tag is defined in section <D:response>
14.13 of RFC 2068 <D:href>http://www.microsoft.com/user/yarong/dav_drafts/
Description: If the parent of this element is GETentity, this </D:href>
element MUST have a value equal to the content-language header <D:prop>
returned by a GET on the resource without Accept headers. If the <D:resourcetype>
parent is INDEXentity, the value MUST be identical to the <D:collection/>
content-language header returned by an INDEX on the resource. If </D:resourcetype>
no content-language header is available, this element MUST NOT be </D:prop>
defined. <D:status>HTTP 1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>
http://www.microsoft.com/user/yarong/dav_drafts/base
</D:href>
<D:prop>
<D:resourcetype/>
</D:prop>
<D:status>HTTP 1.1 200 OK</D:status>
</D:response>
</D:multistatus>
3.3.9 Last-Modified XML Element 8.5. ADDREF Method
Name: http://www.ietf.org/standards/dav/last-modified The ADDREF method is used to add external members to a resource.
Purpose: The date the resource was last modified. All DAV compliant collection resources MUST support the ADDREF
Schema: http://www.ietf.org/standards/dav/ method. All other DAV compliant resources MAY support the ADDREF
Parent: GETentity or INDEXentity method as appropriate.
Value: The date MUST be given in RFC 1123 format using the
rfc-1123 production, defined in section 3.3.1 of [Fielding et al.,
1997].
Description: If the parent of this element is GETentity, this
element MUST have a value equal to the last-modified header 8.5.1. The Request
returned by a GET on the resource without Accept headers. If the
parent is INDEXentity, the value MUST be identical to the last-
modified header returned by an INDEX on the resource. If no
last-modified header is available, this element MUST NOT be defined.
3.3.10 Etag XML Element The ADDREF method adds the URI specified in the Collection-Member
header as an external member to the collection specified by the
Request-URI. The value in the Collection-Member header MUST be an
absolute URI meeting the requirements of an external member URI.
Name: http://www.ietf.org/standards/dav/etag It is not an error if the URI specified in the Collection-Member
Purpose: The entity tag of the resource. header already exists as an external member of the collection.
Schema: http://www.ietf.org/standards/dav/ However, after processing the ADDREF there MUST be only one instance
Parent: GETentity or INDEXentity of the URI in the collection. If the URI specified in the
Value: entity-tag ; defined in Section 3.11 of [Fielding et Collection-Member header already exists as an internal member of the
al., 1997] collection, the ADDREF method MUST fail with a 412 Precondition
Description: If the parent of this element is GETentity, this Failed status code.
element MUST have a value equal to the entity-tag header returned
by a GET on the resource without Accept headers. If the parent
is INDEXentity, the value MUST be identical to the entity-tag
header returned by an INDEX on the resource. If no entity-tag
header is available, this element MUST NOT be defined.
3.4 INDEX Method 8.5.2. Example
3.4.1 Problem Description ADDREF /~ejw/dav/ HTTP/1.1
Host: www.ics.uci.edu
Collection-Member: http://www.ietf.org/standards/dav/
A mechanism is needed to discover if a resource is a collection HTTP/1.1 200 OK
and if so, list its members.
3.4.2 Solution Requirements This example adds the URI http://www.ietf.org/standards/dav/ as an
external member resource of the collection
http://www.ics.uci.edu/~ejw/dav/.
The solution: 8.6. DELREF Method
- must allow a client to discover the members of a collection
- must always provide a machine-readable description of the
membership of a collection
- must be leveraged as a more general mechanism to provide a
list of contents for any resource which can profitably return a
membership like listing.
3.4.3 The Request The DELREF method is used to remove external members from a
resource. All DAV compliant collection resources MUST support the
DELREF method. All other DAV compliant resources MUST support the
DELREF method only if they support the ADDREF method.
The INDEX method returns a machine-readable representation of the 8.6.1. The Request
membership of the resource at the Request-URI.
For a collection, INDEX MUST return a list of its members. All The DELREF method removes the URI specified in the Collection-Member
WebDAV compliant resources MUST support the text/xml response header from the collection specified by the Request-URI.
entity described below. The INDEX result for a collection MAY
also return a list of the members of child collections, to any
depth.
Collections that respond to an INDEX method with a text/xml DELREFing a URI which is not a member of the collection is not an
entity MUST contain only one ResInfo element. This ResInfo error. DELREFing an internal member MUST fail with a 412
element contains an Href element, which gives the identifier(s) Precondition Failed status code.
of the resource, a Prop element, which gives selected properties
of the resource, and a Members element, which contains a ResInfo
element for each member of the collection. The Prop element MUST
contain at least the following properties, if they are defined 8.6.2. Example
and available: DisplayName, IsCollection, CreationDate,
GETentity, and INDEXentity.
The response from INDEX is cacheable, and SHOULD be accompanied DELREF /~ejw/dav/ HTTP/1.1
by an ETag header (see section 13.3.4 of RFC 2068). If GET and Host: www.ics.udi.edu
INDEX return different entities for the same resource state, they Collection-Member: http://www.ietf.org/standards/dav/
MUST return different entity tags.
3.4.4 The Response HTTP/1.1 200 OK
200 (OK) - The server MUST send a machine readable response This example removes the URI http://www.ietf.org/standards/dav/, an
entity which describes the membership of the resource. external member resource, from the collection
http://www.ics.uci.edu/~ejw/dav/.
3.4.5 ResInfo XML Element 8.7. GET, HEAD for Collections
Name: http://www.ietf.org/standards/dav/resinfo The semantics of GET are unchanged when applied to a collection,
Purpose: Describes a resource. since GET is defined as, _retrieve whatever information (in the form
Schema: http://www.ietf.org/standards/dav/ of an entity) is identified by the Request-URI_ [Fielding et al.,
Parent: Any 1997]. GET when applied to a collection MAY return the contents of
Value: Href Prop Members an _index.html_ resource, a human-readable view of the contents of
Description: There MUST be at least one Href element. Each Href the collection, or something else altogether, and hence it is
element contains a URI for the resource, which MUST be an possible the result of a GET on a collection will bear no
absolute URI. There MUST be a single Prop element that contains a correlation to the state of the collection.
series of properties defined on the resource. If the resource is
a collection, it MAY have at most one Members element, which
describes the members of the collection.
3.4.6 Members XML Element 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.
Name: http://www.ietf.org/standards/dav/members 8.8. POST for Collections
Purpose: Describes the membership of a collection resource.
Schema: http://www.ietf.org/standards/dav/
Parent: ResInfo
Value: ResInfo
Description: Contains zero or more ResInfo elements, which
describe members of the collection.
3.4.7 Href XML Element 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.
Name: http://www.ietf.org/standards/dav/href 8.9. DELETE
Purpose: To identify that the content of the element is a URI.
Schema: http://www.ietf.org/standards/dav/
Parent: Any
Value: URI ; See section 3.2.1 of [Fielding et al., 1997]
3.4.8 Example 8.9.1. DELETE Method for Non-Collection Resources
INDEX /user/yarong/dav_drafts/ HTTP/1.1 If the DELETE method is issued to a non-collection resource which is
Host: www.microsoft.com an internal member of a collection, then during DELETE processing a
server MUST remove the Request-URI from its parent collection. A
server MAY remove the URI of a deleted resource from any collections
of which the resource is an external member.
HTTP/1.1 200 OK 8.9.2. DELETE for Collections
Content-Type: text/xml The DELETE method on a collection MUST act as if a Depth = Infinity
Content-Length: xxx header was used on it. A client MUST NOT submit a Depth header on a
Last-Modified: Thu, 11 Sep 1997 23:45:12 GMT DELETE on a collection with any value but Infinity.
ETag: "fooyyybar"
<?XML:Namespace DELETE instructs that the collection specified in the request-URI,
href = "http://www.ietf.org/standards/dav/" as = "D"/> the records of its external member resources, and all its internal
member resources, are to be deleted.
<D:ResInfo> If any member cannot be deleted then all of the member's progeny
<XML:Href> MUST NOT be deleted, so as to maintain the namespace.
http://www.microsoft.com/user/yarong/dav_drafts/
</XML:Href>
<Prop>
<DisplayName>
WebDAV working drafts directory
</DisplayName>
<IsCollection>true</IsCollection>
<CreationDate>19970418T070304Z</CreationDate>
<GETentity>
<Content-Type>text/html</Content-Type>
<Content-Length>2754</Content-Length>
<Content-Language>en</Content-Language>
<Last-Modified>
Fri, 22 Aug 1997 10:11:26 GMT
</Last-Modified>
<Etag>"8675309"</Etag>
</GETentity>
<INDEXentity>
<Content-Type>text/xml</Content-Type>
<Content-Length>xxx</Content-Length>
<Last-Modified>
Thu, 11 Sep 1997 23:45:12 GMT
</Last-Modified>
<Etag>"fooyyybar"</Etag>
</INDEXentity>
</Prop>
<Members> Any headers included with DELETE MUST be applied in processing every
<ResInfo> resource to be deleted. In this case, a header of special interest
<XML:Href> is the Destroy header, which specifies the method to be used to
http://www.microsoft.com/user/yarong/dav_drafts/base delete all resources in the scope of the DELETE.
</XML:Href>
<Prop>
<IsCollection
D:PropLoc="http://www.microsoft.com/user/yarong/dav_drafts/b
ase;props=IsCollection">
False
</IsCollection>
<DisplayName>
WebDAV Name Space Operations Draft
</DisplayName>
<Creation-Date>19970320T230525Z</Creation-Date>
<GETentity> When the DELETE method has completed processing it MUST return a
<Content-Type>application/msword</Content-Type> consistent namespace.
<Content-Length>1400</Content-Length>
<Content-Language>en</Content-Language>
<Last-Modified>
Fri, 22 Aug 1997 18:22:56 GMT
</Last-Modified>
<Etag>"8675309"</Etag>
</GETentity>
</Prop>
</ResInfo>
</Members>
</D:ResInfo>
This example shows the result of the INDEX method applied to the The response SHOULD be a Multi-Status response that describes the
collection resource result of the DELETE on each affected resource.
http://www.microsoft.com/user/yarong/dav_drafts/. It returns a
response body in XML format, which gives information about the
container and its sole member,
http://www.microsoft.com/user/yarong/dav_drafts/base. The entry
on the collection confirms that the resource the INDEX was 8.9.2.1. Example
executed on is a collection. The result also contains the URI of
the IsCollection property on the member resource.
3.5 Behavior of RFC 2068 Methods on Collections DELETE /container/ HTTP/1.1
Host: www.foo.bar
Destroy: NoUndelete
With the introduction of the collection resource type to the HTTP HTTP/1.1 207 Multi-Status
object model, it is necessary to define the behavior of the Content-Type: text/xml
existing methods (defined in RFC 2068) when invoked on a Content-Length: xxxxx
collection resource to avoid ambiguity. While some methods, such
as OPTIONS and TRACE behave identically when applied to
collections, GET, HEAD, POST, PUT, and DELETE require some
additional explanation.
3.5.1 GET, HEAD for Collections <?XML version="1.0">
<?namespace href = "http://www.ietf.org/standards/dav/" As = "d"?>
<d:multistatus>
<d:response>
<d:href>http://www.foo.bar/container/resource1</d:href>
<d:href>http://www.foo.bar/container/resource2</d:href>
<d:status>HTTP/1.1 200 OK</d:status>
</d:response>
<d:response>
<d:href>http://www.foo.bar/container/</d:href>
<d:status>HTTP/1.1 420 Method Failure</d:status>
</d:response>
<d:response>
<d:href>http://www.foo.bar/container/resource3</d:href>
<d:status>HTTP/1.1 412 Precondition Failed</d:status>
</d:response>
</d:multistatus>
In this example the attempt to delete
http://www.foo.bar/container/resource3 failed because the server was
unable to guarantee that resource3 would not be able to be
undeleted. Consequently, the attempt to delete
http://www.foo.bar/container/ also failed, but resource1 and
resource2 were deleted. Even though a Depth header has not been
included, a depth of infinity is assumed because the method is on a
collection. As this example illustrates, DELETE processing need not
be atomic.
The semantics of GET are unchanged when applied to a collection, 8.10. PUT
since GET is defined as, "retrieve whatever information (in the
form of an entity) is identified by the Request-URI" [Fielding et
al., 1997]. 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, and
hence it is possible the result of a GET on a collection will
bear no correlation to the state of the collection.
Similarly, since the definition of HEAD is a GET without a 8.10.1. PUT for Non-Collection Resources
response message body, the semantics of HEAD are unmodified when
applied to collection resources.
3.5.2 POST for Collections 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. 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.
Since by definition the actual function performed by POST is A PUT that would result in the creation of a resource without an
determined by the server and often depends on the particular appropriately scoped parent collection MUST fail with a 405 Method
resource, the behavior of POST when applied to collections cannot Not Allowed.
be meaningfully modified because it is largely undefined. Thus
the semantics of POST are unmodified when applied to a
collection.
3.5.3 PUT for Collections 8.10.2. PUT for Collections
As defined in the HTTP/1.1 specification [Fielding et al., 1997], As defined in the HTTP/1.1 specification [Fielding et al., 1997],
the "PUT method requests that the enclosed entity be stored under the "PUT method requests that the enclosed entity be stored under
the supplied Request-URI." Since submission of an entity the supplied Request-URI." Since submission of an entity
representing a collection would implicitly encode creation and representing a collection would implicitly encode creation and
deletion of resources, this specification intentionally does not deletion of resources, this specification intentionally does not
define a transmission format for creating a collection using PUT. define a transmission format for creating a collection using PUT.
Instead, the MKCOL method is defined to create collections. If a Instead, the MKCOL method is defined to create collections. If a
PUT is invoked on a collection resource it MUST fail. PUT is invoked on a collection resource it MUST fail.
When the PUT operation creates a new non-collection resource all When the PUT operation creates a new non-collection resource all
ancestors MUST already exist. If all ancestors do not exist, the ancestors MUST already exist. If all ancestors do not exist, the
method MUST fail with a 409 Conflict status code. For example, method MUST fail with a 409 Conflict status code. For example, if
if resource /a/b/c/d.html is to be created and /a/b/c/ does not resource /a/b/c/d.html is to be created and /a/b/c/ does not exist,
exist, then the request MUST fail. then the request must fail.
3.5.3.1 PUT for Non-Collection Resources
A PUT performed on an existing resource replaces the GET response
entity of the resource, but MUST NOT change the value of any dead
properties defined on the resource. Live properties defined on
the resource MAY be recomputed during PUT processing.
3.5.4 DELETE for Collections
When DELETE is applied to a collection without internal members
the collection resource, along with its properties, and external
members, MUST be deleted. A DELETE method applied to a
collection resource containing internal member resources MUST
fail with a 409 Conflict status code.
3.5.5 DELETE Method for Non-Collection Resources
If the DELETE method is issued to a non-collection resource which
is an internal member of a collection, then during DELETE
processing a server MUST remove the Request-URI from its parent
collection. A server MAY remove the URI of a deleted resource
from any collections of which the resource is an external member.
3.6 COPY Method
3.6.1 Problem Description
Currently, in order to create a copy of a resource, the client
must GET an entity and then PUT that entity to the desired
destination. This requires (1) an entity to be transmitted to and
from the server and (2) that the resource be expressible as an
entity with complete fidelity.
This is problematic because of the network traffic involved in 8.11. COPY Method
making a copy, and because there is often no way to fully express
a resource as an entity without a loss of fidelity.
3.6.2 Solution Requirements The COPY method creates a duplicate of the specified resource. All
DAV compliant resources MUST support the COPY method.
The solution: Support for the COPY method does not guarantee the ability to copy a
- MUST allow a principal to create a copy of a resource resource. For example, separate programs may control resources on
without having to transmit the resource to and from the server. the same server. As a result, it may not even be possible to copy a
resource to a location that appears to be on the same server.
3.6.3 The Request 8.11.1. The Request
The COPY method creates a duplicate of the source resource, given The COPY method creates a duplicate of the source resource, given by
by the Request-URI, in the destination resource, given by the the Request-URI, in the destination resource, given by the
Destination header. The Destination header MUST be present. The Destination header. The Destination header MUST be present. The
exact behavior of the COPY method depends on the type of the exact behavior of the COPY method depends on the type of the source
source resource. resource.
3.6.3.1 COPY for HTTP/1.1 resources 8.11.1.1. COPY for HTTP/1.1 resources
When the source resource is not a collection, and is not a When the source resource is not a collection the body of the
property, the body of the destination resource MUST be octet-for- destination resource MUST be octet-for-octet identical to the body
octet identical to the body of the source resource. Alterations of the source resource. Alterations to the destination resource do
to the destination resource do not modify the source resource. not modify the source resource. Alterations to the source resource
Alterations to the source resource do not modify the destination do not modify the destination resource. Thus, all copies are
resource. Thus, all copies are performed "by-value". performed _by-value_.
All properties on the source resource MUST be duplicated on the All properties on the source resource MUST be duplicated on the
destination resource, subject to modifying headers, following the destination resource, subject to modifying headers, following the
definition for copying properties. definition for copying properties.
3.6.3.2 COPY for Properties 8.11.1.2. COPY for Properties
The following section defines how properties on a resource are The following section defines how properties on a resource are
handled during a COPY operation. handled during a COPY operation.
Live properties SHOULD be duplicated as identically behaving live Live properties SHOULD be duplicated as identically behaving live
properties at the destination resource. Since they are live properties at the destination resource. Since they are live
properties, the server determines the syntax and semantics (hence properties, the server determines the syntax and semantics of these
value) of these properties. Properties named by the Enforce- properties. Properties named by the Enforce-Live-Properties header
Live- MUST be live on the destination resource, or the method MUST fail.
Properties header MUST be live on the destination resource, or If a property is not named by Enforce-Live-Properties and cannot be
the method MUST fail. If a property is not named by Enforce- copied live, then its value MUST be duplicated, octet-for-octet, in
Live- an identically named, dead property on the destination resource.
Properties and cannot be copied live, then its value MUST be
duplicated, octet-for-octet, in an identically named, dead
resource on the destination resource.
If a property on the source already exists on the resource and If a property on the source already exists on the destination
the overwrite header is set to TRUE then the property at the resource and the Overwrite header is set to "T" then the property at
destination MUST be overwritten with the property from the the destination MUST be overwritten with the property from the
source. If the overwrite header is false and the previous source. If the Overwrite header is "F" and the previous situation
situation exists then the COPY MUST fail with a 409 Conflict. exists, then the COPY MUST fail with a 409 Conflict.
3.6.3.3 COPY for Collections 8.11.1.3. COPY for Collections
A COPY on a collection causes a new, empty collection resource to The COPY method on a collection without a Depth header MUST act as
be created at the destination with the same properties as the if a Depth = infinity header was included. A client MAY submit a
source resource. All properties on the source collection MUST be Depth header on a COPY on a collection with a value of "0" or
duplicated on the destination collection, subject to modifying "infinity". DAV compliant servers MUST support the "0" and
headers, following the definition for copying properties. The "infinity" behaviors.
new collection MUST NOT contain any members, internal or
external.
3.6.3.4 Type Interactions A COPY of depth infinity instructs that the collection specified in
the Request-URI, the records of its external member resources, and
all its internal member resources, are to be copied to a location
relative to the Destination header.
If the destination resource identifies a property and the source A COPY of depth "0" only instructs that the collection, the
resource is not a property, then the copy SHOULD fail. properties, and its external members, not its internal members, are
to be copied.
Any headers included with a COPY are to be applied in processing
every resource to be copied.
The exception to this rule is the Destination header. This header
only specifies the destination for the Request-URI. When applied to
members of the collection specified in 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" and the destination is "b"
then when a/c/d is processed it MUST use a destination of b/c/d.
When the COPY method has completed processing it MUST have created a
consistent namespace at the destination. Thus if it is not possible
to COPY a collection with internal members, the internal members may
still be copied but a collection will have to be created at the
destination to contain them.
The response is a Multi-Status response that describes the result of
the COPY on each affected resource. The response is given for the
resource that was to be copied, not the resource that was created as
a result of the copy. In other words, each entry indicates whether
the copy on the resource specified in the href succeeded or failed
and why.
The exception to this rule is for errors that occurred on the
destination. For example, if the destination was locked the
response would indicate the destination URL and a 421 Destination
Locked error.
8.11.1.4. Type Interactions
If the destination resource identifies a collection and the If the destination resource identifies a collection and the
Overwrite header is "true," prior to performing the copy, the Overwrite header is _T_, prior to performing the copy the server
server MUST perform a DELETE operation on the collection. MUST perform a DELETE operation on the collection.
3.6.4 The Response 8.11.2. Response Codes
200 (OK) The source resource was successfully copied to a pre- 200 OK - The source resource was successfully copied to a pre-
existing destination resource. existing destination resource.
201 (Created) The source resource was successfully copied. The 201 Created - The source resource was successfully copied. The copy
copy operation resulted in the creation of a new resource. operation resulted in the creation of a new resource.
412 (Precondition Failed) This status code MUST be returned if 412 Precondition Failed - This status code MUST be returned if the
the server was unable to maintain the liveness of the properties server was unable to maintain the liveness of the properties listed
listed in the Enforce-Live-Properties header, or if the Overwrite in the Enforce-Live-Properties header, or if the Overwrite header is
header is false, and the state of the destination resource is "F", and the state of the destination resource is non-null.
non-null.
417 (Insufficient Space on Resource) - The destination resource 419 Insufficient Space on Resource - The destination resource does
does not have sufficient space to record the state of the not have sufficient space to record the state of the resource after
resource after the execution of this method. the execution of this method.
500 (Server Error) The resource was in such a state that it could 421 Destination Locked _ The destination resource was locked and
not be copied. This may occur if the Destination header specifies either a valid Lock-Token header was not submitted, or the Lock-
a resource that is outside the namespace the resource is able to Token header identifies a lock held by another principal.
interact with.
3.6.5 Examples 500 Server Error - The resource was in such a state that it could
not be copied. This may occur if the Destination header specifies a
resource that is outside the namespace the resource is able to
interact with.
3.6.5.1 Overwrite Example 8.11.3. Overwrite Example
This example shows resource This example shows resource
http://www.ics.uci.edu/~fielding/index.html being copied to the http://www.ics.uci.edu/~fielding/index.html being copied to the
location http://www.ics.uci.edu/users/f/fielding/index.html. The location http://www.ics.uci.edu/users/f/fielding/index.html. The
contents of the destination resource were overwritten, if non- contents of the destination resource were overwritten, if non-null.
null.
COPY /~fielding/index.html HTTP/1.1 COPY /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/users/f/fielding/index.html Destination: http://www.ics.uci.edu/users/f/fielding/index.html
HTTP/1.1 200 OK HTTP/1.1 200 OK
3.6.5.2 No Overwrite Example 8.11.4. No Overwrite Example
The following example shows the same copy operation being The following example shows the same copy operation being performed,
performed, except with the Overwrite header set to "false." A except with the Overwrite header set to _F._ A response of 412
response of 412, Precondition Failed, is returned because the Precondition Failed is returned because the destination resource has
destination resource has a non-null state. a non-null state.
COPY /~fielding/index.html HTTP/1.1 COPY /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/users/f/fielding/index.html Destination: http://www.ics.uci.edu/users/f/fielding/index.html
Overwrite: "false" Overwrite: _F_
HTTP/1.1 412 Precondition Failed HTTP/1.1 412 Precondition Failed
3.7 MOVE Method 8.11.5. Collection Example
3.7.1 Problem Description COPY /container/ HTTP/1.1
Host: www.foo.bar
Destination: http://www.foo.bar/othercontainer/
Enforce-Live-Properties: *
Depth: Infinity
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxxx
The move operation on a resource is the logical equivalent of a <?XML version="1.0">
copy followed by a delete, where the actions are performed <?namespace href = "http://www.ietf.org/standards/dav/" As = "d"?>
atomically. Using RFC 2068 methods only, this procedure could be <d:multistatus>
performed in several steps. First, the client could issue a GET <d:response>
to retrieve a representation of a resource, issue a DELETE to <d:href>http://www.foo.bar/othercontainer/resource1</d:href>
remove the resource from the server, then use PUT to place the <d:href>http://www.foo.bar/othercontainer/resource2</d:href>
resource on the server with a new URI. As is the case for COPY - <d:href>http://www.foo.bar/othercontainer/</d:href>
because of the network traffic involved in making a move, and <d:href>http://www.foo.bar/othercontainer/R2/D2</d:href>
because there is often no way to fully express a resource as an <d:status>HTTP/1.1 201 Created</d:status>
entity without a loss of fidelity - server move functionality is </d:response>
preferable. <d:response>
<d:href>http://www.foo.bar/othercontainer/R2/</d:href>
<d:status>HTTP/1.1 412 Precondition Failed</d:status>
</d:response>
</d:multistatus>
With a WEBDAV server, a principal may accomplish this task by The Depth header is unnecessary as the default behavior of COPY on a
issuing a COPY and then DELETE. Network load decreases, but the collection is to act as if a "Depth: Infinity" header had been
server load may still be significant because the server must submitted. In this example most of the resources, along with the
create a duplicate resource. Were a server to know beforehand collection, were copied successfully. However the collection R2
that a principal intended to perform COPY and DELETE operations failed, most likely due to a problem with enforcing live properties.
in succession, it could avoid the creation of a duplicate R2's member D2 was successfully copied. As a result a collection
resource. was created at www.foo.bar/othercontainer/R2 to contain D2.
3.7.2 Solution Requirements 8.12. MOVE Method
The solution: The move operation on a resource is the logical equivalent of a copy
- Must prevent the unneeded transfer of entity bodies from and followed by a delete, where the actions are performed atomically.
to the server. All DAV compliant resources MUST support the MOVE method.
- Must prevent the unneeded creation of copies by the server.
3.7.3 The Request However, 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 even be possible to move
a resource within a namespace that appears to belong to the same
server.
The move operation on a resource is the logical equivalent of a 8.12.1. The Request
copy followed by a delete, where the actions are performed
atomically. 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.
3.7.4 The Response 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.
200 (OK) - The resource was moved. A successful response must 8.12.2. MOVE for Collections
contain the Content-Location header, set equal to the URI in
source. This lets caches properly flush any cached entries for
the source. Unfortunately the Content-Location header only allows
a single value so it is not possible for caches unfamiliar with
the MOVE method to properly clear their caches.
412 (Precondition Failed) This status code MUST be returned if MOVE instructs that the collection specified in the Request-URI, the
the server was unable to maintain the liveness of the properties records of its external member resources, and all its internal
listed in the Enforce-Live-Properties header, or if the Overwrite member resources, are to be moved to a location relative to the
header is false, and the state of the destination resource is Destination header.
non-null.
501 (Not Implemented) - This may occur if the Destination header The MOVE method on a collection MUST act as if a Depth "infinity"
specifies a resource which is outside its domain of control header was used on it. A client MUST NOT submit a Depth header on a
(e.g., stored on another server) resource and the server either MOVE on a collection with any value but "infinity".
refuses or is incapable of moving to an external resource.
502 (Bad Gateway) - This may occur when moving to external Any headers included with MOVE are to be applied in processing every
resources and the destination server refused to accept the resource to be moved.
resource.
3.7.5 Examples The exception to this rule is the Destination header. The behavior
of this header is the same as given for COPY on collections.
3.7.5.1 Overwrite Example When the MOVE method has completed processing it MUST have created a
consistent namespace on both the source and destination, creating
collections at the source or destination as necessary.
As specified in the definition of MOVE, a MOVE of a collection over
another collection causes the destination collection and all its
members to be deleted.
The response is a Multi-Status response that describes the result of
the MOVE on each effected resource. The response is given for the
resource that was to be moved, not the resource that was created as
a result of the move. In other words, each entry indicates whether
the move on the resource specified in the href succeeded or failed
and why.
The exception to this rule is for errors that occurred on the
destination. For example, if the destination was locked the
response would indicate the destination URL and a 421 Destination
Locked error.
8.12.3. Response Codes
200 OK - The move operation was successful.
409 Conflict _ The MOVE was attempted on a collection with members.
While the COPY part of this operation could succeed the DELETE could
not. Therefore the MOVE MUST fail.
412 Precondition Failed - This status code MUST be returned if the
server was unable to maintain the liveness of the properties listed
in the Enforce-Live-Properties header, or if the Overwrite header is
"F", and the state of the destination resource is non-null.
421 Destination Locked - The destination resource was locked and
either a valid Lock-Token header was not submitted, or the Lock-
Token header identifies a lock held by another principal.
502 Bad Gateway - This may occur when the destination is
o
n another
server and the destination server refuses to accept the resource
8.12.4. Overwrite Example
This example shows resource This example shows resource
http://www.ics.uci.edu/~fielding/index.html being moved to the http://www.ics.uci.edu/~fielding/index.html being moved to the
location http://www.ics.uci.edu/users/f/fielding/index.html. The location http://www.ics.uci.edu/users/f/fielding/index.html. The
contents of the destination resource were overwritten, if non- contents of the destination resource were overwritten, if non-null.
null.
MOVE /~fielding/index.html HTTP/1.1 MOVE /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/users/f/fielding/index.html Destination: http://www.ics.uci.edu/users/f/fielding/index.html
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Location:
http://www.ics.uci.edu/users/f/fielding/index.html
3.8 ADDREF Method 8.12.5. Collection Example
3.8.1 Problem Definition MOVE /container/ HTTP/1.1
Host: www.foo.bar
Destination: http://www.foo.bar/othercontainer/
Enforce-Live-Properties: *
Overwrite: False
Lock-Token: <OpaqueLockToken:xxxx> <OpaqueLockToken:xxxx>
There needs to be a way to add an external member to a HTTP/1.1 207 Multi-Status
collection. Content-Type: text/xml
Content-Length: xxxxx
3.8.2 Solution Requirements <?XML version="1.0">
<?namespace href = "http://www.ietf.org/standards/dav/" As = "D"?>
<d:multistatus>
<d:response>
<d:href>http://www.foo.bar/container/resource1</d:href>
<d:href>http://www.foo.bar/container/resource2</d:href>
<d:href>http://www.foo.bar/container/</d:href>
<d:href>http://www.foo.bar/container/C2/R2</d:href>
<d:status>HTTP/1.1 201 Created</d:status>
</d:response>
<d:response>
<d:href>http://www.foo.bar/container/C2</d:href>
<d:status>HTTP/1.1 420 Method Failure</d:status>
<d:response>
<d:href>http://www.foo.bar/othercontainer/C2</d:href>
<d:status>HTTP/1.1 409 Conflict</d:status>
</d:response>
</d:multistatus>
The solution must: In this example the client has submitted a number of lock tokens
- allow access control with the request. A lock token will need to be submitted for every
- allow referencing to URIs of external members resource, both source and destination, anywhere in the scope of the
- not require a body method, that is locked. In this case the proper lock token was not
submitted for the destination http://www.foo.bar/othercontainer/C2.
This means that the resource continer/c2 could not be moved,
although its child container/C2/R2 could be moved.
3.8.3 The Request 8.13. LOCK Method
The ADDREF method adds the URI specified in the Collection-Member The following sections describe the LOCK method, which is used to
header as an external member to the collection specified by the take out a lock of any access type. These sections on the LOCK
Request-URI. The value in the Collection-Member header MUST be an method describe only those semantics that are specific to the LOCK
absolute URI meeting the requirements of an external member URI. method and are independent of the access type of the lock being
requested. Once the general LOCK method has been described,
subsequent sections describe the semantics of the "write" access
type, and the write lock.
It is not an error if the URI specified in the Collection-Member 8.13.1. Operation
header already exists as an external member of the collection,
however, after processing ADDREF there MUST be only one instance
of the URI in the collection. If the URI specified in the
Collection-Member header already exists as an internal member of
the collection, the ADDREF method MUST fail with a 412
Precondition Failed status code.
3.8.4 Example A LOCK method invocation creates the lock specified by the Lock-Info
header on the Request-URI. Lock method requests SHOULD have a XML
request body which contains an Owner XML element for this lock
request. The LOCK request MAY have a Timeout header.
ADDREF /~whitehead/dav/ HTTP/1.1 A successful response to a lock invocation MUST include Lock-Token
HOST: www.ics.udi.edu and Timeout headers. Clients MUST assume that locks may arbitrarily
Collection-Member: http://www.ietf.org/standards/dav/ 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,
an administrator 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. The response MUST also contain the value of the
lockdiscovery property in a prop XML element.
HTTP/1.1 200 OK 8.13.2. The Effect of Locks on Properties and Collections
3.9 DELREF Method By default the scope of a lock is the entire state of the resource,
including its body and associated properties. As a result, a lock
on a resource also locks the resource's properties, and a lock on a
property may lock a property's resource or may restrict the ability
to lock the property's resource. Only a single lock token MUST be
used when a lock extends to cover both a resource and its
properties. Note that certain lock types MAY override this
behavior.
3.9.1 Problem Definition For collections, a lock also affects the ability to add or remove
members. The nature of the effect depends upon the type of access
control involved.
There needs to be a way to remove an external member from a 8.13.3. Locking Replicated Resources
collection.
3.9.2 Solution Requirements Some servers automatically replicate resources across multiple URLs.
In such a circumstance the server MAY only accept a lock on one of
the URLs if the server can guarantee that the lock will be honored
across all the URLs.
The solution must: 8.13.4. Locking Multiple Resources
- allow access control
- allow referencing to URIs of external members
- not require a body
3.9.3 The Request The LOCK method supports locking multiple resources simultaneously
by allowing for the listing of several URIs in the LOCK request.
These URIs, in addition to the Request-URI, are then to be locked as
a result of the LOCK method's invocation. When multiple resources
are specified the LOCK method only succeeds if all specified
resources are successfully locked.
The DELREF method removes the URI specified in the Collection- The Lock-Tree option of the lock request specifies that the resource
Member header from the collection specified by the Request-URI. and all its internal children (including internal collections, and
their internal members) are to be locked. This is another mechanism
by which a request for a lock on multiple resources can be
specified.
DELREFing a URI which is not a member of the collection is not an Currently existing locks can not be extended to cover more or less
error. DELREFing an internal member MUST fail with a 412 resources, and any request to expand or contract the number of
Precondition Failed status code. resources in a lock MUST fail with a 409 Conflict status code. So,
for example, if resource A is exclusively write locked and then the
same principal asks to exclusively write lock resources A, B, and C,
the request will fail as A is already locked and the lock can not be
extended.
3.9.4 Example A successful result will return a single lock token which represents
all the resources that have been locked. If an UNLOCK is executed
on this token, all associated resources are unlocked.
DELREF /~whitehead/dav/ HTTP/1.1 If the lock cannot be granted to all resources, a 409 Conflict
Host: www.ics.udi.edu status code MUST be returned with a response entity body containing
Collection-Member: http://www.ietf.org/standards/dav/ a multistatus XML element describing which resource(s) prevented the
lock from being granted.
8.13.5. Interaction with other Methods
The interaction of a LOCK with various methods is dependent upon the
lock type. However, independent of lock type, a successful DELETE
of a resource MUST cause all of its locks to be removed.
8.13.6. Lock Compatibility Table
The table below describes the behavior that occurs when a lock
request is made on a resource.
Current lock state/ Shared Lock Exclusive
Lock request Lock
None True True
Shared Lock True False
Exclusive Lock False False*
Legend: True = lock MAY be granted. False = lock MUST NOT be
granted. *=if the principal requesting the lock is the owner of the
lock, the lock MAY be regranted.
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
the lock must not be granted.
If an exclusive or shared lock is re-requested by the principal who
owns the lock, the lock MUST be regranted. If the lock is
regranted, the same lock token that was previously issued MUST be
returned.
8.13.7. Owner XML Element
Name: owner
Namespace: http://www.ietf.org/standards/dav/
Purpose: Provide information about the principal taking out a
lock.
Parent: Any
Values: XML Elements
Descripton: The Owner XML element provides 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 of a homepage) who owns a lock.
8.13.8. Lock Response
A successful lock response MUST contain a Lock-Token response
header, a Timeout header and a prop XML element in the response body
which contains the value of the lockdiscovery property.
8.13.9. Response Codes
409 Conflict - The resource is locked, so the method has been
rejected.
412 Precondition Failed - The included Lock-Token was not
enforceable on this resource or the server could not satisfy the
request in the Lock-Info header.
8.13.10. Example - Simple Lock Request
LOCK /workspace/webdav/proposal.doc HTTP/1.1
Host: webdav.sb.aol.com
Lock-Info: LockType=Write LockScope=Exclusive
Timeout: Infinite; Second-4100000000
Content-Type: text/xml
Content-Length: xyz
<?XML version="1.0">
<?namespace href="http://www.ietf.org/standards/dav/" AS = "D"?>
<D:owner>
<D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href>
</D:owner>
HTTP/1.1 200 OK HTTP/1.1 200 OK
Lock-Token: opaquelocktoken:xyz122393481230912asdfa09s8df09s7df
Timeout: Second-604800
Content-Type: text/xml
Content-Length: xxxxx
3.10 PATCH Method <?XML version="1.0">
<?namespace href ="http://www.ietf.org/standards/dav/" AS = "D"?>
<D:prop>
<D:lockdiscovery>
<D:activelock>
<D:locktype>write</D:locktype>
<D:lockscope>exclusive</D:lockscope>
<D:addlocks/>
<D:owner>
<D:href>
http://www.ics.uci.edu/~ejw/contact.html
</D:href>
</D:owner>
<D:timeout>Second-604800</D:timeout>
<D:locktoken>
<D:href>
opaquelocktoken:xyz122393481230912asdfa09s8df09s7df
</D:href>
</D:locktoken>
</D:activelock>
</D:lockdiscovery>
</D:prop>
3.10.1 Problem Definition This example shows the successful creation of an exclusive write
lock on resource
http://webdav.sb.aol.com/workspace/webdav/proposal.doc. The
resource http://www.ics.uci.edu/~ejw/contact.html contains contact
information for the owner of the lock. The server has an activity-
At present, if a principal wishes to modify a resource, they must based timeout policy in place on this resource, which causes the
issue a GET against the resource, modify their local copy of the lock to automatically be removed after 1 week (604800 seconds). The
resource, and then issue a PUT to place the modified resource on response has a Lock-Token header that gives the lock token URL that
the server. This procedure is inefficient because the entire uniquely identifies the lock created by this lock request.
entity for a resource must be transmitted to and from the server
in order to make even small changes. Ideally, the update entity
transmitted to the server should be proportional in size to the
modifications.
3.10.2 Solution Requirements 8.13.11. Example - Multi-Resource Lock Request
The solution must: LOCK /workspace/webdav/proposal.doc HTTP/1.1
- allow partial modification of a resource without having to Host: webdav.sb.aol.com
transmit the entire modified resource Lock-Info: LockType=Write LockScope=Exclusive
- allow byte-range patching Addlocks=<http://webdav.sb.aol.com/workspace/><http://foo.bar/blah>
- allows extensions so that patches can be done beyond simple Timeout: Infinite, Second-4100000000
byte-range patching
- allow ranges to be deleted, inserted, and replaced
3.10.3 The Request <?XML version="1.0">
<?namespace href="http://www.ietf.org/standards/dav/" AS = "D"?>
<D:href>http://www.ics.uci.edu/~ejw/contact.html<D:href>
HTTP/1.1 409 Conflict
Content-Type: text/xml
Content-Length: xxxxx
<?XML version="1.0">
<?namespace href = "http://www.ietf.org/standards/dav/" As = "D"?>
<D:multistatus>
<D:response>
<D:href>
http://webdav.sb.aol.com/workspace/webdav/proposal.doc
</D:href>
<D:href>
http://webdav.sb.aol.com/workspace/webdav/
</D:href>
<D:status>HTTP/1.1 202 Accepted</D:status>
</D:response>
<D:response>
<D:href>http://foo.bar/blah</D:href>
<D:status>HTTP/1.1 403 Forbidden</D:status>
</D:response>
</D:multistatus>
This example shows a request for an exclusive write lock on three
resources, http://webdav.sb.aol.com/workspace/webdav/proposal.doc,
http://webdav.sb.aol.com/workspace/, and http://foo.bar/blah. 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 Owner header field specifies the web
address for contact information for the principal taking out the
lock.
This lock request has failed, because the server rejected the lock
request for http://foo.bar/blah. The 409 Conflict status code
indicates that the server was unable to satisfy the request because
there is a conflict between the state of the resources and the
operation named in the request. Within the multistatus, the 202
Accepted status code indicates that the lock method was accepted by
the resources, and would have been completed if all resources named
in the request were able to be locked. The 403 Forbidden status
code indicates that the server does not allow lock requests on this
resource.
8.14. UNLOCK Method
The UNLOCK method removes the lock identified by the lock token in
the Lock-Token header from the Request-URI, and all other resources
included in the lock.
Any DAV compliant resource which supports the LOCK method MUST
support the UNLOCK method.
8.14.1. Example
UNLOCK /workspace/webdav/info.doc HTTP/1.1
Host: webdav.sb.aol.com
Lock-Token:opaquelocktoken:123AbcEfg1284h23h2
HTTP/1.1 200 OK
In this example, the lock identified by the lock token
"opaquelocktoken:123AbcEfg1284h23h2" is successfully removed from
the resource http://webdav.sb.aol.com/workspace/webdav/info.doc. If
this lock included more than just one resource, the lock was removed
from those resources as well.
8.15. PATCH Method
The PATCH method is used to modify parts of the entity returned in
the response to a GET method. DAV compliant resources MAY support
the PATCH method.
8.15.1. The Request
The request entity of the PATCH method contains a list of The request entity of the PATCH method contains a list of
differences between the resource identified by the Request-URI differences between the resource identified by the Request-URI and
and the desired content of the resource after the PATCH action the desired content of the resource after the PATCH action has been
has been applied. The list of differences is in a format defined applied. The list of differences is in a format defined by the
by the media type of the entity (e.g., "application/diff") and media type of the entity (e.g., "application/diff") and must include
must include sufficient information to allow the server to sufficient information to allow the server to convert the original
convert the original version of the resource to the desired version of the resource to the desired version. Processing
version. Processing performed by PATCH is atomic, hence all performed by PATCH is atomic. Hence all changes MUST be
changes MUST be successfully executed or the method fails. PATCH successfully executed or the method fails. PATCH MUST fail if
MUST fail if executed on a non-existent resource; i.e. PATCH does executed on a non-existent resource; i.e., PATCH does not create a
not create a resource as a side effect. resource as a side effect.
If the request appears (at least initially) to be acceptable, the If the request appears (at least initially) to be acceptable, the
server MUST transmit an interim 100 response message after server MUST transmit an interim 100 response message after receiving
receiving the empty line terminating the request headers and the empty line terminating the request headers and continue
continue processing the request. Since the semantics of PATCH processing the request. Since the semantics of PATCH are non-
are non-idempotent, responses to this method are not cacheable. idempotent, responses to this method are not cacheable.
While server support for PATCH is optional, if a server does While server support for PATCH is optional, if a server does support
support PATCH, it MUST support at least the text/xml diff format PATCH, it MUST support at least the text/xml diff format defined
defined below. Support for the VTML difference format [VTML] is below. Support for the VTML difference format [VTML] is
recommended, but not required. recommended, but not required.
3.10.4 text/xml elements for PATCH 8.15.2. text/xml elements for PATCH
The resourceupdate XML element contains a set of XML sub-entities The resourceupdate XML element contains a set of XML sub-entities
that describe modification operations. The name and meaning of that describe modification operations. The name and meaning of
these XML elements is given below. Processing of these directives these XML elements are given below. Processing of these directives
MUST be performed in the order encountered within the XML MUST be performed in the order encountered within the XML document.
document. A directive operates on the resource as modified by A directive operates on the resource as modified by all previous
all previous directives (executed in sequential order). The directives (executed in sequential order). The length of the
length of the resource MAY be extended or reduced by a PATCH. resource MAY be extended or reduced by a PATCH.
The changes specified by the resourceupdate XML element MUST be The changes specified by the resourceupdate XML element MUST be
executed atomically. executed atomically.
3.10.4.1 ResourceUpdate 8.15.2.1. resourceupdate XML Element
Name: http://www.ietf.org/standards/dav/patch/resourceupdate Name: resourceupdate
Purpose: Contains an ordered set of changes to a non- Namespace: http://www.ietf.org/standards/dav/patch/
collection, non-property resource. Purpose: Contains an ordered set of changes to a non-collection,
Schema: http://www.ietf.org/standards/dav/patch/ non-property resource.
Parent: Any Parent: None
Value: *(Insert | Delete | Replace) Value= *(insert | delete | replace)
3.10.4.2 Insert 8.15.2.2. insert XML Element
Name: http://www.ietf.org/standards/dav/patch/insert Name: insert
Purpose: Insert the XML elementís contents starting at the Namespace: http://www.ietf.org/standards/dav/patch/
Purpose: Insert the XML element's contents starting at the
specified octet. specified octet.
Schema: http://www.ietf.org/standards/dav/patch/ Parent: resourceupdate
Parent: ResourceUpdate Value: The insert XML element MUST contain an octet-range XML
Value: The insert XML element MUST contain an Octet-Range attribute that specifies an octet position within the body of a
XML element that specifies an octet position within the body of a resource. A value of _end_ specifies the end of the resource. The
resource. A value of "end" specifies the end of the resource. body of the insert XML element contains the octets to be inserted.
The body of the insert XML element contains the octets to be
inserted.
Please note that in order to protect the white space contained in Please note that in order to protect the white space contained in
this XML element the following attribute/value MUST be included this XML element the following attribute/value MUST be included in
in the element: XML-SPACE = "PRESERVE". the element: XML-SPACE = "PRESERVE". This attribute is defined in
the XML specification [Bray, Sperberg-McQueen, 1997].
3.10.4.3 Delete 8.15.2.3. delete XML Element
Name: http://www.ietf.org/standards/dav/patch/delete Name: delete
Namespace: http://www.ietf.org/standards/dav/patch/
Purpose: Removes the specified range of octets. Purpose: Removes the specified range of octets.
Schema: http://www.ietf.org/standards/dav/patch/ Parent: resourceupdate
Parent: ResourceUpdate Value: The delete XML element MUST contain an octet-range XML
Value: The Delete XML element MUST contain an octet-range attribute.
XML element.
Discussion: The octets that are deleted are removed, which means
the resource is collapsed and the length of the resource is
decremented by the size of the octet range. It is not
appropriate to replace deleted octets with zeroed-out octets,
since zero is a valid octet value.
3.10.4.4 Replace Discussion: The octets that are deleted are removed, which means the
resource is collapsed and the length of the resource is decremented
by the size of the octet range. It is not appropriate to replace
deleted octets with zeroed-out octets, since zero is a valid octet
value.
Name: http://www.ietf.org/standards/dav/patch/replace 8.15.2.4. replace XML Element
Purpose: Replaces the specified range of octets with the
contents of the XML element. If the number of octets in the XML
element is different from the number of octets specified, the Name: replace
update MUST be rejected. Namespace: http://www.ietf.org/standards/dav/patch/
Schema: http://www.ietf.org/standards/dav/patch/ Purpose: Replaces the specified range of octets with the contents
Parent: ResourceUpdate of the XML element. If the number of octets in the XML element is
Value: The Replace XML element MUST contain an octet- different from the number of octets specified, the update MUST be
range XML element. The contents of the entity are the replacement rejected.
octets. Parent: resourceupdate
Value: The replace XML element MUST contain an octet-range XML
attribute. The contents of the entity are the replacement octets.
Please note that in order to protect the white space contained in Please note that in order to protect the white space contained in
this XML element the following attribute/value MUST be included this XML element the following attribute/value MUST be included in
in the element: XML-SPACE = "PRESERVE". the element: XML-SPACE = "PRESERVE"
.
3.10.4.5 Octet-Range Attribute This attribute is defined in the
XML specification [Bray, Sperberg-McQueen, 1997].
Name: http://www.ietf.org/standards/dav/patch/octet- 8.15.2.5. octet-range Attribute
range
Name: octet-range
Namespace: http://www.ietf.org/standards/dav/patch/
Purpose: Specifies a range of octets that the enclosing property Purpose: Specifies a range of octets that the enclosing property
effects. affects.
Schema: http://www.ietf.org/standards/dav/patch/ Parent: insert | delete | replace
Parent: Insert, Delete, Replace Value: number [_-_ (number | _end_)]
Value: number ["-" (number | "end")]
Number = 1*Digit Number = 1*Digit
Description: Octet numbering begins with 0. If the octet contains Description: Octet numbering begins with 0. If the octet contains a
a single number then the operation is to begin at that octet and single number then the operation is to begin at that octet and to
to continue for a length specified by the operation. In the case continue for a length specified by the operation. In the case of a
of a delete, this would mean to delete a single octet. In the delete, this would mean to delete a single octet. In the case of an
case of an insert this would mean to begin the insertion at the insert this would mean to begin the insertion at the specified octet
specified octet and to continue for the length of the included and to continue for the length of the included value, extending the
value, extending the resource if necessary. In the case of resource if necessary. In the case of replace, the replace begins
replace, the replace begins at the specified octet and overwrites at the specified octet and overwrites all that follow to the length
all that follow to the length of the included value. of the included value.
3.10.5 The Response 8.15.3. Response Codes
200 (OK) - The request entity body was processed without error, 200 OK - The request entity body was processed without error,
resulting in an update to the state of the resource. resulting in an update to the state of the resource.
409 (Conflict) - If the update information in the request message 409 Conflict - If the update information in the request message body
body does not make sense given the current state of the resource does not make sense given the current state of the resource (e.g.,
(e.g., an instruction to delete a non-existent line), this status an instruction to delete a non-existent line), this status code MAY
code MAY be returned. be returned.
415 (Unsupported Media Type) - The server does not support the 415 Unsupported Media Type - The server does not support the content
content type of the update instructions in the request message type of the update instructions in the request message body.
body.
416 (Unprocessable Entity) - A new status code. The server 418 Unprocessable Entity - The entity body submitted with the PATCH
understands the content type of the request entity, but was was not understood by the resource.
unable to process the contained instructions.
417 (Insufficient Space on Resource) - The resource does not have 419 Insufficient Space on Resource - The resource does not have
sufficient space to record the state of the resource after the sufficient space to record the state of the resource after the
execution of this method. execution of this method.
3.10.6 Examples 8.15.4. HTML file modification Example
3.10.6.1 HTML file modification
The following example shows a modification of the title and The following example shows a modification of the title and contents
contents of the HTML resource http://www.example.org/hello.html. of the HTML resource http://www.example.org/hello.html.
Before: Before:
<HTML> <HTML>
<HEAD> <HEAD>
<TITLE>Hello world HTML page</TITLE> <TITLE>Hello world HTML page</TITLE>
</HEAD> </HEAD>
<BODY> <BODY>
<P>Hello, world!</P> <P>Hello, world!</P>
</BODY> </BODY>
</HTML> </HTML>
skipping to change at line 2143 skipping to change at line 2264
Before: Before:
<HTML> <HTML>
<HEAD> <HEAD>
<TITLE>Hello world HTML page</TITLE> <TITLE>Hello world HTML page</TITLE>
</HEAD> </HEAD>
<BODY> <BODY>
<P>Hello, world!</P> <P>Hello, world!</P>
</BODY> </BODY>
</HTML> </HTML>
PATCH Request: Response: PATCH Request: Response:
PATCH hello.html HTTP/1.1 PATCH hello.html HTTP/1.1
Host: www.example.org Host: www.example.org
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxx Content-Length: xxx
HTTP/1.1 100 Continue HTTP/1.1 100 Continue
<?XML:Namespace href =
Shttp://www.ietf.org/standards/dav/patch/" AS = "D"/> <?XML version="1.0">
<D:ResourceUpdate> <?namespace href = _http://www.ietf.org/standards/dav/patch/_ AS =
<Replace XML-SPACE = "PRESERVE"><octet-range>14</octet- _D_?>
range>&003CTITLE&003ENew Title&003C/TITLE&003E</Replace> <D:resourceupdate>
<Delete><octet-range>38-50</Delete> <D:replace XML-SPACE = "PRESERVE">
<Insert XML-SPACE = "PRESERVE"><octet-range>86</>& <D:octet-range>14</D:octet-range>&003CTITLE&003ENew
003CP&003ENew paragraph&003C/P&003E</Insert> Title&003C/TITLE&003E</D:replace>
</D:ResourceUpdate> <D:delete><D:octet-range>38-50</D:octet-range></D:delete>
<D:insert XML-SPACE = "PRESERVE"><D:octet-range>86</D:octet-
range>&003CP&003ENew paragraph&003C/P&003E</D:insert>
</D:resourceupdate>
HTTP/1.1 200 OK HTTP/1.1 200 OK
After: After:
<HTML> <HTML>
<HEAD> <HEAD>
<TITLE>New Title</TITLE> <TITLE>New Title</TITLE>
</HEAD> </HEAD>
<BODY> <BODY>
<P>Hello, world!</P> <P>Hello, world!</P>
<P>New paragraph</P> <P>New paragraph</P>
</BODY> </BODY>
</HTML> </HTML>
skipping to change at line 2171 skipping to change at line 2299
<HTML> <HTML>
<HEAD> <HEAD>
<TITLE>New Title</TITLE> <TITLE>New Title</TITLE>
</HEAD> </HEAD>
<BODY> <BODY>
<P>Hello, world!</P> <P>Hello, world!</P>
<P>New paragraph</P> <P>New paragraph</P>
</BODY> </BODY>
</HTML> </HTML>
3.11 Headers 9. HTTP Headers for Distributed Authoring
3.11.1 Destination Header
The Destination header specifies a destination resource for
methods such as COPY and MOVE, which take two URIs as parameters.
Destination= "Destination" ":" URI
3.11.2 Enforce-Live-Properties Header
The Enforce-Live-Properties header specifies properties that MUST
be "live" after they are copied (moved) to the destination
resource of a copy (or move). If the value "*" is given for the
header, then it designates all live properties on the source
resource. If the value is "Omit" then the server MUST NOT
duplicate on the destination resource any properties that are
defined on the source resource. If this header is not included
then the server is expected to act as defined by the default
property handling behavior of the associated method.
EnforceLiveProperties = "Enforce-Live-Properties" ":" ("*" |
"Omit" | 1#(Property-Name))
Property-Name = "<" URI ">"
3.11.3 Overwrite Header
The Overwrite header specifies whether the server should
overwrite the state of a non-null destination resource during a
COPY or MOVE. A value of "false" states that the server MUST NOT
perform the COPY or MOVE operation if the state of the
destination resource is non-null. By default, the value of
Overwrite is "true," and a client MAY omit this header from a
request when its value is "true." While the Overwrite header
appears to duplicate the functionality of the If-Match: * header
of HTTP/1.1, If-Match applies only to the Request-URI, and not to
the Destination of a COPY or MOVE.
Overwrite = "Overwrite" ":" ("true" | "false")
If there is a conflict and the Overwrite header equals "true", or
is absent and thus defaults to "true", then the method MUST fail
with a 409 Conflict.
3.11.4 Destroy Header
When deleting a resource the client often wishes to specify
exactly what sort of delete is being enacted. The Destroy header,
used with the Mandatory header, allows the client to specify the
end result they desire. The Destroy header is specified as
follows:
The Undelete token requests that, if possible, the resource
should be left in a state such that it can be undeleted. The
server is not required to honor this request.
The NoUndelete token requests that the resource MUST NOT be left
in a state such that it can be undeleted.
The VersionDestroy token includes the functionality of the
NoUndelete token and extends it to include having the server
remove all versioning references to the resource that it has
control over.
DestroyHeader = "Destroy" ":" #Choices
Choices = "VersionDestroy" | "NoUndelete" | "Undelete" | token 9.1. Collection-Member Header
|"<" URI ">" ; a token extension MUST NOT be used unless it is
specified in a RFC16, otherwise a URI MUST be used for
extensions.
3.11.5 Collection-Member Header CollectionMember = "Collection-Member" ":" URI ; URI is defined in
section 3.2.1 of [Fielding et al., 1997]
The Collection-Member header specifies the URI of an external The Collection-Member header specifies the URI of an external
resource to be added/deleted to/from a collection. resource to be added/deleted to/from a collection.
CollectionMember = "Collection-Member" ":" URI 9.2. DAV Header
3.12 Links
3.12.1 Source Link Property Type
Name: http://www.ietf.org/standards/dav/link/source
Purpose: The destination of the source link identifies the
resource that contains the unprocessed source of the linkís
source.
Schema: http://www.ietf.org/standards/dav/link/
Parent: Any
Value: An XML document with zero or more link XML
elements.
Discussion: The source of the link (src) is typically the URI of DAV = "DAV" ":" ("1" | "2" | extend)
the output resource on which the link is defined, and there is
typically only one destination (dst) of the link, which is the
URI where the unprocessed source of the resource may be accessed.
When more than one link destination exists, this specification
asserts no policy on ordering.
4 State Tokens This header indicates that the resource supports the DAV schema and
protocol to the level indicated. All DAV compliant resources MUST
return the DAV header on all OPTIONS responses.
4.1 Overview 9.3. Depth Header
4.1.1 Problem Description Depth = "Depth" ":" ("0" | "1" | "infinity")
There are times when a principal will want to predicate The Depth header is used with methods executed on collections to
successful execution of a method on the current state of a indicate whether the method is to be applied only to the collection
resource. While HTTP/1.1 provides a mechanism for conditional (Depth = 0), to the collection and its immediate children, (Depth =
execution of methods using entity tags via the "If-Match" and 1), or the collection and all its progeny (Depth = infinity). Note
"If-None-Match" headers, the mechanism is not sufficiently that Depth = 1 and Depth = infinity behavior only applies to
extensibleto express conditional statements involving more internal member resources, and not to external member resources.
generic state indicators, such as lock tokens.
The fundamental issue with entity tags is that they can only be The Depth header is only supported if a method's definition
generated by a resource. However there are times when a client explicitly provides for such support.
will want to be able to share state tokens between resources,
potentially on different servers, as well as be able to generate
certain types of lock tokens without first having to communicate
with a server.
For example, a principal may wish to require that resource B have The following rules are the default behavior for any method that
a certain state in order for a method to successfully execute on supports the depth header. A method MAY override these defaults by
resource A. If the client submits an e-tag from resource B to defining different behavior in its definition.
resource A, then A has no way of knowing that the e-tag is meant
to describe resource B.
Another example occurs when a principal wishes to predicate the Methods which support the depth header MAY choose not to support all
successful completion of a method on the absence of any locks on of the header's values and MAY define, on a case by case basis, the
a resource. It is not sufficient to submit an "If-None-Match: *" behavior of the method on a collection if a depth header is not
as this refers to the existence of an entity, not of a lock. present. For example, the MOVE method only supports Depth = infinity
and if a depth header is not present will act as if a Depth =
infinity header had been applied.
This draft defines the term "state token" as an identifier for a Clients MUST NOT rely upon methods executing on members of their
state of a resource. The sections below define requirements for hierarchies in any particular order or the execution being atomic.
state tokens and provide a state token syntax, along with two Note that methods MAY provide guarantees on ordering and atomicity.
new headers which can accept the new state token syntax.
4.1.2 Solution Requirements 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.
4.1.2.1 Syntax So, for example, an attempt to COPY a hierarchy may result in some
of the members being copied and some not.
Self-Describing. A state token must be self describing such that Any headers on a method with a depth header MUST be applied to all
upon inspecting a state token it is possible to determine what resources in the scope of the method. For example, an if-match
sort of state token it is, what resource(s) it applies to, and header will have its value applied against every resource in the
what state it represents. method's scope and will cause the method to fail if the header fails
to match.
This self-describing nature allows servers to accept tokens from If a resource, source or destination, within the scope of the method
other servers and potentially be able to coordinate state 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 Lock-Token request header.
information cross resource and cross site through standardized 9.4. Destination Header
protocols. For example, the execution of a request on resource A
can be predicated on the state of resource B, where A and B are
potentially on different servers.
Client Generable. The state token syntax must allow, when Destination = "Destination" ":" URI
appropriate, for clients to generate a state token without having
first communicated with a server.
One drawback of entity tags is that they are set by the server, The Destination header specifies a destination resource for methods
and there is no interoperable algorithm for calculating an entity such as COPY and MOVE, which take two URIs as parameters.
tag. Consequently, a client cannot generate an entity tag from a
particular state of a resource. However, a state token which
encodes an MD5 state hash could be calculated by a client based
on a client-held state of a resource, and then submitted to a
server in a conditional method invocation.
Another potential use for client generable state tokens is for a 9.5. Destroy Header
client to generate lock tokens with wild card fields, and hence
be able to express conditionals such as: "only execute this GET
if there are no write locks on this resource."
4.1.2.2 Conditonals DestroyHeader = "Destroy" ":" #Choices
Universal. A solution must be applicable to all requests. Choices = "VersionDestroy" | "NoUndelete" | "Undelete" | extend
Positive and Negative. Conditional expressions must allow for the
expression of both positive and negative state requirements.
4.2 State Token Syntax Extend = RFC-Reg | Coded-URL
State tokens are URLs employing the following syntax:
State-Token = "StateToken:" Type ":" Resources ":" State-Info
Type = "Type" "=" Caret-encoded-URL
Resources = "Res" "=" Caret-encoded-URL
Caret-encoded-URL = "^" Resource "^"
Resource = <A URI where all "^" characters are escaped>
State-Info = *(uchar | reserved) ; uchar, reserved defined
section 3.2.1 of RFC 2068
This proposal has created a new URL scheme for state tokens RFC-Req = Token ; This is a token value (defined in section 2.2 of
because a state token names a network resource using its normal [Fielding et al., 1997]) that has been published as an RFC.
name, which is typically state-invariant, along with additional
information that specifies a particular state of the resource.
Encoding the state information into the native URL scheme of the
network resource was not felt to be safe, since freedom from name
space collisions could not be guaranteed. If this proposal is
accepted, the StateToken URL scheme will need to be defined and
registered with IANA.
State Token URLs begin with the URL scheme name "StateToken" Coded-URL = "<" URI ">"
rather than the name of the particular state token type they
represent in order to make the URL self describing. Thus it is
possible to examine the URL and know, at a minimum, that it is a
state token.
Labeled name/value pairs are used within the token to allow new When deleting a resource the client often wishes to specify exactly
fields to be added. Processors of state tokens MUST be prepared what sort of delete should be performed. The Destroy header, used
to accept the fields in whatever order they are present and MUST with the Mandatory header, allows the client to specify the end
ignore any fields they do not understand. result it desires. The Destroy header is specified as follows:
The "Type" field specifies the type of the state information
encoded in the state token. A URL is used in order to avoid
namespace collisions.
The "Res" field identifies the resource for which the state token The Undelete token requests that, if possible, the resource should
be left in a state such that it can be undeleted. The server is not
required to honor this request.
specifies a particular state. Since commas and spaces are The NoUndelete token requests that the resource MUST NOT be left in
acceptable URL characters, a caret is used to delimit a URL. a state such that it can be undeleted.
Since a caret is an acceptable URL character, any instances of it
must be escaped using the % escape convention.
The State-Info production is expanded upon in descriptions of The VersionDestroy token includes the functionality of the
specific state token types, and is intended to contain the state NoUndelete token and extends it to include having the server remove
description information for a particular state token. all versioning references to the resource that it has control over.
4.3 State Token Conditional Headers 9.6. Enforce-Live-Properties Header
4.3.1 If-State-Match EnforceLiveProperties = "Enforce-Live-Properties_ _:" (_*_ | "Omit"
| 1*(Property-Name))
If-State-Match = "If-State-Match" ":" ("AND" | "OR") 1#("<" Property-Name = Coded-URL
State-Token ">")
The If-State-Match header is intended to have similar The Enforce-Live-Properties header specifies properties that MUST be
functionality to the If-Match header defined in section 14.25 of _live_ after they are copied (moved) to the destination resource of
RFC 2068. a copy (or move). If the value _*_ is given for the header, then it
designates all live properties on the source resource. If the value
is "Omit" then the server MUST NOT duplicate on the destination
resource any properties that are defined on the source resource. If
this header is not included then the server is expected to act as
If the AND keyword is used and all of the state tokens identify defined by the default property handling behavior of the associated
the state of the resource, then the server MAY perform the method.
requested method. If the OR keyword is used and any of the state
tokens identifies the current state of the resource, then server
MAY perform the requested method. If neither of the keyword
requirements is met, the server MUST NOT perform the requested
method, and MUST return a 412 (Precondition Failed) response.
4.3.2 If-None-State-Match 9.7. If-None-State-Match
If-None-State-Match = "If-None-State-Match" ":" 1#("<" State- If-None-State-Match = "If-None-State-Match" ":" 1#Coded-URL
Token ">")
The If-None-State-Match header is intended to have similar The If-None-State-Match header is intended to have similar
functionality to the If-None-Match header defined in section functionality to the If-None-Match header defined in section 14.26
14.26 of RFC 2068. of RFC 2068. However the if-none-state-match header is intended for
use with any URI which represents state information about a
resource, referred to as a state token. A typical example is a lock
token.
If any of the state tokens identifies the current state of the If any of the state tokens identifies the current state of the
resource, the server MUST NOT perform the requested method. resource, the server MUST NOT perform the requested method.
Instead, if the request method was GET, HEAD, INDEX, or GETMETA, Instead, if the request method was GET, HEAD, INDEX, or PROPFIND,
the server SHOULD respond with a 304 (Not Modified) response, the server SHOULD respond with a 304 Not Modified response,
including the cache-related entity-header fields (particularly including the cache-related entity-header fields (particularly ETag)
ETag) of the current state of the resource. For all other of the current state of the resource. For all other request
request methods, the server MUST respond with a status of 412 methods, the server MUST respond with a status of 412 Precondition
(Precondition Failed). Failed.
If none of the state tokens identifies the current state of the If none of the state tokens identifies the current state of the
resource, the server MAY perform the requested method. resource, the server MAY perform the requested method.
Note that the "AND" and "OR" keywords specified with the If- If any of the tokens is not recognized then the method MUST fail
State-Match header are intentionally not defined for If-None- with a 412 Precondition Failed.
State-Match, because this functionality is not required.
4.4 State Token Header
State-Token-Header = "State-Token" ":" 1#("<" State-Token ">")
The State Token header is intended to have similar functionality
to the etag header defined in section 14.20 of RFC 2068. The
purpose of the tag is to return state tokens defined on a
resource in a response. The contents of the state-token are not
guaranteed to be exhaustive and are generally used to return a
new state token that has been defined as the result of a method.
For example, if a LOCK method were successfully executed on a
resource the response would include a state token header with the
lock state token included.
4.5 E-Tags
E-tags have already been deployed using the If-Match and If-None-
Match headers. Introducing two mechanisms to express e-tags
would only confuse matters, therefore e-tags should continue to
be expressed using quoted strings and the If-Match and If-None-
Match headers.
5 Locking
5.1 Locking: Introduction
Locking is used to arbitrate access to a resource amongst
principals that have equal access rights to that resource.
This specification allows locks to vary over two parameters, the
number of principals involved and the type of access to be
granted. Furthermore, this document only provides the definition
of locking for one access type, write. However, the syntax is
extensible, and allows the specification of other access types.
5.1.1 Exclusive Vs. Shared Locks
The most basic form of lock is an exclusive lock. This is a lock
where the access right in question is only granted to a single
principal. The need for this arbitration results from a desire to
avoid having to constantly merge results. In fact, many users so
dislike having to merge that they would rather serialize their
access to a resource rather than have to constantly perform
merges.
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 right. Shared locks are provided for
this case. A shared lock allows multiple principals to receive a
lock, hence any principal with appropriate access can get the
lock.
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 the resource, those who are not, don't. Among those who
have access permission to write 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 (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 is potentially 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 is potentially
working on a resource.
Shared locks are included because experience from web distributed
authoring systems has indicated that exclusive write locks are
often too rigid. An exclusive write lock is used to enforce a
particular editing process: take out exclusive write lock, read
the resource, perform edits, write the resource, release the
lock. What happens if the lock isn't released? While the time-
out mechanism provides one solution, if you need to force the
release of a lock immediately, it doesn't help much. Granted, an
administrator can release the lock for you, but this could become
a significant burden for large sites. In addition there is the
problem that an administrator may not be immediately available.
Despite their potential problems, exclusive write locks are
extremely useful, since often a guarantee of freedom from
overwrite conflicts is what is needed. The tradeoff described in
this specification is to provide exclusive write locks, but also
to provide a less strict mechanism in the form of shared locks
which can be used by a set of people who trust each other and who
have access to a communications channel external to HTTP which
can be used to negotiate writing to the resource.
5.1.2 Required Support
A WebDAV compliant server is not required to support locking in
any form. If the server 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 server implementers have
said that they are willing to accept minimum requirements on all
services but locking. Locking policy strikes to the very heart of
their resource management and versioning systems and they require
control over what sort of locking will be made available. For
example, some systems 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, the
authors are proposing that locking be allowed as the sole axis of
negotiation within WebDAV.
5.2 LOCK Method
The following sections describe the LOCK method, which is used to
take out a lock of any access type. 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. Once the general LOCK method has been
described, subsequent sections describe the semantics of the
"write" access type, and the write lock.
5.2.1 Operation
A LOCK method invocation creates the lock specified by the Lock-
Info header on the Request-URI. Lock method requests SHOULD NOT
have a request body. A user-agent SHOULD submit an Owner header
field with a lock request.
A successful response to a lock invocation MUST include Lock-
Token and Time-Out headers.
5.2.2 The Effect of Locks on Properties and Containers
By default the scope of a lock is the entire state of the
resource, including its body and associated properties. As a
result, a lock on a resource also locks the resource's
properties, and a lock on a property may lock a property's
resource or may restrict the ability to lock the property's
resource. Only a single lock token MUST be used when a lock
extends to cover both a resource and its properties. Note that
certain lock types MAY override this behavior.
For containers, a lock also affects the ability to add or remove Note that the "AND" and "OR" keywords specified with the If-State-
members. The nature of the effect depends upon the type of access Match header are intentionally not defined for If-None-State-Match,
control involved. because this functionality is not required.
5.2.3 Locking Replicated Resources 9.8. If-State-Match
Some servers automatically replicate resources across multiple If-State-Match = "If-State-Match" ":" ("AND" | "OR") 1#Coded-URL
URLs. In such a circumstance the server MAY only accept a lock on
one of the URLs if the server can guarantee that the lock will be
honored across all the URLs.
5.2.4 Locking Multiple Resources The If-State-Match header is intended to have similar functionality
to the If-Match header defined in section 14.25 of RFC 2068.
However the If-State-Match header is intended for use with any URI
which represents state information about a resource. A typical
example is a lock token.
The LOCK method supports locking multiple resources If the AND keyword is used and all of the state tokens identify the
simultaneously by allowing for the listing of several URIs in the state of the resource, then the server MAY perform the requested
LOCK request. These URIs, in addition to the Request-URI, are method. If the OR keyword is used and any of the state tokens
then to be locked as a result of the LOCK method's invocation. identifies the current state of the resource, then the server MAY
When multiple resources are specified the LOCK method only perform the requested method. If the keyword requirement for the
succeeds if all specified resources are successfully locked. the keyword used is not met, the server MUST NOT perform the
requested method, and MUST return a 412 Precondition Failed
response.
The Lock-Tree option of the lock request specifies that the If any of the tokens is not recognized then the method MUST fail
resource and all its internal children (including internal with a 412 Precondition Failed.
collections, and their internal members) are to be locked. This
is another mechanism by which a request for a lock on multiple
resources can be specified.
Currently existing locks can not be extended to cover more or 9.9. Lock-Info Request Header
less resources, and any request to expand or contract the number
of resources in a lock MUST fail with a 409 Conflict status code.
So, for example, if resource A is exclusively write locked and
then the same principal asked to exclusively write lock resources
A, B, and C, the request would fail as A is already locked and
the lock can not be extended.
A successful result will return a single lock token which LockInfo = "Lock-Info" ":" DAVLockType SP DAVLockScope [SP
represents all the resources that have been locked. If an UNLOCK AdditionalLocks] [SP Lock-Tree]
is executed on this token, all associated resources are unlocked. DAVLockType = "LockType" "=" DAVLockTypeValue
DAVLockTypeValue = ("Write" | Extend)
DAVLockScope = "LockScope" "=" DAVLockScopeValue
DAVLockScopeValue = ("Exclusive" |"Shared" | Extend)
AdditionalLocks = "AddLocks" "=" 1*("<" URI ">")
Lock-Tree = "Lock-Tree" "=" ("T" | "F")
If the lock can not be granted to all resources, a 406 Conflict The Lock-Info request header specifies the scope and type of a lock
status code MUST be returned with a response entity body for a LOCK method request. The syntax specification below is
containing a multiresponse XML element describing which extensible, allowing new type and scope identifiers to be added.
resource(s) prevented the lock from being granted.
5.2.5 Interaction with other Methods The LockType field specifies the access type of the lock. At
present, this specification only defines one lock type, the "Write"
lock. The LockScope field specifies whether the lock is an
exclusive lock, or a shared lock. The AddLocks field specifies
additional URIs, beyond the Request-URI, to which the lock request
applies. The LockTree field is used to specify recursive locks. If
the LockTree field is "T", the lock request applies to the hierarchy
traversal of the internal member resources of the Request-URI, and
the AddLocks URIs, inclusive of the Request-URI and the AddLocks
URIs. It is not an error if LockTree is "T", and the Request-URI or
the AddLocks URIs have no internal member resources. By default,
the value of LockTree is "F", and this field MAY be omitted when its
value is "F".
The interaction of a LOCK with various methods is dependent upon 9.10. Lock-Token Request Header
the lock type. However, independent of lock type, a successful
DELETE of a resource MUST cause all of its locks to be removed.
5.2.6 Lock Compatibility Table Lock-Token = "Lock-Token" ":" 1#Coded-URL
The table below describes the behavior that occurs when a lock The Lock-Token request header, containing a lock token owned by the
request is made on a resource. requesting principal, is used by the principal to indicate that the
principal is aware of the existence of the lock specified by the
lock token.
Current lock state/ Shared Lock Exclusive Lock If the following conditions are met:
Lock request
None True True
Shared Lock True False
Exclusive Lock False False*
Legend: True = lock MAY be granted. False = lock MUST NOT be 1) The method is restricted by a lock type that requires the
granted. *=if the principal requesting the lock is the owner of submission of a lock token, such as a write lock,
the lock, the lock MAY be regranted. 2) The user-agent has authenticated itself as a principal,
3) The user-agent is submitting a method request to a resource on
which the principal owns a write lock,
The current lock state of a resource is given in the leftmost Then:
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 the lock must not be granted.
If an exclusive or shared lock is re-requested by the principal 1) The method request MUST include a Lock-Token header with the lock
who owns the lock, the lock MUST be regranted. If the lock is token, or,
regranted, the same lock token that was previously issued MUST be 2) The method MUST fail with a 409 Conflict status code.
returned.
5.2.7 Status Codes If multiple resources are involved with a method, such as a COPY or
MOVE method, then the lock tokens, if any, for all involved
resources, MUST be included in the Lock-Token request header.
409 "Conflict" - The resource is locked, so the method has been For example, Program A, used by user A, takes out a write lock on a
rejected. resource. Program A then makes a number of PUT requests on the
locked resource. All the requests contain a Lock-Token request
header that includes the write lock state token. Program B, also
run by User A, then proceeds to perform a PUT to the locked
resource. However, program B was not aware of the existence of the
lock and so does not include the appropriate Lock-Token request
header. The method is rejected even though principal A is
authorized to perform the PUT. Program B can, if it so chooses, now
perform lock discovery and obtain the lock token. Note that
programs A and B can perform GETs without using the Lock-Token
header because the ability to perform a GET is not affected by a
write lock.
412 "Precondition Failed" - The included state-token was not Having a lock token provides no special access rights. Anyone can
enforceable on this resource or the request in the lock-info find out anyone else's lock token by performing lock discovery.
header could not be satisfied by the server. Locks are to be enforced based upon whatever authentication
mechanism is used by the server, not based on the secrecy of the
token values.
5.2.8 Lock-Info Request Header 9.11. Lock-Token Response Header
Lock-Token = "Lock-Token" ":" Coded-URL
The Lock-Info request header specifies the scope and type of a If a resource is successfully locked then a Lock-Token header will
lock for a LOCK method request. The syntax specification below is be returned containing the lock token that represents the lock.
extensible, allowing new type and scope identifiers to be added.
LockInfo = "Lock-Info" ":" DAVLockType SP DAVLockScope [SP 9.12. Overwrite Header
AdditionalLocks] [SP Lock-Tree]
DAVLockType = "LockType" "=" DAVLockTypeValue
DAVLockTypeValue = ("Write" | *(uchar | reserved))
DAVLockScope = "LockScope" "=" DAVLockScopeValue
DAVLockScopeValue = ("Exclusive" |"Shared" | *(uchar | reserved))
AdditionalLocks = "AddLocks" "=" 1*("<" URI ">")
Lock-Tree = "Lock-Tree" "=" ("True" | "False")
The LockType field specifies the access type of the lock. At Overwrite = "Overwrite" ":" ("T" | "F")
present, this specification only defines one lock type, the
"Write" lock. The LockScope field specifies whether the lock is
an exclusive lock, or a shared lock. The AddLocks field The Overwrite header specifies whether the server should overwrite
specifies additional URIs, beyond the Request-URI, to which the the state of a non-null destination resource during a COPY or MOVE.
lock request applies. The LockTree field is used to specify A value of _F_ states that the server MUST NOT perform the COPY or
recursive locks. If the LockTree field is "true", the lock MOVE operation if the state of the destination resource is non-null.
request applies to the hierarchy traversal of the internal By default, the value of Overwrite is _T,_ and a client MAY omit
members resources of the Request-URI, and the AddLocks URIs, this header from a request when its value is _T._ While the
inclusive of the Request-URI and the AddLocks URIs. It is not an Overwrite header appears to duplicate the functionality of the If-
error if LockTree is true, and the Request-URI or the AddLocks Match: * header of HTTP/1.1, If-Match applies only to the Request-
URIs have no internal member resources. By default, the value of URI, and not to the Destination of a COPY or MOVE.
LockTree is "false", and this field MAY be omitted when its value
is false.
5.2.9 Owner Request Header If a COPY or MOVE is not performed due to the value of the Overwrite
header, the method MUST fail with a 409 Conflict status code.
5.2.9.1 Problem Description 9.13. Propfind Request Header
When discovering the list of owners of locks on a resource, a Propfind = "Propfind" ":" ("allprop" | "propname" | RFC-Reg |
principal may want to be able to contact the owner directly. For 1*(Property-Name))
this to be possible the lock discovery mechanism must provide
enough information for the lock owner to be contacted.
Additionally, programs may wish to be able to record structured
information in the owner header so that other programs may be
able to parse it later. Note, however, that these programs may
not necessarily be coordinating so there need be no guarantee
that the information can be parsed.
5.2.9.2 Solution Requirements The Propfind header is used to specify which properties are to be
returned in a PROPFIND method. The properties are identified by
their URIs. Two special tokens are defined for use with the
Propfind header, allprop and propname. The allprop token specifies
that all property names and values on the resource are to be
returned. The propname token specifies that only a list of property
names on the resource are to be returned.
Not all systems have authentication procedures that provide 9.14. Status-URI Response Header
sufficient information to identify a particular user in a way
that is meaningful to a person. In addition, many systems that do
have sufficient information, such as a name and e-mail address,
do not have the ability to associate this information with the
lock discovery mechanism. Therefore a means is needed to allow
principals to provide authentication in a manner which will be
meaningful to a person.
The From header (defined in RFC 2068), which contains only an The Status-URI response header MAY be used with the 102 Processing
email mailbox, is not sufficient for the purposes of quick response code to inform the client as to the status of a method.
identification. When desperately looking for someone to remove a
lock, e-mail is often not sufficient. A telephone number (cell
number, pager number, etc.) would be better. Furthermore, the
email address in the From header only optionally includes the
owners name and that name is often set to an alias anyway.
Therefore a header more flexible than From is required.
The value also needs to be such that both man and machine can Status-URI = "Status-URI" ":" *(Status-Code "<" URI ">") ; Status-
place values in it and later retrieve those values. Code is defined in 6.1.1 of [Fielding et al., 1997]
5.2.9.3 Syntax The URIs listed in the header are source resources which have been
affected by the outstanding method. The status code indicates the
resolution of the method on the identified resource. So, for
example, if a MOVE method on a collection is outstanding and a 102
"Processing" response with a Status-URI response header is returned,
the included URIs will indicate resources that have had move
attempted on them and what the result was.
Owner = "Owner" ":" (Coded-XML | quoted-string) 9.15. Timeout Header
Coded-XML = field-content ; XML where any character which is TimeOut = "Timeout" ":" 1#TimeType
not legal in field-content (see section 4.2 of [Fielding et al., TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other)
1997]) is XML encoded DAVTimeOutVal = 1*digit
Other = Extend field-value ; See section 4.2 of RFC 2068
The XML SHOULD provide information sufficient for either directly Clients MAY include Timeout headers in their LOCK requests.
contacting the principal (such as a telephone number or e-mail However, the server is not required to honor or even consider these
URI), or for discovering the principal (such as the URL of a requests. Clients MUST NOT submit a Timeout request header with any
homepage) who owns the lock. The quoted string SHOULD provide a method other than a LOCK method.
means for directly contacting the principal who owns the lock,
such as a name and telephone number. A Timeout request header MUST contain at least one TimeType and MAY
contain multiple TimeType entries. The purpose of listing multiple
TimeType entries is to indicate multiple different values and value
types that are acceptable to the client. The client lists the
TimeType entries in order of preference.
5.2.10 Time-Out Header The Timeout response header MUST use a Second value, Infinite, or a
TimeType the client has indicated familiarity with. The server MAY
assume a client is familiar with any TimeType submitted in a Timeout
header.
5.2.10.1 Problem Description The _Second_ TimeType specifies the number of seconds that MUST
elapse between granting of the lock at the server, and the automatic
removal of the lock. A server MUST not generate a timeout value for
_Second_ greater than 2^32-1.
In a perfect world principals take out locks, work on the The timeout counter is restarted any time an owner of the lock sends
resource, and then remove the lock when it is no longer needed. a method to any member of the lock, including unsupported methods,
However, this process is frequently not completed, leaving active or methods which are unsuccessful. It is recommended that the HEAD
but unused locks. Reasons for this include client programs method be used when the goal is simply to restart the timeout
crashing and losing information about locks, users leaving their counter.
systems for the day and forgetting to remove their locks, etc. As
a result of this behavior, servers need to establish a policy by
which they can remove a lock without input from the lock owner.
Once such a policy is instituted, the server also needs a
mechanism to inform the principal of the policy.
5.2.10.2 Solution Requirements If the timeout expires then the lock is lost. Specifically the
server SHOULD act as if an UNLOCK method was executed by the server
on the resource using the lock token of the timed-out lock,
performed with its override authority. Thus logs should be updated
with the disposition of the lock, notifications should be sent,
etc., just as they would be for an UNLOCK request.
There are two basic lock removal policies: administrator and time Servers are advised to pay close attention to the values submitted
based removal. In the case of administrator based removal, a by clients, as they will be indicative of the type of activity the
principal other than the lock owner has sufficient access rights client intends to perform. For example, an applet running in a
to order the lock removed, even though they did not take it out. browser may need to lock a resource, but because of the instability
The second policy type is time based removal. In this case, a of the environment within which the applet is running, the applet
timer is set as soon as the lock is created. Every time a method may be turned off without warning. As a result, the applet is
is executed on any resource covered by the lock, the timer is likely to ask for a relatively small timeout value so that if the
reset. If the timer runs out, the lock is removed. 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 off-line.
User-agents MUST assume that locks may arbitrarily disappear at 10. Response Code Extensions to HTTP/1.1
any time. If their actions require confirmation of the existence
of a lock then the If-State headers are available.
5.2.10.3 Syntax The following response codes are added to those defined in HTTP/1.1
[Fielding et al., 1997].
TimeOut = "Time-Out" ":" 1#TimeType 10.1. 102 Processing
TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Extend)
DAVTimeOutVal = 1*digit
Extend = RFC-Reg | URL "-" Token ; The URL format is used for
unregistered TimeTypes
RFC-Req = Token ; This is a TimeType that has been published as
an RFC
Clients MAY include TimeOut headers in their LOCK requests. Methods can potentially take a long period of time to process,
However the server is not required to honor or even consider the especially methods that support the Depth header. In such cases the
request. Clients MUST NOT submit a Time-Out request header with client may time-out the connection while waiting for a response. To
any method other than a LOCK method. prevent this the server MAY return a 102 response code to indicate
to the client that the server is still processing the method.
A Time-Out request header MUST contain at least one TimeType and If a method is taking longer than 20 seconds (a reasonable, but
MAY contain multiple TimeType entries. The purpose of listing arbitrary value) to process the server SHOULD return a 102
multiple TimeType is to indicate multiple different values and "Processing" response.
value types that are acceptable to the client. The client lists
the TimeType entries in order of preference.
The Time-Out response header MUST use a Second value, Infinite, 10.2. 207 Multi-Status
or a TimeType the client has indicated familiarity with. The
server MAY assume a client is familiar with any TimeType
submitted in a Time-Out header.
The "Second" TimeType specifies the number of seconds that MUST The response requires providing status for multiple independent
elapse between granting of the lock at the server, and the operations.
automatic removal of the lock. A server MUST not generate a time 10.3. 418 Unprocessable Entity
out value for "Second" greater than 2^32-1.
The time out counter is restarted any time the client sends a The server understands the content type of the request entity, but
method to any member of the lock, including unsupported methods, was unable to process the contained instructions.
or methods which are unsuccessful. It is recommended that the
HEAD method be used when the goal is simply to restart the time
out counter.
If the timeout expires then the lock is lost. Specifically the 10.4. 419 Insufficient Space on Resource
server SHOULD act as if an UNLOCK method was executed by the
server on the resource using the lock token of the timed-out
lock, performed with its override authority. Thus logs,
notifications, and other mechanisms that act as side effects to
the granting and removal of a lock will be properly informed as
to the disposition of the lock.
Servers are advised to pay close attention to the values The resource does not have sufficient space to record the state of
submitted by clients, as they will be indicative of the type of the resource after the execution of this method.
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 time-
out 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 time-out because its user may be planning
on going off-line.
5.2.11 Lock Response 10.5. 420 Method Failure
A successful lock response MUST contain a Lock-Token response The method was not executed on a particular resource within its
header, a Time-Out header and a PROP element in the response body scope because some part of the method's execution failed causing the
which contains the value of the LockDiscovery property. entire method to be aborted. For example, if a resource could not
be moved as part of a MOVE method, all the other resources would
fail with a 420 Method Failure.
5.2.11.1 Lock-Token Response Header 10.6. 421 Destination Locked
If a resource is successfully locked then a lock-token header The destination resource of a method is locked, and either the
will be returned containing the lock token that represents the request did not contain a valid Lock-Info header, or the Lock-Info
lock. header identifies a lock held by another principal.
Lock-Token = "Lock-Token" ":" URI 11. Multi-Status Response
5.2.12 Example - Simple Lock Request The default 207 Multi-Status response body is a text/xml HTTP entity
that contains a single XML element called multistatus, which
contains a set of XML elements called response, one for each 200,
300, 400, and 500 series status code generated during the method
invocation. 100 series status codes MUST NOT be recorded in a
response XML element.
LOCK /workspace/webdav/proposal.doc HTTP/1.1 11.1. multistatus XML Element
Host: webdav.sb.aol.com
Lock-Info: LockType=Write LockScope=Exclusive
Time-Out: Infinite; Second-4100000000
Owner: <?XML:Namespace href="http://www.ietf.org/standards/dav/"
AS =
"D"/><D:HREF>http://www.ics.uci.edu/~ejw/contact.html</D:HREF>
HTTP/1.1 200 OK Name: multistatus
Lock-Token: OpaqueLockToken:xyz122393481230912asdfa09s8df09s7df08 Namespace: http://www.ietf.org/standards/dav/
sd0f98a098sda Purpose: Contains multiple response messages.
Time-Out: Second-604800 Parent: Any
Content-Type: text/xml Value: 1*response [responsedescription]
Content-Length: xxxxx Description: The responsedescription 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.
<?XML:Namespace 11.2. response XML Element
href ="http://www.ietf.org/standards/dav/" AS = "D"/> Name: response
<D:Prop> Namespace: http://www.ietf.org/standards/dav/
<lockdiscovery> Purpose: Holds a single response
<activelock> Parent: multistatus
<locktype>write</locktype> Value: href [prop] status [responsedescription]
<lockscope>exclusive</lockscope> Description: Prop MUST contain one or more empty XML elements
<addlocks/> representing the names of properties. Multiple properties may be
<owner> included if the same response applies to them all. If href is used
<HREF>http://www.ics.uci.edu/~ejw/contact.html</HREF> then the response refers to a problem with the referenced resource,
</owner> not a property.
<timeout>Second-604800</timeout>
<locktoken>
<HREF>
OpaqueLockToken:xyz122393481230912asdfa09s8df09s7d
f08sd0f98a098sda
</HREF>
</locktoken>
</activelock>
</lockdiscovery>
</D:Prop>
This example shows the successful creation of an exclusive write 11.3. status XML Element
lock on resource
http://webdav.sb.aol.com/workspace/webdav/proposal.doc. The
resource http://www.ics.uci.edu/~ejw/contact.html contains
contact information for the owner 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). The response has a Lock-Token header that gives the
state token URL for the lock token generated by this lock
request.
5.2.13 Example - Multi-Resource Lock Request Name: status
Namespace: http://www.ietf.org/standards/dav/
Purpose: Holds a single HTTP status-line
Parent: response
Value: status-line ;status-line defined in [Fielding et al.,
1997]
LOCK /workspace/webdav/proposal.doc HTTP/1.1 11.4. responsedescription XML Element
Host: webdav.sb.aol.com
Lock-Info: LockType=Write LockScope=Exclusive
Addlocks=<http://webdav.sb.aol.com/workspace/><http://foo.bar/bla
h>
Time-Out: Infinite, Second-4100000000
Owner: <http://www.ics.uci.edu/~ejw/contact.html>
HTTP/1.1 409 Conflict Name: responsedescription
Content-Type: text/xml Namespace: http://www.ietf.org/standards/dav/
Content-Length: xxxxx Purpose: Contains a message that can be displayed to the user
explaining the nature of the response.
Parent: multistatus | response
Value: Any
Description: This XML element provides information suitable to be
presented to a user.
<?XML:Namespace href = 12. Generic DAV XML Elements
"http://www.ietf.org/standards/dav/" As = "D"/>
<D:MultiResponse>
<Response>
<HREF>
http://webdav.sb.aol.com/workspace/webdav/proposal.doc
</HREF>
<HREF>
http://webdav.sb.aol.com/workspace/webdav/
</HREF>
<Status>HTTP/1.1 202 Accepted</Status>
</Response>
<Response>
<HREF>http://foo.bar/blah</HREF>
<Status>HTTP/1.1 403 Forbidden</Status>
</Response>
</D:MultiResponse>
This example shows a request for an exclusive write lock on three 12.1. href XML Element
resources,
http://webdav.sb.aol.com/workspace/webdav/proposal.doc,
http://webdav.sb.aol.com/workspace/, and http://foo.bar/blah. 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 Owner header field specifies
the web address for contact information for the principal taking
out the lock.
This lock request has failed, because the server rejected the Name: href
lock request for http://foo.bar/blah. The 409 Conflict status Namespace: http://www.ietf.org/standards/dav/
code indicates that the server was unable to satisfy the request Purpose: To identify that the content of the element is a URI.
because there is a conflict between the state of the resources Parent: Any
and the operation named in the request. Within the Value: URI ; See section 3.2.1 of [Fielding et al., 1997]
multiresponse, the 202 Accepted status code indicates that the
lock method was accepted by the resources, and would have been
completed if all resources named in the request were able to be
locked. The 403 Forbidden status code indicates that the server
does not allow lock requests on this resource.
5.3 Write Lock 12.2. link XML Element
This section describes the semantics specific to the write access Name: link
type for locks. The write lock is a specific instance of a lock Namespace: http://www.ietf.org/standards/dav/
type, and is the only lock type described in this specification. Purpose: To identify a property as a link and to contain the
source and destination of that link.
Values= 1*src 1*dst
Description: Link is used to provide the sources and destinations of
a link. The type of the property containing the link XML element
provides the type of the link. Link is a multi-valued element, so
multiple Links may be used together to indicate multiple links with
the same type.
5.3.1 Methods Restricted by Write Locks 12.2.1. src XML Element
A write lock prevents a principal without the lock from Name: src
successfully executing a PUT, POST, PATCH, PROPPATCH, MOVE, Namespace: http://www.ietf.org/standards/dav/
DELETE, MKCOL, ADDREF or DELREF on the locked resource. All other Purpose: To indicate the source of a link.
current methods, GET in particular, function independent of the Parent: link
lock. Values= URI
Note, however, that as new methods are created it will be 12.2.2. dst XML Element
necessary to specify how they interact with a write lock.
5.3.2 Write Locks and Properties Name: dst
Namespace: http://www.ietf.org/standards/dav/
Purpose: To indicate the destination of a link
Parent: link
Values= URI
While those without a write lock may not alter a property on a 12.2.3. Example
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 to
respect locks are guaranteed to not change while write locked.
If a property is write locked then a LOCK request on the <?XML version="1.0">
associated resource MUST fail with a 409 "Conflict". Note that a <?namespace href = "http://www.ietf.org/standards/dav/" AS = "D"?>
write lock on a property MAY be extended to include the <?namespace href = "http://www.foocorp.com/Project/" AS = "F"?>
associated resource without the principal having explicitly <D:prop>
requested the extension. <D:Source>
<D:link>
<F:projfiles>Source</F:projfiles>
<D:src>http://foo.bar/program</D:src>
<D:dst>http://foo.bar/src/main.c</D:dst>
</D:link>
<D:link>
<F:projfiles>Library</F:projfiles>
<D:src>http://foo.bar/program</D:src>
<D:dst>http://foo.bar/src/main.lib</D:dst>
</D:link>
<D:link>
<F:projfiles>Makefile</F:projfiles>
<D:src>http://foo.bar/program</D:src>
<D:dst>http://foo.bar/src/makefile</D:dst>
</D:link>
</D:Source>
</D:prop>
5.3.3 Write Locks and Null Resources In this example the resource http://foo.bar/program has a source
property that contains three links. Each link contains three
elements, two of which, src and dst, are part of the DAV schema
defined in this document, and one which is defined by the schema
http://www.foocorp.com/project/ (