10.5. Lock-Token Header Lock-Token = "Lock-Token" ":" Coded-URL The Lock-Token request header is used with the UNLOCK method to identify the lock to be removed. The lock token in the Lock-Token request header MUST identify a lock that contains the resource identified by Request-URI as a member. The Lock-Token response header is used with the LOCK method to indicate the lock token created as a result of a successful LOCK request to create a new lock. 10.6. Overwrite Header Overwrite = "Overwrite" ":" ("T" | "F") The Overwrite request header specifies whether the server should overwrite a resource mapped to the destination URL during a COPY or MOVE. A value of "F" states that the server must not perform the COPY or MOVE operation if the destination URL does map to a resource. If the overwrite header is not included in a COPY or MOVE request, then the resource MUST treat the request as if it has an overwrite header of value "T". While the Overwrite header appears to duplicate the functionality of using an "If-Match: *" header (see [RFC2616]), If-Match applies only to the Request-URI, and not to the Destination of a COPY or MOVE. If a COPY or MOVE is not performed due to the value of the Overwrite header, the method MUST fail with a 412 (Precondition Failed) status code. The server MUST do authorization checks before checking this or any conditional header. All DAV-compliant resources MUST support the Overwrite header.
10.7. Timeout Request Header TimeOut = "Timeout" ":" 1#TimeType TimeType = ("Second-" DAVTimeOutVal | "Infinite") ; No LWS allowed within TimeType DAVTimeOutVal = 1*DIGIT Clients MAY include Timeout request headers in their LOCK requests. However, the server is not required to honor or even consider these requests. Clients MUST NOT submit a Timeout request header with any method other than a LOCK method. The "Second" TimeType specifies the number of seconds that will elapse between granting of the lock at the server, and the automatic removal of the lock. The timeout value for TimeType "Second" MUST NOT be greater than 2^32-1. See Section 6.6 for a description of lock timeout behavior. 11. Status Code Extensions to HTTP/1.1 The following status codes are added to those defined in HTTP/1.1 [RFC2616]. 11.1. 207 Multi-Status The 207 (Multi-Status) status code provides status for multiple independent operations (see Section 13 for more information). 11.2. 422 Unprocessable Entity The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415(Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions. 11.3. 423 Locked The 423 (Locked) status code means the source or destination resource of a method is locked. This response SHOULD contain an appropriate precondition or postcondition code, such as 'lock-token-submitted' or 'no-conflicting-lock'.
11.4. 424 Failed Dependency The 424 (Failed Dependency) status code means that the method could not be performed on the resource because the requested action depended on another action and that action failed. For example, if a command in a PROPPATCH method fails, then, at minimum, the rest of the commands will also fail with 424 (Failed Dependency). 11.5. 507 Insufficient Storage The 507 (Insufficient Storage) status code means the method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request. This condition is considered to be temporary. If the request that received this status code was the result of a user action, the request MUST NOT be repeated until it is requested by a separate user action. 12. Use of HTTP Status Codes These HTTP codes are not redefined, but their use is somewhat extended by WebDAV methods and requirements. In general, many HTTP status codes can be used in response to any request, not just in cases described in this document. Note also that WebDAV servers are known to use 300-level redirect responses (and early interoperability tests found clients unprepared to see those responses). A 300-level response MUST NOT be used when the server has created a new resource in response to the request. 12.1. 412 Precondition Failed Any request can contain a conditional header defined in HTTP (If- Match, If-Modified-Since, etc.) or the "If" or "Overwrite" conditional headers defined in this specification. If the server evaluates a conditional header, and if that condition fails to hold, then this error code MUST be returned. On the other hand, if the client did not include a conditional header in the request, then the server MUST NOT use this status code. 12.2. 414 Request-URI Too Long This status code is used in HTTP 1.1 only for Request-URIs, not URIs in other locations.
13. Multi-Status Response A Multi-Status response conveys information about multiple resources in situations where multiple status codes might be appropriate. The default Multi-Status response body is a text/xml or application/xml HTTP entity with a 'multistatus' root element. Further elements contain 200, 300, 400, and 500 series status codes generated during the method invocation. 100 series status codes SHOULD NOT be recorded in a 'response' XML element. Although '207' is used as the overall response status code, the recipient needs to consult the contents of the multistatus response body for further information about the success or failure of the method execution. The response MAY be used in success, partial success and also in failure situations. The 'multistatus' root element holds zero or more 'response' elements in any order, each with information about an individual resource. Each 'response' element MUST have an 'href' element to identify the resource. A Multi-Status response uses one out of two distinct formats for representing the status: 1. A 'status' element as child of the 'response' element indicates the status of the message execution for the identified resource as a whole (for instance, see Section 9.6.2). Some method definitions provide information about specific status codes clients should be prepared to see in a response. However, clients MUST be able to handle other status codes, using the generic rules defined in Section 10 of [RFC2616]. 2. For PROPFIND and PROPPATCH, the format has been extended using the 'propstat' element instead of 'status', providing information about individual properties of a resource. This format is specific to PROPFIND and PROPPATCH, and is described in detail in Sections 9.1 and 9.2. 13.1. Response Headers HTTP defines the Location header to indicate a preferred URL for the resource that was addressed in the Request-URI (e.g., in response to successful PUT requests or in redirect responses). However, use of this header creates ambiguity when there are URLs in the body of the response, as with Multi-Status. Thus, use of the Location header with the Multi-Status response is intentionally undefined.
13.2. Handling Redirected Child Resources Redirect responses (300-303, 305, and 307) defined in HTTP 1.1 normally take a Location header to indicate the new URI for the single resource redirected from the Request-URI. Multi-Status responses contain many resource addresses, but the original definition in [RFC2518] did not have any place for the server to provide the new URI for redirected resources. This specification does define a 'location' element for this information (see Section 14.9). Servers MUST use this new element with redirect responses in Multi-Status. Clients encountering redirected resources in Multi-Status MUST NOT rely on the 'location' element being present with a new URI. If the element is not present, the client MAY reissue the request to the individual redirected resource, because the response to that request can be redirected with a Location header containing the new URI. 13.3. Internal Status Codes Sections 9.2.1, 9.1.2, 9.6.1, 9.8.3, and 9.9.2 define various status codes used in Multi-Status responses. This specification does not define the meaning of other status codes that could appear in these responses. 14. XML Element Definitions In this section, the final line of each section gives the element type declaration using the format defined in [REC-XML]. The "Value" field, where present, specifies further restrictions on the allowable contents of the XML element using BNF (i.e., to further restrict the values of a PCDATA element). Note that all of the elements defined here may be extended according to the rules defined in Section 17. All elements defined here are in the "DAV:" namespace. 14.1. activelock XML Element Name: activelock Purpose: Describes a lock on a resource. <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?, locktoken?, lockroot)>
14.2. allprop XML Element Name: allprop Purpose: Specifies that all names and values of dead properties and the live properties defined by this document existing on the resource are to be returned. <!ELEMENT allprop EMPTY > 14.3. collection XML Element Name: collection Purpose: Identifies the associated resource as a collection. The DAV:resourcetype property of a collection resource MUST contain this element. It is normally empty but extensions may add sub- elements. <!ELEMENT collection EMPTY > 14.4. depth XML Element Name: depth Purpose: Used for representing depth values in XML content (e.g., in lock information). Value: "0" | "1" | "infinity" <!ELEMENT depth (#PCDATA) > 14.5. error XML Element Name: error Purpose: Error responses, particularly 403 Forbidden and 409 Conflict, sometimes need more information to indicate what went wrong. In these cases, servers MAY return an XML response body with a document element of 'error', containing child elements identifying particular condition codes. Description: Contains at least one XML element, and MUST NOT contain text or mixed content. Any element that is a child of the 'error' element is considered to be a precondition or postcondition code. Unrecognized elements MUST be ignored. <!ELEMENT error ANY >
14.6. exclusive XML Element Name: exclusive Purpose: Specifies an exclusive lock. <!ELEMENT exclusive EMPTY > 14.7. href XML Element Name: href Purpose: MUST contain a URI or a relative reference. Description: There may be limits on the value of 'href' depending on the context of its use. Refer to the specification text where 'href' is used to see what limitations apply in each case. Value: Simple-ref <!ELEMENT href (#PCDATA)> 14.8. include XML Element Name: include Purpose: Any child element represents the name of a property to be included in the PROPFIND response. All elements inside an 'include' XML element MUST define properties related to the resource, although possible property names are in no way limited to those property names defined in this document or other standards. This element MUST NOT contain text or mixed content. <!ELEMENT include ANY > 14.9. location XML Element Name: location Purpose: HTTP defines the "Location" header (see [RFC2616], Section 14.30) for use with some status codes (such as 201 and the 300 series codes). When these codes are used inside a 'multistatus' element, the 'location' element can be used to provide the accompanying Location header value.
Description: Contains a single href element with the same value that would be used in a Location header. <!ELEMENT location (href)> 14.10. lockentry XML Element Name: lockentry Purpose: Defines the types of locks that can be used with the resource. <!ELEMENT lockentry (lockscope, locktype) > 14.11. lockinfo XML Element Name: lockinfo Purpose: The 'lockinfo' XML element is used with a LOCK method to specify the type of lock the client wishes to have created. <!ELEMENT lockinfo (lockscope, locktype, owner?) > 14.12. lockroot XML Element Name: lockroot Purpose: Contains the root URL of the lock, which is the URL through which the resource was addressed in the LOCK request. Description: The href element contains the root of the lock. The server SHOULD include this in all DAV:lockdiscovery property values and the response to LOCK requests. <!ELEMENT lockroot (href) > 14.13. lockscope XML Element Name: lockscope Purpose: Specifies whether a lock is an exclusive lock, or a shared lock. <!ELEMENT lockscope (exclusive | shared) >
14.14. locktoken XML Element Name: locktoken Purpose: The lock token associated with a lock. Description: The href contains a single lock token URI, which refers to the lock. <!ELEMENT locktoken (href) > 14.15. locktype XML Element Name: locktype Purpose: Specifies the access type of a lock. At present, this specification only defines one lock type, the write lock. <!ELEMENT locktype (write) > 14.16. multistatus XML Element Name: multistatus Purpose: Contains multiple response messages. Description: The 'responsedescription' element at the top level is used to provide a general message describing the overarching nature of the response. If this value is available, an application may use it instead of presenting the individual response descriptions contained within the responses. <!ELEMENT multistatus (response*, responsedescription?) > 14.17. owner XML Element Name: owner Purpose: Holds client-supplied information about the creator of a lock. Description: Allows a client to provide information sufficient for either directly contacting a principal (such as a telephone number or Email URI), or for discovering the principal (such as the URL
of a homepage) who created a lock. The value provided MUST be treated as a dead property in terms of XML Information Item preservation. The server MUST NOT alter the value unless the owner value provided by the client is empty. For a certain amount of interoperability between different client implementations, if clients have URI-formatted contact information for the lock creator suitable for user display, then clients SHOULD put those URIs in 'href' child elements of the 'owner' element. Extensibility: MAY be extended with child elements, mixed content, text content or attributes. <!ELEMENT owner ANY > 14.18. prop XML Element Name: prop Purpose: Contains properties related to a resource. Description: A generic container for properties defined on resources. All elements inside a 'prop' XML element MUST define properties related to the resource, although possible property names are in no way limited to those property names defined in this document or other standards. This element MUST NOT contain text or mixed content. <!ELEMENT prop ANY > 14.19. propertyupdate XML Element Name: propertyupdate Purpose: Contains a request to alter the properties on a resource. Description: This XML element is a container for the information required to modify the properties on the resource. <!ELEMENT propertyupdate (remove | set)+ > 14.20. propfind XML Element Name: propfind
Purpose: Specifies the properties to be returned from a PROPFIND method. Four special elements are specified for use with 'propfind': 'prop', 'allprop', 'include', and 'propname'. If 'prop' is used inside 'propfind', it MUST NOT contain property values. <!ELEMENT propfind ( propname | (allprop, include?) | prop ) > 14.21. propname XML Element Name: propname Purpose: Specifies that only a list of property names on the resource is to be returned. <!ELEMENT propname EMPTY > 14.22. propstat XML Element Name: propstat Purpose: Groups together a prop and status element that is associated with a particular 'href' element. Description: The propstat XML element MUST contain one prop XML element and one status XML element. The contents of the prop XML element MUST only list the names of properties to which the result in the status element applies. The optional precondition/ postcondition element and 'responsedescription' text also apply to the properties named in 'prop'. <!ELEMENT propstat (prop, status, error?, responsedescription?) > 14.23. remove XML Element Name: remove Purpose: Lists the properties to be removed from a resource. Description: Remove instructs that the properties specified in prop should be removed. Specifying the removal of a property that does not exist is not an error. All the XML elements in a 'prop' XML element inside of a 'remove' XML element MUST be empty, as only the names of properties to be removed are required. <!ELEMENT remove (prop) >
14.24. response XML Element Name: response Purpose: Holds a single response describing the effect of a method on resource and/or its properties. Description: The 'href' element contains an HTTP URL pointing to a WebDAV resource when used in the 'response' container. A particular 'href' value MUST NOT appear more than once as the child of a 'response' XML element under a 'multistatus' XML element. This requirement is necessary in order to keep processing costs for a response to linear time. Essentially, this prevents having to search in order to group together all the responses by 'href'. There are, however, no requirements regarding ordering based on 'href' values. The optional precondition/postcondition element and 'responsedescription' text can provide additional information about this resource relative to the request or result. <!ELEMENT response (href, ((href*, status)|(propstat+)), error?, responsedescription? , location?) > 14.25. responsedescription XML Element Name: responsedescription Purpose: Contains information about a status response within a Multi-Status. Description: Provides information suitable to be presented to a user. <!ELEMENT responsedescription (#PCDATA) > 14.26. set XML Element Name: set Purpose: Lists the property values to be set for a resource. Description: The 'set' element MUST contain only a 'prop' element. The elements contained by the 'prop' element inside the 'set' element MUST specify the name and value of properties that are set on the resource identified by Request-URI. If a property already exists, then its value is replaced. Language tagging information appearing in the scope of the 'prop' element (in the "xml:lang"
attribute, if present) MUST be persistently stored along with the property, and MUST be subsequently retrievable using PROPFIND. <!ELEMENT set (prop) > 14.27. shared XML Element Name: shared Purpose: Specifies a shared lock. <!ELEMENT shared EMPTY > 14.28. status XML Element Name: status Purpose: Holds a single HTTP status-line. Value: status-line (defined in Section 6.1 of [RFC2616]) <!ELEMENT status (#PCDATA) > 14.29. timeout XML Element Name: timeout Purpose: The number of seconds remaining before a lock expires. Value: TimeType (defined in Section 10.7) <!ELEMENT timeout (#PCDATA) > 14.30. write XML Element Name: write Purpose: Specifies a write lock. <!ELEMENT write EMPTY >
15. DAV Properties For DAV properties, the name of the property is also the same as the name of the XML element that contains its value. In the section below, the final line of each section gives the element type declaration using the format defined in [REC-XML]. The "Value" field, where present, specifies further restrictions on the allowable contents of the XML element using BNF (i.e., to further restrict the values of a PCDATA element). A protected property is one that cannot be changed with a PROPPATCH request. There may be other requests that would result in a change to a protected property (as when a LOCK request affects the value of DAV:lockdiscovery). Note that a given property could be protected on one type of resource, but not protected on another type of resource. A computed property is one with a value defined in terms of a computation (based on the content and other properties of that resource, or even of some other resource). A computed property is always a protected property. COPY and MOVE behavior refers to local COPY and MOVE operations. For properties defined based on HTTP GET response headers (DAV:get*), the header value could include LWS as defined in [RFC2616], Section 4.2. Server implementors SHOULD strip LWS from these values before using as WebDAV property values. 15.1. creationdate Property Name: creationdate Purpose: Records the time and date the resource was created. Value: date-time (defined in [RFC3339], see the ABNF in Section 5.6.) Protected: MAY be protected. Some servers allow DAV:creationdate to be changed to reflect the time the document was created if that is more meaningful to the user (rather than the time it was uploaded). Thus, clients SHOULD NOT use this property in synchronization logic (use DAV:getetag instead). COPY/MOVE behavior: This property value SHOULD be kept during a MOVE operation, but is normally re-initialized when a resource is created with a COPY. It should not be set in a COPY.
Description: The DAV:creationdate property SHOULD be defined on all DAV compliant resources. If present, it contains a timestamp of the moment when the resource was created. Servers that are incapable of persistently recording the creation date SHOULD instead leave it undefined (i.e. report "Not Found"). <!ELEMENT creationdate (#PCDATA) > 15.2. displayname Property Name: displayname Purpose: Provides a name for the resource that is suitable for presentation to a user. Value: Any text. Protected: SHOULD NOT be protected. Note that servers implementing [RFC2518] might have made this a protected property as this is a new requirement. COPY/MOVE behavior: This property value SHOULD be preserved in COPY and MOVE operations. Description: Contains a description of the resource that is suitable for presentation to a user. This property is defined on the resource, and hence SHOULD have the same value independent of the Request-URI used to retrieve it (thus, computing this property based on the Request-URI is deprecated). While generic clients might display the property value to end users, client UI designers must understand that the method for identifying resources is still the URL. Changes to DAV:displayname do not issue moves or copies to the server, but simply change a piece of meta-data on the individual resource. Two resources can have the same DAV: displayname value even within the same collection. <!ELEMENT displayname (#PCDATA) > 15.3. getcontentlanguage Property Name: getcontentlanguage Purpose: Contains the Content-Language header value (from Section 14.12 of [RFC2616]) as it would be returned by a GET without accept headers. Value: language-tag (language-tag is defined in Section 3.10 of [RFC2616])
Protected: SHOULD NOT be protected, so that clients can reset the language. Note that servers implementing [RFC2518] might have made this a protected property as this is a new requirement. COPY/MOVE behavior: This property value SHOULD be preserved in COPY and MOVE operations. Description: The DAV:getcontentlanguage property MUST be defined on any DAV-compliant resource that returns the Content-Language header on a GET. <!ELEMENT getcontentlanguage (#PCDATA) > 15.4. getcontentlength Property Name: getcontentlength Purpose: Contains the Content-Length header returned by a GET without accept headers. Value: See Section 14.13 of [RFC2616]. Protected: This property is computed, therefore protected. Description: The DAV:getcontentlength property MUST be defined on any DAV-compliant resource that returns the Content-Length header in response to a GET. COPY/MOVE behavior: This property value is dependent on the size of the destination resource, not the value of the property on the source resource. <!ELEMENT getcontentlength (#PCDATA) > 15.5. getcontenttype Property Name: getcontenttype Purpose: Contains the Content-Type header value (from Section 14.17 of [RFC2616]) as it would be returned by a GET without accept headers. Value: media-type (defined in Section 3.7 of [RFC2616]) Protected: Potentially protected if the server prefers to assign content types on its own (see also discussion in Section 9.7.1).
COPY/MOVE behavior: This property value SHOULD be preserved in COPY and MOVE operations. Description: This property MUST be defined on any DAV-compliant resource that returns the Content-Type header in response to a GET. <!ELEMENT getcontenttype (#PCDATA) > 15.6. getetag Property Name: getetag Purpose: Contains the ETag header value (from Section 14.19 of [RFC2616]) as it would be returned by a GET without accept headers. Value: entity-tag (defined in Section 3.11 of [RFC2616]) Protected: MUST be protected because this value is created and controlled by the server. COPY/MOVE behavior: This property value is dependent on the final state of the destination resource, not the value of the property on the source resource. Also note the considerations in Section 8.8. Description: The getetag property MUST be defined on any DAV- compliant resource that returns the Etag header. Refer to Section 3.11 of RFC 2616 for a complete definition of the semantics of an ETag, and to Section 8.6 for a discussion of ETags in WebDAV. <!ELEMENT getetag (#PCDATA) > 15.7. getlastmodified Property Name: getlastmodified Purpose: Contains the Last-Modified header value (from Section 14.29 of [RFC2616]) as it would be returned by a GET method without accept headers. Value: rfc1123-date (defined in Section 3.3.1 of [RFC2616]) Protected: SHOULD be protected because some clients may rely on the value for appropriate caching behavior, or on the value of the Last-Modified header to which this property is linked.
COPY/MOVE behavior: This property value is dependent on the last modified date of the destination resource, not the value of the property on the source resource. Note that some server implementations use the file system date modified value for the DAV:getlastmodified value, and this can be preserved in a MOVE even when the HTTP Last-Modified value SHOULD change. Note that since [RFC2616] requires clients to use ETags where provided, a server implementing ETags can count on clients using a much better mechanism than modification dates for offline synchronization or cache control. Also note the considerations in Section 8.8. Description: The last-modified date on a resource SHOULD only reflect changes in the body (the GET responses) of the resource. A change in a property only SHOULD NOT cause the last-modified date to change, because clients MAY rely on the last-modified date to know when to overwrite the existing body. The DAV: getlastmodified property MUST be defined on any DAV-compliant resource that returns the Last-Modified header in response to a GET. <!ELEMENT getlastmodified (#PCDATA) > 15.8. lockdiscovery Property Name: lockdiscovery Purpose: Describes the active locks on a resource Protected: MUST be protected. Clients change the list of locks through LOCK and UNLOCK, not through PROPPATCH. COPY/MOVE behavior: The value of this property depends on the lock state of the destination, not on the locks of the source resource. Recall that locks are not moved in a MOVE operation. Description: Returns a listing of who has a lock, what type of lock he has, the timeout type and the time remaining on the timeout, and the associated lock token. Owner information MAY be omitted if it is considered sensitive. If there are no locks, but the server supports locks, the property will be present but contain zero 'activelock' elements. If there are one or more locks, an 'activelock' element appears for each lock on the resource. This property is NOT lockable with respect to write locks (Section 7). <!ELEMENT lockdiscovery (activelock)* >
15.8.1. Example - Retrieving DAV:lockdiscovery >>Request PROPFIND /container/ HTTP/1.1 Host: www.example.com Content-Length: xxxx Content-Type: application/xml; charset="utf-8" <?xml version="1.0" encoding="utf-8" ?> <D:propfind xmlns:D='DAV:'> <D:prop><D:lockdiscovery/></D:prop> </D:propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: application/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D='DAV:'> <D:response> <D:href>http://www.example.com/container/</D:href> <D:propstat> <D:prop> <D:lockdiscovery> <D:activelock> <D:locktype><D:write/></D:locktype> <D:lockscope><D:exclusive/></D:lockscope> <D:depth>0</D:depth> <D:owner>Jane Smith</D:owner> <D:timeout>Infinite</D:timeout> <D:locktoken> <D:href >urn:uuid:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76</D:href> </D:locktoken> <D:lockroot> <D:href>http://www.example.com/container/</D:href> </D:lockroot> </D:activelock> </D:lockdiscovery> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> </D:multistatus>
This resource has a single exclusive write lock on it, with an infinite timeout. 15.9. resourcetype Property Name: resourcetype Purpose: Specifies the nature of the resource. Protected: SHOULD be protected. Resource type is generally decided through the operation creating the resource (MKCOL vs PUT), not by PROPPATCH. COPY/MOVE behavior: Generally a COPY/MOVE of a resource results in the same type of resource at the destination. Description: MUST be defined on all DAV-compliant resources. Each child element identifies a specific type the resource belongs to, such as 'collection', which is the only resource type defined by this specification (see Section 14.3). If the element contains the 'collection' child element plus additional unrecognized elements, it should generally be treated as a collection. If the element contains no recognized child elements, it should be treated as a non-collection resource. The default value is empty. This element MUST NOT contain text or mixed content. Any custom child element is considered to be an identifier for a resource type. Example: (fictional example to show extensibility) <x:resourcetype xmlns:x="DAV:"> <x:collection/> <f:search-results xmlns:f="http://www.example.com/ns"/> </x:resourcetype> 15.10. supportedlock Property Name: supportedlock Purpose: To provide a listing of the lock capabilities supported by the resource. Protected: MUST be protected. Servers, not clients, determine what lock mechanisms are supported.
COPY/MOVE behavior: This property value is dependent on the kind of locks supported at the destination, not on the value of the property at the source resource. Servers attempting to COPY to a destination should not attempt to set this property at the destination. Description: Returns a listing of the combinations of scope and access types that may be specified in a lock request on the resource. Note that the actual contents are themselves controlled by access controls, so a server is not required to provide information the client is not authorized to see. This property is NOT lockable with respect to write locks (Section 7). <!ELEMENT supportedlock (lockentry)* > 15.10.1. Example - Retrieving DAV:supportedlock >>Request PROPFIND /container/ HTTP/1.1 Host: www.example.com Content-Length: xxxx Content-Type: application/xml; charset="utf-8" <?xml version="1.0" encoding="utf-8" ?> <D:propfind xmlns:D="DAV:"> <D:prop><D:supportedlock/></D:prop> </D:propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: application/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://www.example.com/container/</D:href> <D:propstat> <D:prop> <D:supportedlock> <D:lockentry> <D:lockscope><D:exclusive/></D:lockscope> <D:locktype><D:write/></D:locktype> </D:lockentry> <D:lockentry> <D:lockscope><D:shared/></D:lockscope>
<D:locktype><D:write/></D:locktype> </D:lockentry> </D:supportedlock> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> </D:multistatus> 16. Precondition/Postcondition XML Elements As introduced in Section 8.7, extra information on error conditions can be included in the body of many status responses. This section makes requirements on the use of the error body mechanism and introduces a number of precondition and postcondition codes. A "precondition" of a method describes the state of the server that must be true for that method to be performed. A "postcondition" of a method describes the state of the server that must be true after that method has been completed. Each precondition and postcondition has a unique XML element associated with it. In a 207 Multi-Status response, the XML element MUST appear inside an 'error' element in the appropriate 'propstat or 'response' element depending on whether the condition applies to one or more properties or to the resource as a whole. In all other error responses where this specification's 'error' body is used, the precondition/postcondition XML element MUST be returned as the child of a top-level 'error' element in the response body, unless otherwise negotiated by the request, along with an appropriate response status. The most common response status codes are 403 (Forbidden) if the request should not be repeated because it will always fail, and 409 (Conflict) if it is expected that the user might be able to resolve the conflict and resubmit the request. The 'error' element MAY contain child elements with specific error information and MAY be extended with any custom child elements. This mechanism does not take the place of using a correct numeric status code as defined here or in HTTP, because the client must always be able to take a reasonable course of action based only on the numeric code. However, it does remove the need to define new numeric codes. The new machine-readable codes used for this purpose are XML elements classified as preconditions and postconditions, so naturally, any group defining a new condition code can use their own namespace. As always, the "DAV:" namespace is reserved for use by IETF-chartered WebDAV working groups.
A server supporting this specification SHOULD use the XML error whenever a precondition or postcondition defined in this document is violated. For error conditions not specified in this document, the server MAY simply choose an appropriate numeric status and leave the response body blank. However, a server MAY instead use a custom condition code and other supporting text, because even when clients do not automatically recognize condition codes, they can be quite useful in interoperability testing and debugging. Example - Response with precondition code >>Response HTTP/1.1 423 Locked Content-Type: application/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:error xmlns:D="DAV:"> <D:lock-token-submitted> <D:href>/workspace/webdav/</D:href> </D:lock-token-submitted> </D:error> In this example, a client unaware of a depth-infinity lock on the parent collection "/workspace/webdav/" attempted to modify the collection member "/workspace/webdav/proposal.doc". Some other useful preconditions and postconditions have been defined in other specifications extending WebDAV, such as [RFC3744] (see particularly Section 7.1.1), [RFC3253], and [RFC3648]. All these elements are in the "DAV:" namespace. If not specified otherwise, the content for each condition's XML element is defined to be empty. Name: lock-token-matches-request-uri Use with: 409 Conflict Purpose: (precondition) -- A request may include a Lock-Token header to identify a lock for the UNLOCK method. However, if the Request-URI does not fall within the scope of the lock identified by the token, the server SHOULD use this error. The lock may have a scope that does not include the Request-URI, or the lock could have disappeared, or the token may be invalid.
Name: lock-token-submitted (precondition) Use with: 423 Locked Purpose: The request could not succeed because a lock token should have been submitted. This element, if present, MUST contain at least one URL of a locked resource that prevented the request. In cases of MOVE, COPY, and DELETE where collection locks are involved, it can be difficult for the client to find out which locked resource made the request fail -- but the server is only responsible for returning one such locked resource. The server MAY return every locked resource that prevented the request from succeeding if it knows them all. <!ELEMENT lock-token-submitted (href+) > Name: no-conflicting-lock (precondition) Use with: Typically 423 Locked Purpose: A LOCK request failed due the presence of an already existing conflicting lock. Note that a lock can be in conflict although the resource to which the request was directed is only indirectly locked. In this case, the precondition code can be used to inform the client about the resource that is the root of the conflicting lock, avoiding a separate lookup of the "lockdiscovery" property. <!ELEMENT no-conflicting-lock (href)* > Name: no-external-entities Use with: 403 Forbidden Purpose: (precondition) -- If the server rejects a client request because the request body contains an external entity, the server SHOULD use this error. Name: preserved-live-properties Use with: 409 Conflict Purpose: (postcondition) -- The server received an otherwise-valid MOVE or COPY request, but cannot maintain the live properties with the same behavior at the destination. It may be that the server
only supports some live properties in some parts of the repository, or simply has an internal error. Name: propfind-finite-depth Use with: 403 Forbidden Purpose: (precondition) -- This server does not allow infinite-depth PROPFIND requests on collections. Name: cannot-modify-protected-property Use with: 403 Forbidden Purpose: (precondition) -- The client attempted to set a protected property in a PROPPATCH (such as DAV:getetag). See also [RFC3253], Section 3.12. 17. XML Extensibility in DAV The XML namespace extension ([REC-XML-NAMES]) is used in this specification in order to allow for new XML elements to be added without fear of colliding with other element names. Although WebDAV request and response bodies can be extended by arbitrary XML elements, which can be ignored by the message recipient, an XML element in the "DAV:" namespace SHOULD NOT be used in the request or response body unless that XML element is explicitly defined in an IETF RFC reviewed by a WebDAV working group. For WebDAV to be both extensible and backwards-compatible, both clients and servers need to know how to behave when unexpected or unrecognized command extensions are received. For XML processing, this means that clients and servers MUST process received XML documents as if unexpected elements and attributes (and all children of unrecognized elements) were not there. An unexpected element or attribute includes one that may be used in another context but is not expected here. Ignoring such items for purposes of processing can of course be consistent with logging all information or presenting for debugging. This restriction also applies to the processing, by clients, of DAV property values where unexpected XML elements SHOULD be ignored unless the property's schema declares otherwise. This restriction does not apply to setting dead DAV properties on the server where the server MUST record all XML elements.
Additionally, this restriction does not apply to the use of XML where XML happens to be the content type of the entity body, for example, when used as the body of a PUT. Processing instructions in XML SHOULD be ignored by recipients. Thus, specifications extending WebDAV SHOULD NOT use processing instructions to define normative behavior. XML DTD fragments are included for all the XML elements defined in this specification. However, correct XML will not be valid according to any DTD due to namespace usage and extension rules. In particular: o Elements (from this specification) are in the "DAV:" namespace, o Element ordering is irrelevant unless otherwise stated, o Extension attributes MAY be added, o For element type definitions of "ANY", the normative text definition for that element defines what can be in it and what that means. o For element type definitions of "#PCDATA", extension elements MUST NOT be added. o For other element type definitions, including "EMPTY", extension elements MAY be added. Note that this means that elements containing elements cannot be extended to contain text, and vice versa. With DTD validation relaxed by the rules above, the constraints described by the DTD fragments are normative (see for example Appendix A). A recipient of a WebDAV message with an XML body MUST NOT validate the XML document according to any hard-coded or dynamically-declared DTD. Note that this section describes backwards-compatible extensibility rules. There might also be times when an extension is designed not to be backwards-compatible, for example, defining an extension that reuses an XML element defined in this document but omitting one of the child elements required by the DTDs in this specification.