]> Carnegie Mellon University

5000 Forbes Avenue Pittsburgh PA 15213 USA +1 412 268 1982 murch@andrew.cmu.edu

Applications Independent Submission I-D http prefer webdav caldav This specification defines how the HTTP Prefer header field can be used by a WebDAV client to request that certain behaviors be employed by a server while constructing a response to a request. Please send comments to the Web Distributed Authoring and Versioning (WebDAV) mailing list at <mailto:w3c-dist-auth@w3.org>, which may be joined by sending a message with subject "subscribe" to <mailto:w3c-dist-auth-request@w3.org>. This mailing list is archived at <http://lists.w3.org/Archives/Public/w3c-dist-auth/>. Should the list of updated RFCs (other than RFC 7240) in the title page header only contain those whose method responses have been altered by this document? Or should all potentially effected methods/protocols be listed? Should we add any text regarding caching responses in ? Should we update the HTTP Status Code Registry to add a reference to for 412 (Precondition Failed)?

defines the HTTP Prefer request header field and the "return=minimal" preference which indicates that a client wishes for the server to return a minimal response to a successful request, but states that what constitutes an appropriate minimal response is left solely to the discretion of the server. of this specification defines precisely what is expected of a server when constructing minimal responses to successful WebDAV requests. also defines the "return=representation" preference which indicates that a client wishes for the server to include an entity representing the current state of the resource in the response to a successful request. of this specification makes recommendations on when this preference should be used by clients and extends its applicability to 412 (Precondition Failed) responses. Finally, of this specification defines the "depth-noroot" preference that can be used with WebDAV methods that support the "Depth" header field.

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 . This document references XML element types in the "DAV:", "urn:ietf:params:xml:ns:caldav", and "urn:ietf:params:xml:ns:carddav" namespaces outside of the context of an XML fragment. When doing so, the strings "DAV:", "CALDAV:", and "CARDDAV:" will be prepended to the XML element types respectively.

Some payload bodies in responses to WebDAV requests, such as 207 (Multi-Status) responses, can be quite verbose or even unnecessary at times. This specification defines how the Prefer request header field, in conjunction with its "return=minimal" preference, can be used by clients to reduce the verbosity of such responses by requesting that the server omit those portions of the response that can be inferred by their absence.

When a PROPFIND request, or a REPORT request whose report type results in a 207 (Multi-Status) response, contains a Prefer header field with a preference of "return=minimal", the server SHOULD omit all DAV:propstat XML elements containing a DAV:status XML element of value 404 (Not Found) from the 207 (Multi-Status) response. If the omission of such a DAV:propstat element would result in a DAV:response XML element containing zero DAV:propstat elements, the server MUST substitute one of the following in its place: a DAV:propstat element consisting of an empty DAV:prop element and a DAV:status element of value 200 (OK) a DAV:status element of value 200 (OK) The following report types are candidates that could benefit from use of the "return=minimal" preference. NOTE: This list is not intended to be normative or exhaustive. DAV:expand-property DAV:acl-principal-prop-set DAV:principal-property-search DAV:sync-collection CALDAV:calendar-query CALDAV:calendar-multiget CARDDAV:addressbook-query CARDDAV:addressbook-multiget See and for examples.

When a PROPPATCH request contains a Prefer header field with a preference of "return=minimal", and all instructions are processed successfully, the server SHOULD return one of the following responses rather than a 207 (Multi-Status) response: 204 (No Content) 200 (OK) (preferably with a zero-length message body) See for examples.

Both the MKCALENDAR and Extended MKCOL specifications indicate that a server MAY return a message body in response to a successful request. This specification explicitly defines the intended behavior in the presence of the Prefer header field. When a MKCALENDAR or an Extended MKCOL request contains a Prefer header field with a preference of "return=minimal", and the collection is created with all requested properties being set successfully, the server SHOULD return a 201 (Created) response with an empty (zero-length) message body. Note that the rationale for requiring that a minimal success response have an empty body is twofold: Section 5.3.1 states: "If a response body for a successful request is included, it MUST be a CALDAV:mkcalendar-response XML element." Section 3 states: "When an empty response body is returned with a success request status code, the client can assume that all properties were set." See for examples.

