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:

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.

lock-token-matches-request-uri

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.

lock-token-submitted

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+) >

no-conflicting-lock

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)* >

no-external-entities

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.

preserved-live-properties

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.

propfind-finite-depth

Name: propfind-finite-depth

Use with: 403 Forbidden

Purpose: (precondition) -- This server does not allow infinite-depth PROPFIND requests on collections.

cannot-modify-protected-property

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.