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 July 22, 2022.

Copyright Notice

Copyright (c) 2022 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
• 3. Querying Collections
• 3.1. Overview
• 3.2. DAV:collection-query Report
• 3.3. Search Criteria
• 3.4. Depth Behavior
• 3.5. Truncation of Results
• 3.6. Limiting Results
• 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
• 6. Acknowledgments
• 7. References
• 7.1. Normative References
• 7.2. Informative References
• Authors' Addresses

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

• Name: collection-query
• Namespace: DAV:
• Purpose: WebDAV report used to search for collections matching certain criteria.
• Description: See Section 3.2
  
  <!ELEMENT collection-query (criteria, limit?, query-token?, prop) >
  
  <!-- DAV:limit defined in [RFC5323], Section 5.17 -->
  <!-- DAV:prop defined in [RFC4918], Section 14.18 -->

4.2. DAV:criteria XML Element

• Name: criteria
• Namespace: DAV:
• Purpose: The criteria to use for the collection search.
• Description: See Section 3.3
  
  <!ELEMENT criteria (terms) >

4.3. DAV:terms XML Element

• Name: terms
• Namespace: DAV:
• Purpose: A set of search terms.
• Description: See Section 3.3
  
  <!ELEMENT terms CDATA>
  
  <!-- Text MUST be a whitespace-separated list of terms -->

4.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 Section 3.5
  
  <!ELEMENT query-token CDATA>
  
  <!-- Text MUST be a valid URI -->

4.5. DAV:multistatus XML Element

• Name: multistatus
• Namespace: DAV:
• Purpose: Extends the DAV:multistatus element to include matching details.
• Description: See Section 3.2
  
  <!ELEMENT multistatus (response*, responsedescription?,
  query-token?, total-matches?) >
  
  <!-- DAV:multistatus originally defined in [RFC4918], Section 14.16 but overridden here to add the DAV:query-token and DAV:total-matches elements -->
  <!-- DAV:responsedescription defined in [RFC4918], Section 14.25 -->

4.6. DAV:response XML Element

• Name: response
• Namespace: DAV:
• Purpose: Extends the DAV:response element to include matching details.
• Description: See Section 3.2
  
  <!ELEMENT response (href, ((href*, status)|(propstat+)),
  error?, responsedescription?, location?, score?) >
  
  <!-- DAV:response originally defined in [RFC4918], Section 14.24 but overridden here to add the DAV:score element -->
  <!-- DAV:href defined in [RFC4918], Section 14.7 -->
  <!-- DAV:status defined in [RFC4918], Section 14.28 -->
  <!-- DAV:propstat defined in [RFC4918], Section 14.22 -->
  <!-- DAV:error defined in [RFC4918], Section 14.5 -->
  <!-- DAV:responsedescription defined in [RFC4918], Section 14.25 -->
  <!-- DAV:location defined in [RFC4918], Section 14.9 -->

4.7. DAV:score XML Element

• Name: score
• Namespace: DAV:
• Purpose: Indicates a relevancy score for the response.
• Description: See Section 3.2
  
  <!ELEMENT score CDATA>
  
  <!-- Text MUST be a floating point number between 0.0 and 1.0 -->

4.8. DAV:total-matches XML Element

• Name: total-matches
• Namespace: DAV:
• Purpose: The total number of collections matching the query.
• Description: See Section 3.2
  
  <!ELEMENT total-matches CDATA>
  
  <!-- Text MUST be a non-negative integer -->

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

7.2. Informative References

Authors' Addresses