describes the "return=representation" preference as being intended to provide a means of optimizing communication between the client and server by eliminating the need for a subsequent GET request to retrieve the current representation of the resource following a modification. This preference is equally applicable to situations where the server itself modifies a resource, and where a resource has been modified by another client.

The state-changing methods PUT, COPY/MOVE, PATCH, and POST can be used to create or update a resource. In some instances, such as with CalDAV Scheduling, the created or updated resource representation may differ from the representation sent in the body of the request or referenced by the effective request URI. In cases where the client, upon receiving a 2xx (Successful) response to its state-changing request, would normally issue a subsequent GET request to retrieve the current representation of the resource, the client can instead include a Prefer header field with the "return=representation" preference in the state-changing request. When a state-changing request contains a Prefer header field with a preference of "return=representation", and the resource is created or updated successfully, the server SHOULD include an entity representating the current state resource in the resulting 201 (Created) or 200 (OK) response. In addition to coalescing the create/update and retrieve operations into a single round-trip, by returning the current representation of the resource in the response the client will know that any changes to the resource were produced by the server rather than a concurrent client, thus providing a level of atomicity to the operation. See for examples.

Frequently, clients using a state-changing method such as those listed above will make them conditional by including either an If-Match or If-None-Match header field in the request. This is done to prevent the client from accidentially overwriting a resource whose current state has been modified by another client acting in parallel. In cases where the client, upon receiving a 412 (Precondition Failed) response to its conditional state-changing request, would normally issue a subsequent GET request to retrieve the current representation of the resource, the client can instead include a Prefer header field with the "return=representation" preference in the conditional state-changing request. When a conditional state-changing request contains a Prefer header field with a preference of "return=representation", and the specified condition evaluates to false, the server SHOULD include an entity representing the current state of the resource in the resulting 412 (Precondition Failed) response. See for examples.

The "depth-noroot" preference indicates that the client wishes for the server to exclude the target (root) resource from processing by the WebDAV method and only apply the WebDAV method to the target resource's subordinate resources.

depth-noroot = "depth-noroot"

This preference is only intended to be used with WebDAV methods whose definitions explicitly provide support for the Depth header field. Furthermore, this preference only applies when the Depth header field has a value of "1" or "infinity" (either implicitly or explicitly). The "depth-noroot" preference MAY be used in conjunction with the "return=minimal" preference in a single request. See for examples.

< RFC Editor: before publication please remove this section and the reference to > This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in . The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. According to , "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".

The open source Cyrus project is a highly scalable enterprise mail system which also supports calendaring and contacts. This production level CalDAV/CardDAV implementation supports all of the preferences described in this document and successfully interoperates with the , , and client implementations described below. This implementation is freely distributable under a BSD style license from Computing Services at Carnegie Mellon University.

The open source Calendar and Contacts Server project is a standards-compliant server implementing the CalDAV and CardDAV protocols. This production level implementation supports all of the preferences described in this document and successfully interoperates with the and client implementations described below. This implementation is freely distributable under the terms of the Apache License, Version 2.0.

Bedework is an open-source enterprise calendar system that supports public, personal, and group calendaring. This production level implementation supports the "return=minimal" preference described in this document and successfully interoperates with the client implementation described below. This implementation is freely distributable under the Jasig Licensing Policy.

DAViCal is a server for calendar sharing using the CalDAV protocol. This production level implementation supports the "return=minimal" preference described in this document and successfully interoperates with the client implementation described below. This implementation is Free Software distributable under the General Public License.

The widely used Apple Calendar and Apple Contacts clients are standards-compliant clients implementing the CalDAV and CardDAV protocols respectively. These production level implementations support the "return=minimal" preference described in this document and successfully interoperate with the and implementations described above. These client implementations are proprietary and are distributed as part of Apple's desktop operating systems.

aCal is an open source calendar client for Android which uses the CalDAV standard for communication. This implementation makes some use of each of the preferences described in this document and successfully interoperates with the server implementation described above. This implementation is freely distributable under the General Public License.

