--- 1/draft-ietf-webdav-protocol-02.txt 2006-02-05 02:11:05.000000000 +0100 +++ 2/draft-ietf-webdav-protocol-03.txt 2006-02-05 02:11:06.000000000 +0100 @@ -1,17 +1,17 @@ WEBDAV Working Group Y. Y. Goland, Microsoft INTERNET-DRAFT E. J. Whitehead, Jr., U.C. Irvine - A. Faizi, Netscape + A. Faizi, Netscape S. R Carter, Novell D. Jensen, Novell - Expires March 8, 1998 September 3, 1997 + Expires April 6, 1998 September 29, 1997 Extensions for Distributed Authoring and Versioning on the World Wide Web -- WEBDAV Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also @@ -93,71 +93,84 @@ 3.1 Observations on the HTTP Object Model 3.1.1 Collection Resources 3.1.2Creation 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 INDEX Method - 3.3.1 Problem Description - 3.3.2 Solution Requirements - 3.3.3 The Request - 3.3.4 The Response - 3.3.5 Response Message Body - 3.3.6 Example - 3.4 Behavior of RFC 2068 Methods on Collections - 3.4.1 GET, HEAD for Collections - 3.4.2 POST for Collections - 3.4.3 PUT for Collections - 3.4.4 DELETE for Collections - 3.5 COPY Method - 3.5.1 Problem Description - 3.5.2 Solution Requirements - 3.5.3 The Request - 3.5.4 The Response - 3.5.5 Examples - 3.6 MOVE Method + 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 Resources + + 3.6 COPY Method 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 ADDREF Method - 3.7.1 Problem Definition - + 3.7 MOVE Method + 3.7.1 Problem Description 3.7.2 Solution Requirements 3.7.3 The Request - 3.8 DELREF Method + 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.9 PATCH Method + 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 application/XML elements for PATCH - 3.9.5 The Response - 3.9.6 Examples - 3.10 Headers - 3.10.1 Depth - 3.10.2 Destination - 3.10.3 Enforce-Live-Properties - 3.10.4 Duplicate-Properties - 3.10.5 Overwrite - 3.10.6 Destroy Header - 3.10.7 Mandatory header - 3.10.8 Collection-Member Header - 3.11 Links - 3.11.1 Source Link Property Type + 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-Tags @@ -1044,1140 +1059,1164 @@ HTTP/1.1 200 Success In this case only two of the properties have direct URLs available, while the other two properties can only be referenced - via PROPFIND and PROPPATCH. 3 A Proposal for Collections of Web Resources and Name Space Operations 3.1 Observations on the HTTP Object Model - As a prerequisite for specification of collections and name space - operations for the Web, a model for collection resources and for - namespace topology must be given. This section describes a new - type of Web resource, the collection resource, and provides a - model for discussing the relationship between the resources that - are generated as the result of a data-producing process, and the - source resources that describe the process. + This section provides a description of a new type of Web + resource, the collection, and discusses its interactions with the + HTTP URL namespace. This discussion is a prerequisite for the + specification of methods that operate on collections, given later + in this document. 3.1.1 Collection Resources - A collection is a Web resource type whose primary state is a set - of URIs and associated values that are recorded as properties on - the resource. The URIs identify resources that are members of - the collection. The values associated with each URI include - information such as the Last Modified Date, Entity Tag, Creation - Date, Content Type, Display Name, and whether the member is a - collection. - - A member of a collection is either an internal member resource, - which MUST have a URI that is relative to the base URI of the - collection, or an external member resource, which has a URI which - is not relative to the base URI of the collection. External - member resources are further subdivided into propagate members, - which have recursive method invocations propagated to them, and - no-propagate members, which do not. - - A collection resource may be viewed and used as a compound - resource in which the collection is a container for a group of - related resources that, together, form a larger logical unit. - For example, a collection of HTML resources where each resource - is the chapter of a book can be viewed as a compound resource - representing the entire book. - - Some methods, when invoked on a collection, affect the entire - collection. For example, it is possible to copy an entire - collection and its contents with just a single copy method - request. The model for performing these operations is a tree - traversal. The method is invoked on the collection, which then - performs the method on itself before propagating the method to - all its internal members and propagate external members. If - these are non-collection resources, the request method is - processed. However, if the request is propagated to another - collection, then the propagation begins again. This sequence of - actions causes the method to be propagated as a tree traversal of - the members of the collections. It is incumbent upon the client - to perform any locking operation on the collection or subordinate - members that it deems necessary in order to maintain state - consistency during the execution of such methods. + A collection is a resource whose state consists of a list of + internal members, a list of external members, and a set of + properties. An internal member resource MUST have a URI that is + 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 + objects (e.g., a filesystem directory) within a server's + namespace. Once these objects have been modeled with + collections, a client may perform an INDEX, add and remove + external members using ADDREF and DELREF, and perform recursive + operations, such as a full hierarchy copy. + To support methods which operate on collections, a server SHOULD + model its collection-like objects with collection resources. For + example, a server which is implemented on top of a filesystem + SHOULD treat all filesystem directories exposed by the server as + collection resources.1 3.1.2 Creation and Retrieval of Collection Resources - Since the existing HTTP methods for creating (PUT, POST) and - retrieving (GET) a resource were defined for non-collection - resources, it is not surprising that the semantics of these - methods do not transfer well to collections. For example, the PUT - - method is defined to store the request entity under the Request- - URI. While a description format for a collection can readily be - constructed that could be 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. + This document specifies the MKCOL method to create new collection + resources, and the INDEX method to list their contents.2 + In HTTP/1.1, the PUT method is defined to store the request body + at the location specified by Request-URI. While a description + format for a collection can readily be constructed that could be + 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 collection" POST command could be constructed, this is - undesirable because it would be difficult to provide separate - access control for collection creation and other uses of POST if - they both use the same method. - - The GET method when applied to collections is also problematic. + undesirable because it would be difficult to separate access + control for collection creation from other uses of POST if they + both use the same method. While it might seem desirable to have GET return a listing of the members of a collection, this is foiled by the existence of the "index.html" de-facto standard namespace redirection, in which a GET request on a collection is automatically redirected to the index.html resource. + The exact definition of the behavior of GET and PUT on + collections is defined later in this document. - Because of the difficulty of reusing some existing HTTP/1.1 - methods for collections, two new resource creation/retrieval - methods are needed. This specification introduces the MKCOL - method for creating collection resources, and the INDEX method - for retrieving the contents of a collection. + 3.1.2.1 Example - The exact definition of the behavior of GET and PUT on - collections is defined later in this draft. + The structured resource http://foo/bar is created with a PUT. Bar + 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 + http://foo/bar/b/d/e was created then a DELETE on d would fail + because d is a collection with an internal member. However the + existence of the collection d is something of an illusion. If a + DELETE was executed on http://foo/bar then everything would be + deleted, even though http://foo/bar/b/d was created with a MKCOL. + Thus the effect of a MKCOL within a composite resource’s + 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 For many resources, the entity returned by GET exactly matches 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, HTML files can sometimes be processed by the server - before being transmitted as a return entity body. Server-side- - include directives within an HTML file instruct a server to + However, the server can sometimes process HTML resources before + they are transmitted as a return entity body. For example, + 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 file + 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- 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. - - In the absence of distributed authoring capability, the fact that - - the source resource(s) for server generated output do not have a - mapping to the URI namespace is not a problem, and has desirable - security benefits. However, if remote editing of the source - resource(s) is desired, they should be given a location in the - URI namespace. This source location should not be one of the + In the absence of distributed authoring capability, it is + acceptable to have no mapping of source resource(s) to the URI + namespace, and in fact 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. For DAV compliant servers 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 single link on the output resource with type - http://www.ietf.org/standards/dav/link/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. - - In the general case, a large number of source resources can - comprise a data-producing process that generates many output - resources, creating a many-to-many relationship between output - resources and source resources. If each output resource had links - back to every source resource in the data-producing process, - there can be a potentially large number of such links. Due to the - potentially large number of links, and the lack of a policy for - ordering access to multiple sources, explicit storage of source - relationships is limited to cases with only a single source - resource. + resources and output resources. + For DAV compliant servers 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 single link on + 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 3.2.1 Problem Description - The client needs a way to create a collection. + A client must be able to create a collection. 3.2.2 Solution Requirements The solution: - Must ensure that a collection has been made (i.e. that it responds to the INDEX method) as opposed to a non-collection - resource. If a collection could not be made, it must indicate a - failure to the principal. - - The server MAY, if necessary, create any intermediate - collections so that the underlying storage medium is self- - consistent. - - + resource. If a collection could not be made, it must indicate + this failure to the user-agent. 3.2.3 Request - The MKCOL method 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 MAY add the Request-URI to one - or more collections within the server’s controlled namespace. + 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 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 - When MKCOL is invoked without a request body then the collection - created has no members. + When MKCOL is invoked without a request body, the newly created + 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 collections, members of a collection, bodies of members and properties on the collections or members. If the server + receives a MKCOL request entity type it does not support or understand it MUST respond with a 415 (Unsupported Media Type) - status code. - - 3.2.3.3 Creating Multiple Collections - - The server MAY create intermediate collections if they do not - already exist. For example, if the collection http://server/a/ - already exists in the server’s namespace, then while performing a - MKCOL to create http://server/a/b/c/ the server may also create a - collection at http://server/a/b/. + 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 Responses from a MKCOL request are not cacheable, since MKCOL has non-idempotent semantics. - 201 (Created) - The structured resource was created in its - entirety. - 403 (Forbidden) - The server does not allow the creation of - collections at the given location in its namespace. + 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. - 416 (Unprocessable Entity) - A new status code. The server - understands the content type of the request entity, but was - unable to process the contained instructions. + 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 /webdisc/xfiles/ on the server www.server.org. MKCOL /webdisc/xfiles/ HTTP/1.1 Host: www.server.org HTTP/1.1 201 Created - 3.3 INDEX Method - - 3.3.1 Problem Description - - A mechanism is needed to discover if a resource is a collection - and if so, list its members. - - 3.3.2 Solution Requirements - - The solution: - - must allow a client to discover the members of a collection - - must always provide a machine-readable description of the - membership of a collection - - - - 3.3.3 The Request - - The INDEX method returns a machine-readable representation of the - membership of the resource at the Request-URI. For a collection, - INDEX MUST return a machine-readable list of its members. For - other resources, the information returned by INDEX is undefined, - and MAY vary. The request message body of an INDEX request - SHOULD be ignored. - - The Depth header can be used to indicate how much of a result can - be generated for the response. The specific values allowed for - the depth header when used with the INDEX method are 1 and - infinity. The 1 value indicates that the internal and external - member resources should be reported in the result, infinity - indicates that all internal and external member resources and all - their descendants should be in the result. If the Depth header is - not given, then 1 is assumed. Servers MUST honor a depth of 1. - Servers MAY honor infinity. If the server does not support the - value of the depth header then a 412 (Precondition failed) MUST - be returned. - - 3.3.4 The Response - - 200 (OK) - The server MUST send an application/xml response - entity which describes the collection. - 404 (Not Found) - Same behavior as HTTP 1.1. The server never had - the resource, or the server permanently deleted the resource and - has no knowledge that it ever existed. This error code implies - that, essentially, the server has no information about the - Request URI. - - 3.3.5 Response Message Body - - The default INDEX response for a resource is an application/xml - HTTP entity (i.e., an Extensible Markup Language (XML) document) - that contains a single XML element called collectionresource - which describes the collection, and a set of XML elements called - memberesource which describe the members of the collection. - - The response from INDEX is cacheable, and SHOULD be accompanied - by an ETag header (see section 13.3.4 of RFC 2068). If GET and - INDEX return different entities for the same resource state, they - MUST return different entity tags. + 3.3 Standard DAV Properties - The server MUST transmit the following XML elements for each - member resource of a collection: Ref, IsCollection, Content-Type, - External. The server MUST transmit the following XML elements if - it can generate any meaningful values for them: Creation-Date, - Last-Modified, DisplayName, Content-Language. The server SHOULD - transmit Etag XML elements for each member (see section 13.3.4 of - RFC 2068). + The following properties are defined on DAV compliant resources. + All enclosed properties are part of the DAV Schema. - The value of content-type, last-modified, and etag XML elements - MUST be identical to the value of the response header field of - the same name in the HTTP/1.1 specification. Since the HTTP/1.1 - header fields are described in terms of the on-the-wire entity, - the values presented by INDEX are those that would be generated - if the resource was accessed using the GET method without content - negotiation. + 3.3.1 IsCollection Property - 3.3.5.1 CollectionResource + Name: http://www.ietf.org/standards/dav/iscollection + Purpose: This property contains a Boolean value that is set to + "true" if the resource is a collection + Schema: http://www.ietf.org/standards/dav/ + Value: ("true" | "false") + Description: This property MUST be defined on all DAV compliant + resources. - Name: http://www.ietf.org/standards/dav/collectionresource + 3.3.2 DisplayName Property - Purpose: Describes a collection + Name: http://www.ietf.org/standards/dav/displayname + Purpose: A name for the resource that is suitable for + presentation to a user. Schema: http://www.ietf.org/standards/dav/ - Parent: - Value: MemberResource + 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 a description of the resource + that is suitable for presentation to a user. - 3.3.5.2 MemberResource + 3.3.3 CreationDate3 Property - Name: http://www.ietf.org/standards/dav/memberresource - Purpose: Describes a member of a collection + Name: http://www.ietf.org/standards/dav/creationdate + Purpose: The time and 4date the resource was created. Schema: http://www.ietf.org/standards/dav/ - Parent: CollectionResource - Value: Ref, IsCollection, Content-Type, External, Creation- - Date, Last-Modified, ETag, DisplayName (other XML elements MAY - also be present) + 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.5.3 Ref + 3.3.4 GETentity Property5 - See XML definition. + Name: http://www.ietf.org/standards/dav/GETentity + Purpose: Contains the value of headers that are returned by a + GET without Accept headers. + 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.4 IsCollection + 3.3.5 INDEXentity Property - Name: http://www.ietf.org/standards/dav/iscollection - Purpose: This is a boolean value which is set to "true" if the - entry is a collection + Name: http://www.ietf.org/standards/dav/INDEXentity + Purpose: Contains the value of headers that are returned by an + INDEX. Schema: http://www.ietf.org/standards/dav/ - Parent: MemberResource - Value: ("true" | "false") + Value: Content-Type Content-Length Content-Language Last- + Modified Etag Creation-Date + Description: This property MUST be defined on all DAV compliant + resources unless INDEX 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.5 Content-Type + 3.3.6 Content-Type XML Element Name: http://www.ietf.org/standards/dav/content-type Purpose: The content-type of the member resource. Schema: http://www.ietf.org/standards/dav/ - Parent: MemberResource + Parent: GETentity or INDEXentity Value: media-type ; defined in Section 3.7 of [Fielding et al., 1997] - If no meaningful content-type can be generated, then an empty - value MUST be given. + 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.5.6 External + 3.3.7 Content-Length XML Element - Name: http://www.ietf.org/standards/dav/external - Purpose: If present, this element indicates the resource is an - external member of the collection. If the value is "propagate," - it is a propagate member, if the value is "no-propagate," it is a - no-propagate member. + Name: http://www.ietf.org/standards/dav/content-length + Purpose: Describes the default content-length of the resource. Schema: http://www.ietf.org/standards/dav/ - Parent: MemberResource - Value: ("propagate" | "no-propagate") + Value: content-length ; see section 14.14 of RFC 2068 + Description: If the parent of this element is GETentity, this - 3.3.5.7 Creation-Date + 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. - Name: http://www.ietf.org/standards/dav/creation-date - Purpose: The date the resource was created. + 3.3.8 Content-Language XML Element + + Name: http://www.ietf.org/standards/dav/content-language + Purpose: Describes the default natural language of a resource. Schema: http://www.ietf.org/standards/dav/ - Parent: MemberResource - Value: The date MUST be given in RFC 1123 format (rfc-1123 - production, defined in section 3.3.1 of [Fielding et al., 1997] + Value: language-tag ;language-tag is defined in section + 14.13 of RFC 2068 + Description: If the parent of this element is GETentity, this + element MUST have a value equal to the content-language header + returned by a GET on the resource without Accept headers. If the + parent is INDEXentity, the value MUST be identical to the + content- + language header returned by an INDEX on the resource. If no + content-language header is available, this element MUST NOT be + defined. - 3.3.5.8 Last-Modified + 3.3.9 Last-Modified XML Element Name: http://www.ietf.org/standards/dav/last-modified Purpose: The date the resource was last modified. Schema: http://www.ietf.org/standards/dav/ - Parent: MemberResource + Parent: GETentity or INDEXentity Value: The date MUST be given in RFC 1123 format (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 + 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.5.9 ETag + 3.3.10 Etag XML Element Name: http://www.ietf.org/standards/dav/etag Purpose: The entity tag of the resource. Schema: http://www.ietf.org/standards/dav/ - Parent: MemberResource + Parent: GETentity or INDEXentity Value: entity-tag ; defined in Section 3.11 of [Fielding et al., 1997] + Description: If the parent of this element is GETentity, this + 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.3.5.10 DisplayName + 3.4 INDEX Method - Name: http://www.ietf.org/standards/dav/displayname - Purpose: A name for the resource that is suitable for - presentation to a person + 3.4.1 Problem Description + + A mechanism is needed to discover if a resource is a collection + and if so, list its members. + + 3.4.2 Solution Requirements + + The solution: + - 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 INDEX method returns a machine-readable representation of the + membership of the resource at the Request-URI. 6 + + For a collection, INDEX MUST return a 7list of its members. All + WebDAV compliant resources MUST support the text/xml response + 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 + entity MUST contain only one ResInfo element. This ResInfo + element contains an Href element, which gives the identifier(s) + 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 + and available8: DisplayName, IsCollection, CreationDate, + GETentity, and INDEXentity. + + The response from INDEX is cacheable, and SHOULD be accompanied + by an ETag header (see section 13.3.4 of RFC 2068). If GET and + INDEX return different entities for the same resource state, they + MUST return different entity tags. + + 3.4.4 The Response + + 200 (OK) - The server MUST send a machine readable response + entity which describes the membership of the resource. + + 3.4.5 ResInfo XML Element + + Name: http://www.ietf.org/standards/dav/resinfo + Purpose: Describes a resource. Schema: http://www.ietf.org/standards/dav/ - Parent: MemberResource - Value: Any valid XML character data (from XML specification) + Parent: Any + Value: Href Prop Members9 + Description: There MUST be at least one Href element. Each Href + element contains a URI for the resource, which MUST be an + absolute URI. There MUST be a single Prop element that contains a + 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.3.5.11 Content-Language + 3.4.6 Members XML Element - Name: http://www.ietf.org/standards/dav/content-language - Purpose: Describes the natural language(s) of the intended - audience for the resource. - Schema: http://www.ietf.org.standards/dav/ - Parent: MemberResource - Value: 1#language-tag ;language-tag is defined in section - 14.13 of RFC 2068 + Name: http://www.ietf.org/standards/dav/members + Purpose: Describes the membership of a collection resource. - 3.3.6 Example + 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 + 10 + Name: http://www.ietf.org/standards/dav/href + 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 INDEX /user/yarong/dav_drafts/ HTTP/1.1 Host: www.microsoft.com - Depth: 1 HTTP/1.1 200 OK - Content-Type: application/xml + Content-Type: text/xml Content-Length: xxx - Last-Modified: xxx + Last-Modified: Thu, 11 Sep 1997 23:45:12 GMT ETag: "fooyyybar" - - http://www.ietf.org/standards/dav/D - - - namespace.doc - false - application/msword - false - Thu, 20 Mar 1997 23:05:25 GMT + + + + http://www.microsoft.com/user/yarong/dav_drafts/ + + + + WebDAV working drafts directory + + true + 19970418T070304Z + + text/html + 2754 + en + + Fri, 22 Aug 1997 10:11:26 GMT + + "8675309" + + + text/xml + xxx + + Thu, 11 Sep 1997 23:45:12 GMT + + "fooyyybar" + + - Fri, 22 Aug 1997 18:22:56 GMT - 8675309 - WebDAV Name Space Operations Draft - en - - + + + + http://www.microsoft.com/user/yarong/dav_drafts/base + + + + False + + + WebDAV Name Space Operations Draft + + 19970320T230525Z + + + application/msword + 1400 + en + + Fri, 22 Aug 1997 18:22:56 GMT + + "8675309" + + + + + This example shows the result of the INDEX method applied to the collection resource - http://www.microsoft.com/er/yarong/dav_drafts/. It returns a + http://www.microsoft.com/user/yarong/dav_drafts/. It returns a response body in XML format, which gives information about the - container’s sole member, - http://www.microsoft.com/users/yarong/dav_drafts/namespace.doc. + container and its sole member, + http://www.microsoft.com/user/yarong/dav_drafts/base. The entry + on the collection confirms that resource the INDEX was executed + on is a collection. The result also contains the URI of the + IsCollection property on the member resource. - 3.4 Behavior of RFC 2068 Methods on Collections + 3.5 Behavior of RFC 2068 Methods on Collections With the introduction of the collection resource type to the HTTP object model, it is necessary to define the behavior of the existing methods (defined in RFC 2068) when invoked on a 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.4.1 GET, HEAD for Collections + 3.5.1 GET, HEAD for Collections The semantics of GET are unchanged when applied to a collection, since GET is defined as, "retrieve whatever information (in the form of an entity) is identified by the Request-URI" [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 - response message body, the semantics of HEAD do not require any - modification when applied to collection resources. + response message body, the semantics of HEAD are unmodified when + applied to collection resources. - 3.4.2 POST for Collections + 3.5.2 POST for Collections Since by definition the actual function performed by POST is determined by the server and often depends on the particular resource, the behavior of POST when applied to collections cannot - be modified because it is largely undefined. Thus the semantics - of POST do not require any modification when applied to a - collection. - - 3.4.3 PUT for Collections - - In HTTP/1.1, PUT stores the request entity under the Request-URI, - and hence its semantics are limited to non-collection resources. - If a PUT is invoked on a collection resource it MUST fail. - - When the PUT operation creates a new non-collection resource, a - server MAY add that resource’s URI to one or more collections - within the server’s controlled namespace. + be meaningfully modified because it is largely undefined. Thus + the semantics of POST are unmodified when applied to a - 3.4.4 DELETE for Collections + collection. - When DELETE is applied to a collection resource, all internal + 3.5.3 PUT for Collections - members MUST be recursively deleted. The dav:link/propagate - external members MUST be deleted and their links must be removed. - dav:link/nopropagate external members MUST have only their link - removed; the resources MUST not be deleted. + As defined in the HTTP/1.1 specification [Fielding et al., 1997], + the "PUT method requests that the enclosed entity be stored under + the supplied Request-URI." Since submission of an entity + representing a collection would implicitly encode creation and + deletion of resources, this specification intentionally does not + define a transmission format for creating a collection using PUT. + Instead, the MKCOL method is defined to create collections. If a + PUT is invoked on a collection resource it MUST fail. + When the PUT operation creates a new non-collection resource all + ancestors MUST already exist. If all ancestors do not exist, the + method MUST fail with a 409 Conflict status code. For example, + if resource /a/b/c/d.html is to be created and /a/b/c/ does not + exist, then the request MUST fail. - The Depth header does not apply to the DELETE method. It cannot - be used to limit the extent of the operation. If it is present it - MUST be ignored. + 3.5.3.1 PUT for Non-Collection Resources - When applied to any resource, the DELETE method deletes all - properties on the Request-URI. + 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. - During DELETE processing, a server MAY remove the URI of the - deleted resource(s) from collections within its controlled - namespace. + 3.5.4 DELETE for Collections - 3.4.4.1 New Response Codes for DELETE + 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 code1112. - 207 (Partial Success) Only some of the member resources were - deleted. The response entity will describe any errors. + 3.5.5 13DELETE Method for Non-Collection Resources - 500 (Server Error) The resource was in such a state that it could - not be deleted. The response entity will describe reason for the - error. + 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.5 COPY Method + 3.6 COPY Method - 3.5.1 Problem Description + 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 making a copy, and because there - is often no way to fully express a resource as an entity without - a loss of fidelity. + entity with complete fidelity. + This is problematic because of the network traffic involved in + making a copy, and because there is often no way to fully express + a resource as an entity without a loss of fidelity. - 3.5.2 Solution Requirements + 3.6.2 Solution Requirements The solution: - MUST allow a principal to create a copy of a resource + without having to transmit the resource to and from the server. - 3.5.3 The Request + 3.6.3 The Request The COPY method creates a duplicate of the source resource, given by the Request-URI, in the destination resource, given by the Destination header. The Destination header MUST be present. The exact behavior of the COPY method depends on the type of the source resource. - 3.5.3.1 COPY for HTTP/1.1 resources + 3.6.3.1 COPY for HTTP/1.1 resources When the source resource is not a collection, and is not a property, the body of the destination resource MUST be octet-for- octet identical to the body of the source resource. Alterations to the destination resource do not modify the source resource. Alterations to the source resource do not modify the destination - resource. Thus, all copies are performed "by-value". + All properties on the source resource MUST be duplicated on the + destination resource, subject to modifying headers, following the + definition for copying properties. - If the Duplicate-Properties header is "false," then properties - SHOULD NOT be copied to the destination resource. If the - Duplicate-Properties header is "false" and the Enforce-Live- - Properties header is also present, the request MUST fail with a - 412 (Precondition Failed) status code. [Ed. Note: what if - resource to be copied has no properties, and no properties are - explicitly named in the header?] - - All properties on a source resource SHOULD be duplicated on the - destination resource following the definition for copying - properties. - - 3.5.3.2 COPY for Properties + 3.6.3.2 COPY for Properties + The following section defines how properties on a resource are + handled during a COPY operation. Live properties SHOULD be duplicated as identically behaving live properties at the destination resource. Since they are live properties, the server determines the syntax and semantics (hence value) of these properties. Properties named by the Enforce- Live- Properties header MUST be live on the destination resource, or the method MUST fail. If a property is not named by Enforce- Live- Properties and cannot be copied live, then its value MUST be - duplicated in an identically named, dead resource on the - destination resource. - - For every dead property defined on the source resource, there - SHOULD be an octet-for-octet identical dead property on the - destination resource. - - 3.5.3.3 COPY for Collections - - The Depth and Overwrite headers govern the behavior of COPY for - collections. - - When performing a recursive copy, all HTTP/1.1 request headers - are duplicated on the propagated method request except for the - precondition headers If-Modified-Since, If-Match, If-None-Match, - If-Range, If-Unmodified-Since, which should only be applied to - the Request-URI in order to determine if the operation should be - performed. The Destination header MUST be rewritten to preserve - the membership of the destination collection, i.e., by appending - the relative URI of the member to the URI of the destination - collection. - - A Depth of "0" indicates the collection MUST duplicate all of its - external members in a new collection at the Destination. Since - the COPY method is not propagated to its members, no internal - member resource is duplicated. - - A Depth of "1" indicates the collection MUST propagate the COPY - to all internal, non-collection members. If the Overwrite header - is "true" the COPY method duplicates all of its external members - in a new collection at the Destination. If the Overwrite header - is "false" and the destination resource is a collection, the COPY - method does not duplicate its external members, but is propagated - to all internal, non-collection members. + 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 + the overwrite header is set to TRUE then the property at the + destination MUST be overwritten with the property from the + source. If the overwrite header is false and the previous + situation exists then the COPY MUST fail with a 409 Conflict. - A Depth of "infinity" indicates the collection MUST propagate the - COPY method to all internal members. If the Overwrite header is - "true," the COPY method MUST duplicate all of its external + 3.6.3.3 COPY for Collections - members in a new collection at the Destination. If the Overwrite - header is "false" and the destination resource is a collection, - then the COPY method does not duplicate its external members, but - is propagated to all internal members. + A COPY on a collection causes a collection resource to be created + at the destination with the same properties, but without any + members, internal or external. All properties on the source + collection are copied over to the destination collection. Where + there is a conflict the source properties will overwrite the + destination properties. Any members at theMUST be duplicated on + the destination collection, subject to modifying headers, + following the definition for copying properties. - 3.5.3.4 Type Interactions + 3.6.3.4 Type Interactions If the destination resource identifies a property and the source resource is not a property, then the copy SHOULD fail. - If the destination resource identifies a collection and the Overwrite header is "true," prior to performing the copy, the + server MUST perform a DELETE operation on the collection. - 3.5.4 The Response + 3.6.4 The Response 200 (OK) The source resource was successfully copied to a pre- existing destination resource. - 201 (Created) The source resource was successfully copied. The copy operation resulted in the creation of a new resource. - - 207 (Partial Success) Only some of the member resources were - copied. The return entity body describes the status code for each - resource. - 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 false, and the state of the destination resource is non- null. - + 417 (Insufficient Space on Resource) - The destination resource + does not have sufficient space to record the state of the + resource after the execution of this method. 500 (Server Error) The resource was in such a state that it could - not be copied. This may occur if the Destination header indicated - an external (from the point of view of the server) resource and - the server has no capability to copy to an external resource. - - 502 (Bad Gateway) - This may occur when copying to external - resources and the destination server refused to accept the - resource. + 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.5.5 Examples + 3.6.5 Examples - 3.5.5.1 Overwrite Example + 3.6.5.1 Overwrite Example This example shows resource http://www.ics.uci.edu/~fielding/index.html being copied to the location http://www.ics.uci.edu/users/f/fielding/index.html. The contents of the destination resource were overwritten, if non- null. COPY /~fielding/index.html HTTP/1.1 Host: www.ics.uci.edu - Destination: - http://www.ics.uci.edu/users/f/fielding/index.html - Overwrite: "true" + Destination: http://www.ics.uci.edu/users/f/fielding/index.html HTTP/1.1 200 OK - 3.5.5.2 No Overwrite Example + 3.6.5.2 No Overwrite Example The following example shows the same copy operation being performed, except with the Overwrite header set to "false." A response of 412, Precondition Failed, is returned because the destination resource has a non-null state. + COPY /~fielding/index.html HTTP/1.1 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" HTTP/1.1 412 Precondition Failed - 3.6 MOVE Method + 3.7 MOVE Method - 3.6.1 Problem Description + 3.7.1 Problem Description The move operation on a resource is the logical equivalent of a - copy followed by a delete. - - In HTTP 1.1, the procedure could be performed in several steps. - First, the client could issue a GET to retrieve a representation - of a resource, issue a DELETE to remove the resource from the - server, then use PUT to place the resource on the server with a - new URI. As is the case for COPY - because of the network traffic - involved in making a move, and because there is often no way to - fully express a resource as an entity without a loss of fidelity - - server move functionality is preferable. - - With a DAV server, a principal may accomplish this task by + copy followed by a delete, where the actions are performed + atomically. Using RFC 2068 methods only, this procedure could be + performed in several steps. First, the client could issue a GET + to retrieve a representation of a resource, issue a DELETE to + remove the resource from the server, then use PUT to place the + resource on the server with a new URI. As is the case for COPY - + because of the network traffic involved in making a move, and + because there is often no way to fully express a resource as an + entity without a loss of fidelity - server move functionality is + preferable. + With a WEBDAV server, a principal may accomplish this task by issuing a COPY and then DELETE. Network load decreases, but the server load may still be significant because the server must create a duplicate resource. Were a server to know beforehand that a principal intended to perform COPY and DELETE operations in succession, it could avoid the creation of a duplicate resource. - 3.6.2 Solution Requirements + 3.7.2 Solution Requirements The solution: - Must prevent the unneeded transfer of entity bodies from and to the server. - Must prevent the unneeded creation of copies by the server. - 3.6.3 The Request + 3.7.3 The Request - The MOVE method is defined as the logical equivalent of a COPY - followed by a DELETE of the source resource, performed - atomically. + The move operation on a resource is the logical equivalent of a + 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.6.4 The Response + 3.7.4 The Response 200 (OK) - The resource was moved. A successful response must 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. - - 207 (Partial Success) Only some of the member resources were - moved. The return entity body will give the status code for each - resource. - 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 false, and the state of the destination resource is non- null. - 501 (Not Implemented) - This may occur if the Destination header specifies a resource which is outside its domain of control (e.g., stored on another server) resource and the server either refuses or is incapable of moving to an external resource. - 502 (Bad Gateway) - This may occur when moving to external resources and the destination server refused to accept the resource. - 3.6.5 Examples + 3.7.5 Examples + + 3.7.5.1 Overwrite Example - 3.6.5.1 Overwrite Example This example shows resource http://www.ics.uci.edu/~fielding/index.html being moved to the location http://www.ics.uci.edu/users/f/fielding/index.html. The contents of the destination resource were overwritten, if non- null. + MOVE /~fielding/index.html HTTP/1.1 Host: www.ics.uci.edu - Destination: - http://www.ics.uci.edu/users/f/fielding/index.html - Overwrite: true + Destination: http://www.ics.uci.edu/users/f/fielding/index.html HTTP/1.1 200 OK Content-Location: http://www.ics.uci.edu/users/f/fielding/index.html - 3.7 ADDREF Method + 3.8 ADDREF Method - 3.7.1 Problem Definition + 3.8.1 Problem Definition There needs to be a way to add an external member to a collection. - 3.7.2 Solution Requirements + 3.8.2 Solution Requirements The solution must: - allow access control - allow referencing to URIs of external members - not require a body - 3.7.3 The Request + 3.8.3 The Request 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. - The propagation type of the external URI is specified in the - Collection-Member Header. + It is not an error if the URI specified in the Collection-Member + 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 DELREF Method + 3.8.4 Example - 3.8.1 Problem Definition + ADDREF /~whitehead/dav/ HTTP/1.1 + HOST: www.ics.udi.edu + Collection-Member: http://www.ietf.org/standards/dav/ + + HTTP/1.1 200 OK + + 3.9 DELREF Method + + 3.9.1 Problem Definition There needs to be a way to remove an external member from a collection. - 3.8.2 Solution Requirements + 3.9.2 Solution Requirements The solution must: - allow access control - allow referencing to URIs of external members - not require a body - 3.8.3 The Request + 3.9.3 The Request The DELREF method removes the URI specified in the Collection- Member header from the collection specified by the Request-URI. + DELREFing a URI which is not a member of the collection is not an + error. DELREFing an internal member MUST fail with a 412 + Precondition Failed status code. - 3.9 PATCH Method + 3.9.4 Example - 3.9.1 Problem Definition + DELREF /~whitehead/dav/ HTTP/1.1 + Host: www.ics.udi.edu + Collection-Member: http://www.ietf.org/standards/dav/ + + HTTP/1.1 200 OK + + 3.10 PATCH Method + + 3.10.1 Problem Definition At present, if a principal wishes to modify a resource, they must issue a GET against the resource, modify their local copy of the resource, and then issue a PUT to place the modified resource on the server. This procedure is inefficient because the entire 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.9.2 Solution Requirements + 3.10.2 Solution Requirements The solution must: - allow partial modification of a resource without having to transmit the entire modified resource - allow byte-range patching - allows extensions so that patches can be done beyond simple byte-range patching - allow ranges to be deleted, inserted, and replaced - 3.9.3 The Request + 3.10.3 The Request - The PATCH method contains a list of differences between the - original version of the resource identified by the Request-URI + The request entity of the PATCH method contains a list of + differences between the resource identified by the Request-URI and the desired content of the resource after the PATCH action has been applied. The list of differences is in a format defined by the media type of the entity (e.g., "application/diff") and must include sufficient information to allow the server to - convert the original version of the resource to the desired - version. - - Since the semantics of PATCH are non-idempotent, responses to - this method are not cacheable. + convert the original version of the resource to the desired + version. Processing performed by PATCH is atomic, hence all + changes MUST be successfully executed or the method fails. PATCH + MUST fail if executed on a non-existent resource; i.e. PATCH does + not create a resource as a side effect. If the request appears (at least initially) to be acceptable, the server MUST transmit an interim 100 response message after receiving the empty line terminating the request headers and - continue processing the request. - + continue processing the request. Since the semantics of PATCH + are non-idempotent, responses to this method are not cacheable. While server support for PATCH is optional, if a server does - support PATCH, it MUST support at least the application/xml diff - format defined below. Support for the VTML difference format - [VTML] is recommended, but not required. + support PATCH, it MUST support at least the text/xml diff format + defined below. Support for the VTML difference format [VTML] is + recommended, but not required. - 3.9.4 application/XML elements for PATCH + 3.10.4 text/xml elements for PATCH - The resourceupdate XML elementXML element contains a set of XML - sub-entities that describe modification operations. The name and - meaning of these XML elements is given below. Processing of these - directives MUST be performed in the order encountered within the - XML document. A directive operates on the resource as modified - by all previous directives (executed in sequential order). + The resourceupdate XML element contains a set of XML sub-entities + that describe modification operations. The name and meaning of + these XML elements is given below. Processing of these directives + MUST be performed in the order encountered within the XML + document. A directive operates on the resource as modified by + all previous directives (executed in sequential order). The + length of the resource MAY be extended or reduced by a PATCH. + The changes specified by the resourceupdate XML element MUST be + executed atomically. - 3.9.4.1 ResourceUpdate + 3.10.4.1 ResourceUpdate Name: http://www.ietf.org/standards/dav/patch/resourceupdate - Purpose: Contains an ordered set of changes to a non-collection, - non-property resource. + Purpose: Contains an ordered set of changes to a non- + collection, non-property resource. Schema: http://www.ietf.org/standards/dav/patch/ - Parent: + Parent: Any Value: *(Insert | Delete | Replace) - 3.9.4.2 Insert + 3.10.4.2 Insert Name: http://www.ietf.org/standards/dav/patch/insert - Purpose: Insert the XML elementXML element’s contents starting - exactly at the specified octet. + Purpose: Insert the XML element’s contents starting at the + specified octet. Schema: http://www.ietf.org/standards/dav/patch/ Parent: ResourceUpdate - Value: The insert XML elementXML element MUST contain an octet - XML elementXML element that specifies an octet position within - the body of a resource. A value of "end" specifies the end of - the resource. The body of the insert XML elementXML element - contains the octets to be inserted. + Value: The insert XML element MUST contain an Octet-Range + XML element that specifies an octet position within the body of a + resource. A value of "end" specifies the end of the resource. + 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 + this XML element the following attribute/value MUST be included + in the element: XML-SPACE = "PRESERVE". - 3.9.4.3 Delete + 3.10.4.3 Delete Name: http://www.ietf.org/standards/dav/patch/delete Purpose: Removes the specified range of octets. Schema: http://www.ietf.org/standards/dav/patch/ Parent: ResourceUpdate - Value: The Delete XML elementXML element MUST contain an - octet- - range XML elementXML element. The value of this XML elementXML - element is empty. - Discussion: The octets which are deleted are removed, which means + Value: The Delete XML element MUST contain an octet-range + 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.9.4.4 Replace + 3.10.4.4 Replace Name: http://www.ietf.org/standards/dav/patch/replace 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 update MUST be rejected. Schema: http://www.ietf.org/standards/dav/patch/ Parent: ResourceUpdate - Value: The Replace XML element MUST contain an octet-range XML - element. The contents of the entity are the replacement octets. + Value: The Replace XML element MUST contain an octet- + range XML element. The contents of the entity are the replacement + octets. + Please note that in order to protect the white space contained in + this XML element the following attribute/value MUST be included + in the element: XML-SPACE = "PRESERVE". - 3.9.4.5 Octet-Range Attribute + 3.10.4.5 Octet-Range Attribute Name: http://www.ietf.org/standards/dav/patch/octet- range - Purpose: Specifies a range of octets which the enclosing - property effects. + Purpose: Specifies a range of octets that the enclosing property + effects. Schema: http://www.ietf.org/standards/dav/patch/ Parent: Insert, Delete, Replace Value: number ["-" (number | "end")] Number = 1*Digit Description: Octet numbering begins with 0. If the octet contains a single number then the operation is to begin at that octet and to continue for a length specified by the operation. In the case - of a delete, this would mean to delete but a single octet. In the + of a delete, this would mean to delete a single octet. In the case of an insert this would mean to begin the insertion at the specified octet and to continue for the length of the included value, extending the resource if necessary. In the case of replace, the replace begins at the specified octet and overwrites - all that follow to the length of the included value. Octet - values MUST specify locations in the state of the resource prior - to the processing of the PATCH method. + all that follow to the length of the included value. - 3.9.5 The Response + 3.10.5 The Response 200 (OK) - The request entity body was processed without error, resulting in an update to the state of the resource. - 409 (Conflict) - If the update information in the request message body does not make sense given the current state of the resource (e.g., an instruction to delete a non-existent line), this status code MAY be returned. - 415 (Unsupported Media Type) - The server does not support the content type of the update instructions in the request message body. - 416 (Unprocessable Entity) - A new status code. The server understands the content type of the request entity, but was unable to process the contained instructions. + 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.9.6 Examples + 3.10.6 Examples - 3.9.6.1 HTML file modification + 3.10.6.1 HTML file modification The following example shows a modification of the title and contents of the HTML resource http://www.example.org/hello.html. Before: Hello world HTML page -

