Abstract
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.
Collection Query Report for Web Distributed Authoring and Versioning (WebDAV)
2. Normative references
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
IETF RFC 2119, S. BRADNER. Key words for use in RFCs to Indicate Requirement Levels. 1997. RFC Publisher. https://www.rfc-editor.org/info/rfc2119.
IETF RFC 3253, G. CLEMM, J. AMSDEN, T. ELLISON, C. KALER and J. WHITEHEAD. Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning). 2002. RFC Publisher. https://www.rfc-editor.org/info/rfc3253.
IETF RFC 3744, G. CLEMM, J. RESCHKE, E. SEDLAR and J. WHITEHEAD. Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol. 2004. RFC Publisher. https://www.rfc-editor.org/info/rfc3744.
IETF RFC 4918, L. DUSSEAULT (ed.). HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV). 2007. RFC Publisher. https://www.rfc-editor.org/info/rfc4918.
IETF RFC 5323, S. REDDY, J. DAVIS and A. BABICH. Web Distributed Authoring and Versioning (WebDAV) SEARCH. 2008. RFC Publisher. https://www.rfc-editor.org/info/rfc5323.
IETF RFC 7230, R. FIELDING and J. RESCHKE (eds.). Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. 2014. RFC Publisher. https://www.rfc-editor.org/info/rfc7230.
IETF RFC 8174, B. LEIBA. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. 2017. RFC Publisher. https://www.rfc-editor.org/info/rfc8174.
W3C REC-xml-20081126, EVE MALER, FRANÇOIS YERGEAU, JEAN PAOLI, MICHAEL SPERBERG-MCQUEEN and TIM BRAY (eds.). Extensible Markup Language (XML) 1.0 (Fifth Edition). 2008. World Wide Web Consortium. https://www.w3.org/TR/2008/REC-xml-20081126/.
3. Terms and definitions
No terms and definitions are listed in this document.
4. Conventions Used in This Document
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 IETF RFC 2119 IETF RFC 8174 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 IETF RFC 4918, Section 17 and due to the fact that all XML elements defined by this specification use the XML namespace name “DAV:”.
In particular:
Element names use the “DAV:” namespace.
Element ordering is irrelevant unless explicitly stated otherwise.
Extension elements (elements not already defined as valid child elements) may be added anywhere, except when explicitly stated otherwise.
Extension attributes (attributes not already defined as valid for this element) may be added anywhere, except when explicitly stated otherwise.
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 IETF RFC 4918, Section 14.
5. Querying Collections
5.1. Overview
WebDAV IETF RFC 4918 defines the concept of ‘collections’, which are hierarchical groupings of WebDAV resources on an HTTP IETF RFC 7230 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.
5.2. DAV:collection-query Report
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.
Marshalling
The request-URI MUST identify a collection. The request body MUST be a DAV:collection-query XML element (see Clause 6.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.
Preconditions
Postconditions
(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 Clause 5.6), but the server is unable to truncate the result set at or below that limit.
5.5. Truncation of Results
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 IETF RFC 3744, 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.
5.6. Limiting Results
A client can limit the number of results returned by the server through use of the DAV:limit element ( IETF RFC 5323, 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.
6. XML Element Definitions
6.1. DAV:collection-query XML Element
Name
collection-query
Namespace
DAV:
Purpose
WebDAV report used to search for collections matching certain criteria.
Description
See Clause 5.2
<!ELEMENT collection-query (criteria, limit?, query-token?, prop) >
<!-- DAV:limit defined in IETF RFC 5323, Section 5.17 -->
<!-- DAV:prop defined in IETF RFC 4918, Section 14.18 -->
6.2. DAV:criteria XML Element
Name
criteria
Namespace
DAV:
Purpose
The criteria to use for the collection search.
Description
See Clause 5.3
<!ELEMENT criteria (terms) >
6.3. DAV:terms XML Element
Name
terms
Namespace
DAV:
Purpose
A set of search terms.
Description
See Clause 5.3
<!ELEMENT terms CDATA>
<!-- Text MUST be a whitespace-separated list of terms -->
6.4. DAV:query-token XML Element
Name
query-token
Namespace
DAV:
Purpose
An opaque token provided by the server and returned by the client.
Description
See Clause 5.5
<!ELEMENT query-token CDATA>
<!-- Text MUST be a valid URI -->
6.5. DAV:multistatus XML Element
Name
multistatus
Namespace
DAV:
Purpose
Extends the DAV:multistatus element to include matching details.
Description
See Clause 5.2
<!ELEMENT multistatus (response*, responsedescription?,
query-token?, total-matches?) >
<!-- DAV:multistatus originally defined in IETF RFC 4918, Section 14.16
but overridden here to add the DAV:query-token
and DAV:total-matches elements -->
<!-- DAV:responsedescription defined in IETF RFC 4918, Section 14.25 -->
6.6. DAV:response XML Element
Name
response
Namespace
DAV:
Purpose
Extends the DAV:response element to include matching details.
Description
See Clause 5.2
<!ELEMENT response (href, ((href*, status)|(propstat+)),
error?, responsedescription?, location?, score?) >
<!-- DAV:response originally defined in IETF RFC 4918, Section 14.24
but overridden here to add the DAV:score element -->
<!-- DAV:href defined in IETF RFC 4918, Section 14.7 -->
<!-- DAV:status defined in IETF RFC 4918, Section 14.28 -->
<!-- DAV:propstat defined in IETF RFC 4918, Section 14.22 -->
<!-- DAV:error defined in IETF RFC 4918, Section 14.5 -->
<!-- DAV:responsedescription defined in IETF RFC 4918, Section 14.25 -->
<!-- DAV:location defined in IETF RFC 4918, Section 14.9 -->
6.7. DAV:score XML Element
Name
score
Namespace
DAV:
Purpose
Indicates a relevancy score for the response.
Description
See Clause 5.2
<!ELEMENT score CDATA>
<!-- Text MUST be a floating point number between 0.0 and 1.0 -->
6.8. DAV:total-matches XML Element
Name
total-matches
Namespace
DAV:
Purpose
The total number of collections matching the query.
Description
See Clause 5.2
<!ELEMENT total-matches CDATA>
<!-- Text MUST be a non-negative integer -->
7. Security Considerations
This extension does not introduce any new security concerns beyond those already described in HTTP and WebDAV.
8. Acknowledgments
This document came about via discussions at the Calendaring and Scheduling Consortium.
Bibliography
[1] IETF RFC 4791, C. DABOO, B. DESRUISSEAUX and L. DUSSEAULT. Calendaring Extensions to WebDAV (CalDAV). 2007. RFC Publisher. https://www.rfc-editor.org/info/rfc4791.
[2] IETF RFC 6352, C. DABOO. CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV). 2011. RFC Publisher. https://www.rfc-editor.org/info/rfc6352.