WebDAV Working Group                                       L. Dusseault
Internet Draft                                                   Xythos
Document: <draft-ietf-webdav-status-00.txt>              January 2000
Category: Informational


                  WebDAV -- Advanced Status Reporting


Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026 [1].

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups. Note that
   other groups may also distribute working documents as Internet-
   Drafts. Internet-Drafts are draft documents valid for a maximum of
   six months and may be updated, replaced, or obsoleted by other
   documents at any time. It is inappropriate to use Internet- Drafts
   as reference material or to cite them other than as "work in
   progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt
   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.


. Abstract

   HTTP 1.1 [2] defines 20 status codes: 100-101, 200-206, 300-305,
   400-415, and 500-505.  The WebDAV RFC [3] adds six more: 102, 207,
   422, 423, 424 and 507.  However, WebDAV implementers have found this
   to be insufficient.  The space of status codes available is limited,
   but even if it were not, additional information would often be very
   helpful.  WebDAV clients frequently need to be able to present
   distinct options and helpful information to users, and sometimes
   clients might even be able to deal with errors automatically.

   Currently, HTTP and WebDAV servers frequently add HTML bodies to
   error responses, so that a simple web browser can present the HTML
   for the user to read.  However, this approach does not allow custom
   client UI or automated client operation, and may handle
   internationalization poorly.

   This Internet-Draft proposes a new header to allow sophisticated or
   automated WebDAV clients to request advanced status reporting rather
   than the single-code approach available today.  This draft also
   proposes a simple XML format for the body of the error response.
   Finally, this draft proposes a number of "detail codes" expressed as
   XML elements, suitable for automatic processing of error conditions.
   These detail codes augment the existing response codes.


Dusseault                  Expires Aug 2000                          1
                 Advanced Status Reporting for WebDAV         Jan 2001


   This draft does not specify how additional codes are to be defined.


. Conventions used in this document

   In examples, "C:" and "S:" indicate lines sent by the client and
   server respectively.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in
   this document are to be interpreted as described in RFC-2119 [4].


. Client Request

   There are several ways clients can handle the typical HTTP error
   response, with or without HTML body.  Some clients (i.e. web
   browsers) simply present the HTML or text response to the user.
   Other clients present a UI (a dialog box, an error message) based on
   the status code, ignoring the HTML response if the server sent it.
   Finally, there are automated clients that may respond to the error
   with further automated action if enough information is present.
   This specification addresses the latter two types of clients, and
   thus has to solve the problem of how these clients identify
   themselves to the server.

3.1  Accept-Error Header

   Accept-Error = "Accept-Error" ":" "type=" media-type

   The "media-type" field is a type/subtype pair as defined in HTTP 1.1
   for the "Accept" header.

   Example:  "Accept-Error: type=text/xml"

   The Accept-Error header MAY be sent on any client request to a
   WebDAV server.  A server MAY choose to ignore the header.  The
   header specifies what format the client wishes to receive with the
   extra status information.  If the header is not present or the
   server does not support the format requested by the client, the
   server MAY send some default response, e.g. many servers already
   return an HTML page with displayable text.

   The client MAY choose not to include this header in every request,
   since most requests are likely to succeed.  The client MAY choose to
   resend failed requests, adding at this point the Accept-Error
   header.  The server MAY cache the client's support for this feature,
   although it SHOULD be able to update the cache if the client sends a
   new Accept-Error header with a different media type.

   This specification only describes two formats that can be requested.
   A request for "text/xml" MUST be considered a request for a body
   with the DAV:response-detail top-level element and sub-elements

Dusseault                  Expires Aug 2000                          2
                 Advanced Status Reporting for WebDAV         Jan 2001


   defined in this specification.  A request for "text/html" MAY be
   considered a request for a free-form HTML page describing the error,
   intended for display to the user (such as some HTTP servers already
   create).

3.2  Use of Accept-Language Header

   It is recommended that the client include the Accept-Language header
   defined for HTTP 1.1.  The server MAY respond with human-readable
   text, and MAY be able to localize the text.


