Calendaring Extensions K. Murchison
Internet-Draft FastMail
Intended status: Informational M. Douglass
Expires: June 14, 2020 Spherical Cow Group
December 12, 2019

Collection Query Report for Web Distributed Authoring and Versioning (WebDAV)
draft-murchison-webdav-collection-query-00

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.

Status of This Memo

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 June 14, 2020.

Copyright Notice

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 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.


Table of Contents

1. Introduction

2. 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 [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:

  1. Element names use the "DAV:" namespace.
  2. Element ordering is irrelevant unless explicitly stated otherwise.
  3. Extension elements (elements not already defined as valid child elements) may be added anywhere, except when explicitly stated otherwise.
  4. 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 Section 14 of [RFC4918].

3. Querying Collections

3.1. Overview

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.

3.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 Section 4.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 Section 3.6), but the server is unable to truncate the result set at or below that limit.

3.3. Search Criteria

3.4. Depth Behavior

3.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 [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.

3.6. Limiting Results

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.

4. XML Element Definitions

4.1. DAV:collection-query XML Element

4.2. DAV:criteria XML Element

4.3. DAV:terms XML Element

4.4. DAV:query-token XML Element

4.5. DAV:multistatus XML Element

4.6. DAV:response XML Element

4.7. DAV:score XML Element

4.8. DAV:total-matches XML Element

5. Security Considerations

This extension does not introduce any new security concerns beyond those already described in HTTP and WebDAV.

6. Acknowledgments

This document came about via discussions at the Calendaring and Scheduling Consortium.

7. References

7.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and J. Whitehead, "Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)", RFC 3253, DOI 10.17487/RFC3253, March 2002.
[RFC3744] Clemm, G., Reschke, J., Sedlar, E. and J. Whitehead, "Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol", RFC 3744, DOI 10.17487/RFC3744, May 2004.
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, June 2007.
[RFC5323] Reschke, J., Reddy, S., Davis, J. and A. Babich, "Web Distributed Authoring and Versioning (WebDAV) SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008.
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
[W3C.REC-xml-20081126] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E. and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008.

7.2. Informative References

[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.

Authors' Addresses

Kenneth Murchison FastMail US LLC 1429 Walnut St, Suite 1201 Philadephia, PA 19102 United States of America EMail: murch@fastmailteam.com URI: http://www.fastmail.com/
Michael Douglass Spherical Cow Group 226 3rd Street Troy, NY 12180 United States of America EMail: mdouglass@sphericalcowgroup.com URI: http://sphericalcowgroup.com