Subject: Issue 177 (status descriptions)

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2006 21:40:14 +0100

While reviewing issue 177 
(<http://ietf.cse.ucsc.edu:8080/bugzilla/show_bug.cgi?id=177>), I came 
to the conclusion that the currently conflates the different usages of 
status codes inside multistatus. Also, the description of multistatus 
(Section 13) currently contains incorrect information which is new 
compared to RFC2518.

Below are proposed changes trying to address these problems (see also 
<http://greenbytes.de/tech/webdav/draft-reschke-webdav-rfc2518bis-latest.html#rfc.issue.bz177>):

Section 9.1.1., para. 3:
OLD:

  9.1.2.  Status codes for use with 207 (Multi-Status)

     The following are examples of response codes one would expect to be
     used in a 207 (Multi-Status) response for this method.  Note,
     however, that unless explicitly prohibited any 2/3/4/5xx series
     response code may be used in a 207 (Multi-Status) response.

NEW:

  9.1.2.  Status Codes for use in 'propstat' Element

     In PROPFIND responses, information about individual properties is
     returned inside 'propstat' elements (see Section 14.22), each
     containing an individual 'status' element containing information
     about the properties appearing in it.  The list below summarizes the
     most common status codes used inside 'propstat', however clients
     should be prepared to handle other 2/3/4/5xx series status codes as
     well.

(clarify that this is about status codes in *propstat*).

Section 9.2., para. 6:
OLD:

  9.2.1.  Status Codes for use in 207 (Multi-Status)

     The following are examples of response codes one would expect to be
     used in a 207 (Multi-Status) response for this method.  Note,
     however, that unless explicitly prohibited any 2/3/4/5xx series
     response code may be used in a 207 (Multi-Status) response.

NEW:

  9.2.1.  Status Codes for use in 'propstat' Element

     In PROPPATCH responses, information about individual properties is
     returned inside 'propstat' elements (see Section 14.22), each
     containing an individual 'status' element containing information
     about the properties appearing in it.  The list below summarizes the
     most common status codes used inside 'propstat', however clients
     should be prepared to handle other 2/3/4/5xx series status codes as
     well.

(clarify that this is about status codes in *propstat*).

Section 13., para. 1:
OLD:

     A Multi-Status response contains one 'response' element for each
     resource in the scope of the request (in no required order) or MAY be
     empty if no resources match the request.  The default 207 (Multi-
     Status) response body is a text/xml or application/xml HTTP entity
     that contains a single XML element called 'multistatus', which
     contains a set of XML elements called response which 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.  The 207 status code itself MUST NOT be
     considered a success response, it is only completely successful if
     all 'response' elements inside contain success status codes.

     The body of a 207 Multi-Status response MUST contain a URL associated
     with each specific status code, so that the client can tell whether
     the error occurred with the source resource, destination resource or
     some other resource in the scope of the request.

(note that the first sentence is plainly incorrect)

NEW:

     The default 207 (Multi-Status) response body is a text/xml or
     application/xml HTTP entity that contains a single XML element called
     'multistatus', which contains a set of XML elements called response
     which 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.

     Note that the usage of status code 207 indicates that the recipient
     needs to consult the contents of the multistatus response body for
     further information about the result of the method execution, thus it
     can occur in success, partial success and also in failure situations.

     Each 'response' element inside the body holds information about one
     individual resource, identified by the 'href' element, and 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 excecution 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.2 and 9.2.1.

(rewrite removes incorrect stuff and (hopefully) clarifies the distinct 
use cases of status codes in multistatus responses).

Section 14., para. 0:
OLD:

     Section 9.2.1, Section 9.1.2, Section 9.6.1, Section 9.8.3 and
     Section 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.

NEW:

(deleted)