. Response Body

   The key pieces of information to be returned to the client are at
   least one tuple, containing an advanced status code (XML element)
   and displayable text string.  The server MAY provide status codes
   and/or text strings for additional errors pinpointed to specific
   resources.  This section describes how this information is formatted
   into a text/xml body to be returned in the response.

   If the client request has the "Accept-Error: text/xml" header, then
   the server MAY respond with an appropriate HTTP response code, and
   add text/xml body with the elements defined in this specification.
   The server MAY return a regular error with no body or with a
   text/html body if it chooses to ignore the Accept-Error header.

   The server MUST NOT add an error body if the response code does not
   allow a body or already has a body defined.  HTTP 1.1 forbids
   response bodies on 1xx, 204, 205 and 304 responses.  The 200
   response already has a body defined, and 307 response is supposed to
   contain "hypertext".  WebDAV defines a body for 207 (however this
   specification allows extension of the 207 "multi-status" XML body to
   contain status codes defined in this specification [ref later
   section]).

   HTTP 1.1 encourages response bodies on some errors, e.g. for 409
   Conflict it states "The response body SHOULD include enough
   information for the user to recognize the source of the conflict".
   This specification is intended to go further in defining the
   formatting required for automated client software to be able to
   recognize the source of the conflict.

   This specification defines a response body for the response codes
   400, 401, 405, 409, 412, 415, 423 and 500.

   The server response MUST have an appropriate HTTP response code,
   even if an error body is returned.

   The text/xml body of the status response MUST have the DAV:response-
   detail top-level element, though it need not be the first or only
   top-level element in the XML document.  The DAV:response-detail
   element MUST contain one or more DAV:status-detail elements, which

Dusseault                  Expires Aug 2000                          3
                 Advanced Status Reporting for WebDAV         Jan 2001


   MUST contain one DAV:detail-code element.  Each DAV:detail-code
   element MUST contain a detail code.  This is the minimum useful
   response body.

   The DAV:response-detail element MAY also contain any number of
   DAV:response elements (defined in the WebDAV RFC).  These serve to
   pinpoint errors to particular resources when more than one resource
   is involved, for example when a depth header is present or when a
   source and destination resource are specified in the request.  The
   DAV:response element in this context can contain the DAV:href and
   DAV:status elements as it normally does (defined by the WebDAV RFC).
   It can also contain two new elements defined here: DAV:detail-code
   and DAV:user-text

   The DAV:status-detail element MAY contain one or more DAV:user-text
   elements with language code specified.

4.1  Using existing status codes

   It is expected and recommended that servers continue to use existing
   status codes in the body, as well as the first line of the response.
   For example, when a MOVE or COPY cannot be executed because the user
   does not have sufficient permissions on the destination, a "403
   Forbidden" response is quite informative -- as long as the
   client/user knows which is forbidden, the source or the destination.
   Thus, the DAV:status element is allowed in the DAV:status-detail
   element defined here.

4.2  Example request/response

   This example has two DAV:response elements to show the status on
   both the source and destination resources involved in a MOVE.  For
   the overall status information in the DAV:status-detail element, the
   server arbitrarily chose to present the 403 Forbidden response.  It
   could equally well have chosen the DAV:destination-resource-exists
   status code.

   C: MOVE http://www.host.com/foo.html HTTP/1.1
      Host: www.host.com
      Destination: http://www.host.com/bar.html
      Overwrite: F
      Accept-Language: En

   S: HTTP/1.1 403 Forbidden
      Content-Type: text/xml
      Content-Length: xxx

      <?xml version="1.0"?>
      <D:response-detail xmlns:D="DAV:">

        <D:status-detail>
          <D:status>HTTP/1.1 403 Forbidden</D:status>
          <D:user-text xml:lang="en">Error: cannot execute move