Hello, world!

PATCH Request: Response: PATCH hello.html HTTP/1.1 Host: www.example.org - Content-Type: application/xml + Content-Type: text/xml Content-Length: xxx HTTP/1.1 100 Continue - - http://www.ietf.org/standards/dav/patch/ - D + - 14&003CTITLE&003ENew - Title&003C/TITLE&003E - 38-50 - 86&003CP&003ENew - paragraph&003C/P&003E - - + 14&003CTITLE&003ENew Title&003C/TITLE&003E + 38-50 + 86&003CP&003ENew paragraph&003C/P&003E + HTTP/1.1 200 OK After: New Title

Hello, world!

New paragraph

- 3.10 Headers - - 3.10.1 Depth - - The Depth header determines the depth to which a method is - propagated on a resource’s children. - Depth = "Depth" ":" DepthToken - DepthToken = "0" | "1" | "infinity" | token - - The optional token allows for extension. A server MUST ignore a - Depth header with an unknown value. + 14 + 3.11 Headers - 3.10.2 Destination + 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.10.3 Enforce-Live-Properties + 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. + 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" ":" ("*" | - 1#( Property-Name )) - Property-Name = <"> URI <"> - - 3.10.4 Duplicate-Properties - - The Duplicate-Properties header instructs the server whether to - duplicate the source resource’s properties onto the destination - resource during a COPY or MOVE. A value of "false" requires that - the server MUST NOT duplicate on the destination resource any - properties that are defined on the source resource. By default, - the value of this header is "true," and a client MAY omit this - header from a request when its value is "true." - Duplicate-Properties = "Duplicate-Properties" ":" ("true" | - "false") - - 3.10.5 Overwrite + "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 "false," and a client MAY omit this header from a - request when its value is "false." While the Overwrite header + 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.10.6 Destroy Header + 3.11.4 Destroy Header15 When deleting a resource the client often wishes to specify exactly what sort of delete is being enacted. The Destroy header, - used with PEP [Connolly et al., 1997], allows the client to - specify the end result they desire. The Destroy header is - specified as follows: - DestroyHeader = "Destroy" ":" #Choices - Choices = "VersionDestroy" | "NoUndelete" | "Undelete" | - Token - + 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 + |"<" URI ">" ; a token extension MUST NOT be used unless it is + specified in a RFC16, otherwise a URI MUST be used for + extensions. - 3.10.7 Mandatory header - - The Mandatory header is used to indicate a list of other header - field names which must be understood by the receiver before the - contents of the message can be stored, cached, or presented to a - user. This header is used to alert the receiver that, unlike the - default behavior, it cannot safely ignore the semantics of the - listed field-names if they are not understood. - - Mandatory = "Mandatory" ":" 1#field-name - - 3.10.8 Collection-Member Header + 3.11.5 Collection-Member Header The Collection-Member header specifies the URI of an external resource to be added/deleted to/from a collection. - CollectionMember = "Collection-Member" ":" PropType SP URI - PropType = "propagation" "=" ("prop" | "noprop") + CollectionMember = "Collection-Member" ":" URI - 3.11 Links + 3.12 Links - 3.11.1 Source Link Property Type + 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. + 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 + 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, DAV asserts no policy - on partial ordering. + When more than one link destination exists, this specification + asserts no policy on ordering. 4 State Tokens 4.1 Overview 4.1.1 Problem Description There are times when a principal will want to predicate successful execution of a method on the current state of a resource. While HTTP/1.1 provides a mechanism for conditional @@ -2509,26 +2546,27 @@ its members are locked or no lock is granted. The result of a Depth 1 lock is a single lock token which represents the lock on the container and all of its members. This lock token may be used in an If-State-Match or If-Not-State-Match header against any of the resources covered by the lock. Since the lock token represents a lock on all the resources, an UNLOCK using that token will remove the lock from all included resources, not - just the resource the UNLOCK was executed on. · A Depth of infinity means that the LOCK is recursively - executed, with a Depth of infinity, on the collection and all of - its propagate members and all of their propagate members. As with + executed, with a Depth of infinity, on the collection and all + of + its propagate members and all of their propagate members. As + with a Depth of 1, the LOCK must be granted in total or not at all. Otherwise the lock operates in the same manner as a Depth of 1 lock. The default behavior when locking a container is to act as if a "Depth: 0" header had been placed on the method. 5.2.3 Locking Replicated Resources Some servers automatically replicate resources across multiple