CalDAVTester is an open source test and performance application designed to work with CalDAV and/or CardDAV servers and tests various aspects of their protocol handling as well as performance. This widely used implementation supports all of the preferences described in this document and successfully interoperates with the server implementations described above. This implementation is freely distributable under the terms of the Apache License, Version 2.0.

No new security considerations are introduced by use of the Prefer header field with WebDAV request methods, beyond those discussed in and those already inherent in those methods.

The following preference is to be added to the HTTP Preferences Registry defined in Section 5.1 of . Preference: depth-noroot Description: The "depth-noroot" preference indicates that the client wishes for the server to exclude the target (root) resource from processing by the WebDAV method and only apply the WebDAV method to the target resource's subordinate resources. Reference: RFCXXXX, Notes: This preference is only intended to be used with WebDAV methods whose definitions explicitly provide support for the "Depth" header field. Furthermore, this preference only applies when the "Depth" header field has a value of "1" or "infinity" (either implicitly or explicitly).

The following methods are to have their references updated in the HTTP Method Registry defined in Section 8.1 of . Method Name References MKCALENDAR RFC4791, Section 5.3.1; RFCXXXX, MKCOL RFC4918, Section 9.3; RFC 5689, Section 3; RFCXXXX, PROPFIND RFC4918, Section 9.1; RFCXXXX, PROPPATCH RFC4918, Section 9.2; RFCXXXX, REPORT RFC3253, Section 3.6; RFCXXXX,

The author would like to thank the following individuals for contributing their ideas and support for writing this specification: Cyrus Daboo, Helge Hess, Andrew McMillan, Arnaud Quillaud, and Julian Reschke. The author would also like to thank the Calendaring and Scheduling Consortium for advice with this specification, and for organizing interoperability testing events to help refine it.

&rfc2119; &rfc3253; &rfc4791; &rfc4918; &rfc5689; &rfc5789; &rfc5995; &rfc7231; &rfc7232; &rfc7240; &rfc3744; &rfc6352; &rfc6578; &rfc6638; &rfc7942; Microsoft Developer Network Microsoft Developer Network Microsoft Developer Network Microsoft Developer Network

This document is based heavily on the Brief and extended Depth request header fields. The behaviors described in and are identical to those provided by the Brief header field when used with the PROPFIND and PROPPATCH methods respectively. The behavior described in is identical to that provided by the "1,noroot" and "infinity,noroot" Depth header field values. Client and server implementations that already support the Brief header field can add support for the "return=minimal" preference with nominal effort. If a server supporting the Prefer header field receives both the Brief and Prefer header fields in a request, clients can expect the server to ignore the Brief header field and only use the Prefer header field preferences.

This example tries to fetch one known and one unknown property from child resources.

>> Request << ]]>

>> Response << /container/ HTTP/1.1 200 OK HTTP/1.1 404 Not Found /container/work/ HTTP/1.1 200 OK HTTP/1.1 404 Not Found /container/home/ HTTP/1.1 200 OK HTTP/1.1 404 Not Found /container/foo.txt HTTP/1.1 200 OK HTTP/1.1 404 Not Found ]]>

This example tries to fetch one known and one unknown property from child resources only.

>> Request << ]]>

>> Response << /container/work/ HTTP/1.1 200 OK /container/home/ HTTP/1.1 200 OK /container/foo.txt HTTP/1.1 200 OK ]]>

This example tries to fetch an unknown property from a collection.

>> Request << ]]>

>> Response << /container/ HTTP/1.1 200 OK ]]>

This example tries to fetch an unknown property from several resources via the DAV:expand-property REPORT type.

>> Request << ]]>

>> Response << /dav/principals/ /dav/principals/user/ken/ ken /dav/calendars/user/ken/ HTTP/1.1 200 OK HTTP/1.1 404 Not Found /dav/addressbooks/user/ken/ HTTP/1.1 200 OK HTTP/1.1 404 Not Found HTTP/1.1 200 OK HTTP/1.1 404 Not Found HTTP/1.1 200 OK ]]>

This example tries to fetch an unknown property from several resources via the DAV:expand-property REPORT type.

>> Request << ]]>