Dusseault                  Expires Aug 2000                          4
                 Advanced Status Reporting for WebDAV         Jan 2001


            </D:user-text>
        </D:status-detail>

        <D:response>
          <D:href>http://www.host.com/foo.html</D:href>
          <D:status>HTTP/1.1 403 Forbidden</D:status>
          <D:user-text xml:lang="en">Error: cannot read source
             resource.</D:user-text>
        </D:response>

        <D:response>
          <D:href>http://www.host.com/bar.html</D:href>
          <D:status>HTTP/1.1 412 Precondition Failed</D:status>
          <D:detail-code><D:destination-resource-exists/>
            </D:detail-code>
          <D:user-text xml:lang="en">Error: Destination resource
            already exists</D:user-text>
        </D:response>

      </D:response-detail>


. Extending 207 Multistatus body

   WebDAV already defines a text/xml body for the 207 Multistatus
   response, containing one XML DAV:response element for each resource
   being reported on.  The DAV:propstat element indicates that the
   status being given is for a property of the resource.  The existing
   schema is extended by allowing both the existing DAV:response and
   the existing DAV:propstat elements to contain the new DAV:status-
   detail.  If the error information is inside a DAV:propstat element
   it should be clear the error refers to the property; otherwise it
   refers to the resource.  The DAV:status-detail element can contain
   DAV:detail-code and/or DAV:user-text (DAV:status must already be in
   the DAV:propstat element).

   The server MAY choose to always augment a 207 Multistatus body with
   this extra information.  The server MAY choose to add this
   information only if the client indicates support for the feature.
   The server MUST return all elements already required by the WebDAV
   RFC.

5.1 Example Multistatus Body with Detail Codes

   This is an example of a 207 Multistatus response body with the
   simple addition of the DAV:status-detail element within the
   DAV:propstat element.  The user requested to PROPPATCH a single
   property on a single resource.

   <?xml version="1.0"?>
   <D:multistatus xmlns:D="DAV:"
       xmlns:Z="http://www.w3.com/standards/z39.50">
     <D:response>

Dusseault                  Expires Aug 2000                          5
                 Advanced Status Reporting for WebDAV         Jan 2001


       <D:href>http://www.foo.bar/top/container/</D:href>
       <D:propstat>
         <D:prop><Z:Copyright-Owner/></D:prop>
         <D:status>HTTP/1.1 409 Conflict</D:status>
         <D:status-detail>
           <D:detail-code><D: property-protected></D:detail-code>
           <D:user-text xml:lang="En">Error: The "Copyright-Owner
             property is protected and may not be set or changed.
           </D:user-text>
         </D:status-detail>
       </D:propstat>
     </D:response>
   </D:multistatus>


. Detail Codes

   All codes defined in this section are XML elements in the DAV:
   namespace.  Since the server must usually present a response code as
   well (in the DAV:status element within DAV:propstat, or in the
   response header line), this specification suggests an appropriate
   code to use.

6.1  ancestor-does-not-exist

   Suggested response code: 409 Conflict

   Used when a resource is being created (method might be MOVE, COPY,
   PUT or MKCOL) when not all ancestors of the destination resource
   exist.

6.2  authentication-insufficient

   Suggested response code: 401 Unauthorized

   Used when the client is currently authenticated, but would need
   different permissions in order to succeed in the request.  Do not
   use this status code when the request would be forbidden no matter
   how the user is able to authenticate (use 403 Forbidden instead).

6.3  authentication-required

   Suggested response code: 401 Unauthorized

   Used when the client is NOT currently authenticated and therefore
   the server forbids the request.  Do not use this status code when
   the request would be forbidden no matter how the user is able to
   authenticate, or when the user is already authenticated (use 403
   Forbidden instead).

   This is analogous to a "authentication timed out" or "logout" status
   message from the server, however it does not require the server to

Dusseault                  Expires Aug 2000                          6
                 Advanced Status Reporting for WebDAV         Jan 2001


   maintain a list of clients that were authenticated at one point in
   order to differentiate from clients that never have authenticated.

