Calendaring Extensions | K. Murchison |
Internet-Draft | FastMail |
Intended status: Informational | M. Douglass |
Expires: August 29, 2021 | Spherical Cow Group |
February 25, 2021 |
Collection Query Report for Web Distributed Authoring and Versioning (WebDAV)
draft-murchison-webdav-collection-query-00
This specification defines an extension to Web Distributed Authoring and Versioning (WebDAV) to search for WebDAV collections based upon a set of client-supplied criteria.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on August 29, 2021.
Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 3.2) as a purely notational convention. WebDAV request and response bodies cannot be validated by a DTD due to the specific extensibility rules defined in Section 17 of [RFC4918] and due to the fact that all XML elements defined by this specification use the XML namespace name "DAV:". In particular:
When an XML element type in the "DAV:" namespace is referenced in this document outside of the context of an XML fragment, the string "DAV:" will be prefixed to the element type.
This document inherits, and sometimes extends, DTD productions from Section 14 of [RFC4918].
WebDAV [RFC4918] defines the concept of 'collections', which are hierarchical groupings of WebDAV resources on an HTTP [RFC7230] server. Collections can be of arbitrary size and depth (i.e., collections within collections). A WebDAV client may only be interested in resources contained in a subset of all of the collections on a server.
This specification defines a new WebDAV report that allows a client to search for collections based on a set of criteria.
If the DAV:collection-query report is implemented by a WebDAV server, then the server MUST list the report in the "DAV:supported-report-set" property on any collection that can be queried.
A server MAY limit the number of member URLs in a response, for example, to limit the amount of work expended in processing a request, or as the result of an explicit limit set by the client. If the result set is truncated, the response MUST use status code 207 (Multi-Status), return a DAV:multistatus response body, and indicate a status of 507 (Insufficient Storage) for the request-URI. That DAV:response element SHOULD include a DAV:error element with the DAV:number-of-matches-within-limits precondition, as defined in [RFC3744] (Section 9.2). DAV:response elements for all the collections being reported are also included.
When truncation occurs, the DAV:query-token value returned in the response MUST represent the correct state for the partial set of results returned. That allows the client to use the returned DAV:query-token to fetch the next set of results. In this way, the client can effectively "page" through the entire set of results in a consistent manner.
Clients MUST handle the 507 status on the request-URI in the response to the report.
A client can limit the number of results returned by the server through use of the DAV:limit element ([RFC5323], Section 5.17) in the request body. This is useful when clients have limited space or bandwidth for the results. If a server is unable to truncate the result at or below the requested number, then it MUST fail the request with a DAV:number-of-matches-within-limits postcondition error. When the results can be correctly limited by the server, the server MUST follow the rules above for indicating a result set truncation to the client.
This extension does not introduce any new security concerns beyond those already described in HTTP and WebDAV.
This document came about via discussions at the Calendaring and Scheduling Consortium.
[RFC4791] | Daboo, C., Desruisseaux, B. and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, March 2007. |
[RFC6352] | Daboo, C., "CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)", RFC 6352, DOI 10.17487/RFC6352, August 2011. |