>> Response << /dav/principals/ /dav/principals/user/ken/ ken /dav/calendars/user/ken/ HTTP/1.1 200 OK /dav/addressbooks/user/ken/ HTTP/1.1 200 OK HTTP/1.1 200 OK HTTP/1.1 200 OK ]]>

>> Request << My Container ]]>

>> Response << /container/ HTTP/1.1 200 OK ]]>

>> Request << My Container ]]>

>> Response <<

>> Request << My Container ]]>

>> Response << HTTP/1.1 200 OK ]]>

>> Request << My Container ]]>

>> Response <<

Note that this request is not conditional because by using the POST method the client lets the server choose the resource URI, thereby guaranteeing that it will not modify an existing resource.

>> Request <<

>> Response << Note that the server did not include any validator header fields (e.g ETag) in the response, signaling that the created representation differs from the representation sent in the body of the request. The client has to send a separate GET request to retrieve the current representation:

>> Request <<

>> Response <<

Note that this request is not conditional because by using the POST method the client lets the server choose the resource URI, thereby guaranteeing that it will not modify an existing resource.

>> Request <<

>> Response <<

>> Request <<

>> Response << The resource has been modified by another user agent (ETag mismatch), therefore the client has to send a separate GET request to retrieve the current representation:

>> Request <<

>> Response <<

>> Request <<

>> Response <<

< RFC Editor: before publication please remove this section >

Combined PROPFIND and REPORT sections Added several more RFCs to Updated list. Added list of report types that can benefit from "return=minimal". Changed REPORT example to use DAV:expand-property. Added IANA section to update HTTP Method Registry references. Split "return=representation" discussion into two separate sections and expanded text. Updated Open Issues with new questions. Several editorial changes from Julian Reschke.

Moved examples to Appendix B. Added reference to HTTP PATCH. Updated Implementation Status reference from RFC 6982 to RFC 7942.

No substantive changes. Refreshed due to pending expiration.

Updated HTTPbis and Prefer references to published RFCs.

Allow a minimal PROPFIND/REPORT response to contain a DAV:status element rather than an empty DAV:propstat element. Allow 204 (No Content) as a minimal PROPATCH success response. Added justification for why a minimal MKCOL/MKCALENDAR success response must have an empty body. Added text and an example of how "return=representation" can be employed with a conditional state-changing request and a 412 (Precondition Failed) response. Added a note to the POST+GET example bringing attention to the lack of a validator header field in the POST response. Reduced the number of inline references. Limited most examples to vanilla WebDAV. Reduced number of items in TOC. Removed the recommendation that the legacy Brief header functionality should be implemented. Added note about how a server should handle a request that contains both Brief and Prefer. Other editorial tweaks from Julian Reschke.

Added note stating where to send comments.

Limited "Updates" to just RFC 4918. Consensus from CalConnect membership that a "depth-root" option is unnecessary at this point. Consensus from CalConnect membership to remove Vary header field from PROPFIND and REPORT responses since these responses don't appear to be cached. Updated "Implementation Status" section boilerplate to RFC 6982. Added aCal to "Implementation Status" section. Added note that servers SHOULD respond with Preference-Applied when return=minimal is used with PROPFIND or REPORT.

Reintroduced "Updates" to header. Added text noting that "return=representation" provides a level of atomicity to the operation. Added "Implementation Status" section. Tweaked/corrected some examples.. Updated HTTPbis references.

Removed "Updates" from header. Fixed some missing/incorrect references. Reintroduced Cache-Control:no-cache to MKCOL responses.

Updated to comply with draft-snell-httpprefer-18. Reordered "Minimal REPORT Response" and "Minimal PROPPATCH Response" sections. Added some explanatory text to examples.

Updated references. Stated that "depth-noroot" can be used in conjuction with "return=minimal". Added text mentioning that "depth-noroot" is based on the MSDN "1,noroot" and "infinity,noroot" Depth header values. The server behavior required when "return=minimal" would result in zero DAV:propstat elements has been changed

from: /container/ HTTP/1.1 200 OK ]]>

to the slightly more verbose: /container/ HTTP/1.1 200 OK ]]>