6.4  child-is-locked

   Suggested response code: 423 Locked

   Used when a request cannot be carried out because some child
   resource of the source or destination resource was locked.  For
   example, a MOVE request with a depth header of "infinity" may not be
   performed if some child resource is already locked and a lock token
   was not provided.

6.5  body-encoding-not-supported

   Suggested response code: 400 Bad Request

   Used when the request body is encoded in a format that the server
   does not support.

6.6  body-missing

   Suggested response code: 400 Bad Request

   Used when a body is required for the request method, but none was
   provided in the request.

6.7  body-not-supported-on-method

   Suggested response code: 415 Unsupported Media Type

   Used when a body is NOT accepted for the request method used,
   however the client sent one anyway.  The WebDAV RFC suggests the
   "415 Unsupported Media Type" response when the client sends a body
   with a MKCOL request.  This new code differentiates the MKCOL case
   from the case where the server doesn't support the media type under
   any circumstances.

6.8  depth-not-supported

   Suggested response code: 500 Internal Server Error

   Used when a depth of "1" or "infinity" was requested but is not
   allowed on this kind of request.  E.g. some servers may choose not
   to support depth-infinity PROPFIND requests.  Most servers do not
   support depth 1 or infinity MKCOL requests.

6.9  destination-resource-exists

   Suggested response code: 412 Precondition Failed


Dusseault                  Expires Aug 2000                          7
                 Advanced Status Reporting for WebDAV         Jan 2001


   Used when a client did not provide an "Overwrite:True" header when
   doing a MOVE or COPY; when the destination already exists, the
   request must be failed.

6.10 header-missing

   Suggested response code: 400 Bad Request

   Used when a required header is missing, such as the content-length
   or host header.  This element contains the name of the missing
   header.  E.g.

   <D:missing-header>Host:</D:missing-header>

6.11 header-syntax-error

   Suggested response code:  400 Bad Request

   Used when a header cannot be parsed correctly.  E.g. content-length
   containing a string rather than an integer.  This element contains
   the name of the problematic header (see header-missing).

6.12 header-value-error

   Suggested response code:  400 Bad Request

   Used when a header is parsable but the value is out-of-bounds or
   incorrect.  E.g. content-length value which exceeds the length of
   the body received, or depth header value of '1' or 'infinity' when
   the resource is not a collection.  This element contains the name of
   the problematic header (see header-missing).

6.13 precondition-failed

   Suggested response code: 412 Precondition Failed

   Used when a precondition failed to specify which precondition
   failed.  The header and precondition are included inside the
   element.  E.g:

   <D:precondition-failed>If-Modified-Since: Sat, 29 Oct 1994 19:43:31
   GMT</D:precondition-failed>

6.14 property-protected

   Suggested response code: 409 Conflict

   Used when a property is protected by the server and may never be
   changed by a WebDAV request regardless of permissions.

6.15 resource-not-locked

   Suggested response code: 405 Method Not Allowed

Dusseault                  Expires Aug 2000                          8
                 Advanced Status Reporting for WebDAV         Jan 2001



   Used when an UNLOCK cannot be performed because the resource is not
   locked.

6.16 resource-unlockable

   Suggested response code: 405 Method Not Allowed

   Used when a LOCK cannot be granted because the resource cannot be
   locked (this may occur when the resource is not an ordinary
   resource, but something still URL-addressable servlet, the root
   directory, or a script).  If a LOCK is requested on a resource but
   it is a child of the resource that cannot be locked, the server must
   specify which child in a DAV:response element.

6.17 url-contains-invalid-characters

   Suggested response code: 400 Bad Request

   Used when the target URL has characters not supported on the server,
   e.g. on PUT or MKCOL, so the resource cannot be created.  The
   element SHOULD contain a list of invalid characters, e.g.

   <D:url-contains-invalid-characters>#?,</D:url-contains-invalid-
   characters>

6.18 xml-not-well-formed

   Suggested response code: 400 Bad Request

   Used only when the XML body of the request is not well-formed, as
   defined for XML 1.0 [5] in section 2.l.

