| Internet-Draft | Collection Query | May 2019 |
| Murchison & Douglass | Expires 1 December 2019 | [Page] |
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 1 December 2019.¶
Copyright (c) 2019 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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
This document came about via discussions at the Calendaring and Scheduling Consortium.¶
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.¶
The request-URI MUST identify a collection. The request body MUST be a DAV:collection-query XML element (see Section 5.1)), which MUST contain one DAV:criteria XML element and one DAV:prop XML element, and MAY contain a DAV:limit XML element and/or a DAV:query-token XML element.¶
The response body for a successful request MUST be a DAV:multistatus XML element, which MUST contain one DAV:response element for each collection that matches the search criteria and MAY contain a DAV:query-token XML element and/or a DAV:total-matches XML element. Each response MAY contain one DAV:score XML element indicating the relevancy of the response to the search criteria. A given collection URL MUST appear only once in the response.¶
(DAV:number-of-matches-within-limits): The number of collections reported in the response must fall within the client-specified limit. This condition might be triggered if a client requests a limit on the number of responses (as per Section 4.6), but the server is unable to truncate the result set at or below that limit.¶
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 Section 9.2 of [RFC3744]. 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 ( Section 5.17 of [RFC5323]) 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.¶
collection-query¶
DAV:¶
WebDAV report used to search for collections matching certain criteria.¶
See Section 4.2¶
<!ELEMENT collection-query (criteria, limit?, query-token?, prop) > <!-- DAV:limit defined in RFC 5323, Section 5.17 --> <!-- DAV:prop defined in RFC 4918, Section 14.18 -->¶
criteria¶
DAV:¶
The criteria to use for the collection search.¶
See Section 4.3¶
<!ELEMENT criteria (terms) >¶
terms¶
DAV:¶
A set of search terms.¶
See Section 4.3¶
<!ELEMENT terms CDATA> <!-- Text MUST be a whitespace-separated list of terms -->¶
query-token¶
DAV:¶
An opaque token provided by the server and returned by the client.¶
See Section 4.5¶
<!ELEMENT query-token CDATA> <!-- Text MUST be a valid URI -->¶
multistatus¶
DAV:¶
Extends the DAV:multistatus element to include matching details.¶
See Section 4.2¶
<!ELEMENT multistatus (response*, responsedescription?,
query-token?, total-matches?) >
<!-- DAV:multistatus originally defined in RFC 4918, Section 14.16
but overridden here to add the DAV:query-token
and DAV:total-matches elements -->
<!-- DAV:responsedescription defined in RFC 4918, Section 14.25 -->¶
response¶
DAV:¶
Extends the DAV:response element to include matching details.¶
See Section 4.2¶
<!ELEMENT response (href, ((href*, status)|(propstat+)),
error?, responsedescription?, location?, score?) >
<!-- DAV:response originally defined in RFC 4918, Section 14.24
but overridden here to add the DAV:score element -->
<!-- DAV:href defined in RFC 4918, Section 14.7 -->
<!-- DAV:status defined in RFC 4918, Section 14.28 -->
<!-- DAV:propstat defined in RFC 4918, Section 14.22 -->
<!-- DAV:error defined in RFC 4918, Section 14.5 -->
<!-- DAV:responsedescription defined in RFC 4918, Section 14.25 -->
<!-- DAV:location defined in RFC 4918, Section 14.9 -->¶
score¶
DAV:¶
Indicates a relevancy score for the response.¶
See Section 4.2¶
<!ELEMENT score CDATA> <!-- Text MUST be a floating point number between 0.0 and 1.0 -->¶
total-matches¶
DAV:¶
The total number of collections matching the query.¶
See Section 4.2¶
<!ELEMENT total-matches CDATA> <!-- Text MUST be a non-negative integer -->¶
This extension does not introduce any new security concerns beyond those already described in HTTP and WebDAV.¶