6.19 xml-syntax-error

   Suggested response code: 400 Bad Request

   Used when the XML body of the request is well-formed but has some
   other error.  E.g. if a PROPFIND request has both DAV:allprop and
   DAV:propname in the body.


. XML Element Definitions

   DAV:status and DAV:href are used in this specification, and are
   unchanged in definition from RFC2518.

   All elements defined in this draft are in the "DAV:" namespace.

7.1  response-detail XML Element

   Used as a top-level XML Element for most status responses with
   bodies, except 207 Multistatus.  This is the container element for

Dusseault                  Expires Aug 2000                          9
                 Advanced Status Reporting for WebDAV         Jan 2001


   the detailed status information produced by the server, including
   overall status and status on specific resources.  It MUST contain a
   status-detail element and zero or more response elements.

   <!ELEMENT response-detail (status-detail, response*) >

7.2  status-detail XML Element

   Used to contain detailed status information for a resource, a
   property, or an entire response.  It MUST contain either status or
   detail-code.

   <!ELEMENT status-detail (status?, detail-code?, user-text?) >

7.3  detail-code XML Element

   Used to contain one of the detail code elements defined in this
   draft (section 6) or elsewhere.

   <!ELEMENT detail-code ANY>

7.4  user-text XML Element

   Used for text displayable to the user.  Takes the XML "lang"
   attribute defined in the W3C XML Recommendation.

   <!ELEMENT user-text (#PCDATA)>

7.5  response XML Element Extended

   The WebDAV RFC defines this element for use in 207 Multistatus
   bodies.  This specification extends the usage and children of the
   response element for a new context.

   <!ELEMENT response
     ( href,
       ((href*, status) | propstat+ | (detail-code, user-text),
       responsedescription?
     )>

7.6  propstat XML Element Extended

   The WebDAV RFC defines this element for use in 207 Multistatus
   bodies.  This specification extends the usage and children of the
   propstat element in the same context.

   <!ELEMENT propstat (prop, status, responsedescription?, detail-code?
   user-text?>

. Security Considerations

   This draft does not substantially alter the security considerations
   outlined in WebDAV (RFC 2518).

Dusseault                  Expires Aug 2000                         10
                 Advanced Status Reporting for WebDAV         Jan 2001



   Returning error information can only make security worse if the
   server chooses to return secure information in the error response.
   Implementers should be wary of returning sensitive information such
   as the names of hidden resources.


. References


   1  Bradner, S., "The Internet Standards Process -- Revision 3", BCP
      9, RFC 2026, October 1996.

   2  Fielding, R., J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee,
      ôHypertext Transfer Protocol û HTTP/1.1ö, RFC 2616, January 1997.

   3  Goland, Y., E. Whitehead, A. Faizi, S. Carter, D. Jensen, "HTTP
      Extensions for Distributed Authoring -- WebDAV", RFC 2518,
      February 1999.

   4  Bradner, S., "Key words for use in RFCs to Indicate Requirement
      Levels", BCP 14, RFC 2119, March 1997

   5  Bray, T., J. Paoli, C. M. Sperberg-McQueen, E. Maler, "Extensible
      Markup Language (XML) 1.0" W3C Recommendation,
      http://www.w3.org/TR/2000/REC-xml-20001006






.  Acknowledgments

   Thanks to Sean Lyndersay, John Stracke, and Roy Fielding for
   substantial suggestions.


. Author's Addresses

   Lisa Dusseault
   Xythos Software Inc
   1582 Gordon Street
   Redwood City, CA 94061
   Email: lisa@Xythos.com


Dusseault                  Expires Aug 2000                         11
                 Advanced Status Reporting for WebDAV         Jan 2001



Full Copyright Statement

   "Copyright (C) The Internet Society (date). All Rights Reserved.
   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implmentation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph
   are included on all such copies and derivative works. However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into





Dusseault                  Expires Aug 2000                         12