WebDAV SEARCH

³ This document defines WebDAV SEARCH, an application of HTTP/1.1 forming a lightweight search protocol to transport queries and result sets and allows clients to make use of server-side search facilities. It is based on the expired draft for WebDAV DASL [DASL]. [DASLREQ] describes the motivation for DASL.¶

⁴ DASL will minimize the complexity of clients so as to facilitate widespread deployment of applications capable of utilizing the DASL search mechanisms.¶

⁵ DASL consists of: ¶

• the SEARCH method,
• the DASL response header,
• the DAV:searchrequest XML element,
• the DAV:queryschema property,
• the DAV:basicsearch XML element and query grammar, and
• the DAV:basicsearchschema XML element.

¹² For WebDAV-compliant servers, it also defines a new live property DAV:supported-query-grammar-set.¶

¹³ DASL relies on the resource and property model defined by [RFC2518]. DASL does not alter this model. Instead, DASL allows clients to access DAV-modeled resources through server-side search.¶

¹⁴ This draft uses the terms defined in [RFC2616], [RFC2518], and [DASLREQ].¶

¹⁵ The augmented BNF used by this document to describe protocol elements is exactly the same as the one described in Section 2.1 of [RFC2616]. Because this augmented BNF uses the basic production rules provided in Section 2.2 of [RFC2616], those rules apply to this document as well.¶

¹⁶ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT" "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].¶

¹⁷ 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.¶

¹⁸ Note that this draft currently defines elements and properties in the WebDAV namespace "DAV:", which it shouldn't do as it isn't a work item of the WebDAV working group. The reason for this is the desire for some kind of backward compatibility to the expired DASL drafts and the assumption that the draft may become an official RFC submission of the WebDAV working group at a later point of time.¶

¹⁹ Similarily, when an XML element type in the namespace "http://www.w3.org/2001/XMLSchema" is referenced in this document outside of the context of an XML fragment, the string "xs:" will be prefixed to the element type.¶

²⁰ One can express the basic usage of DASL in the following steps: ¶

• The client constructs a query using the DAV:basicsearch grammar.
• The client invokes the SEARCH method on a resource that will perform the search (the search arbiter) and includes a text/xml or application/xml request entity that contains the query.
• The search arbiter performs the query.
• The search arbiter sends the results of the query back to the client in the response. The server MUST send an entity that matches the [RFC2518] PROPFIND response.

²⁵ The client invokes the SEARCH method to initiate a server-side search. The body of the request defines the query. The server MUST emit an entity matching the [RFC2518] PROPFIND response.¶

²⁶ The SEARCH method plays the role of transport mechanism for the query and the result set. It does not define the semantics of the query. The type of the query defines the semantics.¶

²⁷ The client invokes the SEARCH method on the resource named by the Request-URI.¶

³² The DAV:searchrequest XML element contains a single XML element that defines the query. The name of the query element defines the type of the query. The value of that element defines the query itself.¶

³³ If the server returns 207 (Multistatus), then the search proceeded successfully and the response MUST match that of a PROPFIND. The results of this method SHOULD NOT be cached.¶

³⁴ There MUST be one DAV:response for each resource that matched the search criteria. For each such response, the DAV:href element contains the URI of the resource, and the response MUST include a DAV:propstat element.¶

³⁵ Note that for each matching resource found there may be multiple URIs within the search scope mapped to it. In this case, a server SHOULD report all of these URIs. Clients can use the live property DAV:resource-id defined in [BIND] to identify possible duplicates.¶

³⁶ In addition, the server MAY include DAV:response items in the reply where the DAV:href element contains a URI that is not a matching resource, e.g. that of a scope or the query arbiter. Each such response item MUST NOT contain a DAV:propstat element, and MUST contain a DAV:status element (unless no property was selected).¶

⁴⁷ If an error occurred that prevented execution of the query, the server MUST indicate the failure with the appropriate status code and SHOULD include a DAV:multistatus element to point out errors associated with scopes.¶

⁴⁸ 400 Bad Request. The query could not be executed. The request may be malformed (not valid XML for example). Additionally, this can be used for invalid scopes and search redirections.¶

⁴⁹ 422 Unprocessable entity. The query could not be executed. If a application/xml or text/xml request entity was provided, then it may have been well-formed but may have contained an unsupported or unimplemented query operator.¶

⁵⁹ The OPTIONS method allows the client to discover if a resource supports the SEARCH method and to determine the list of search grammars supported for that resource.¶

⁶⁰ The client issues the OPTIONS method against a resource named by the Request-URI. This is a normal invocation of OPTIONS defined in [RFC2616].¶

⁶¹ If a resource supports the SEARCH method, then the server MUST list SEARCH in the OPTIONS response as defined by [RFC2616].¶

⁶² DASL servers MUST include the DASL header in the OPTIONS response. This header identifies the search grammars supported by that resource.¶

⁶³ >> Response:

DASLHeader = "DASL" ":" Coded-URL-List
Coded-URL-List : Coded-URL [ "," Coded-URL-List ]
Coded-URL ; defined in section 9.4 of [RFC2518]

⁶⁴ The DASL response header indicates server support for a query grammar in the OPTIONS method. The value is a URI that indicates the type of grammar. Note that although the URI can be used to identify each supported search grammar, there is not necessarily a direct relationship between the URI and the XML element name that can be used in XML based SEARCH requests (the element name itself is identified by it's namespace name (a URI reference) and the element's local name).¶

⁶⁵ This header MAY be repeated.¶

⁶⁶ For example:

DASL: <http://foobar.test/syntax1> 
DASL: <http://akuma.test/syntax2>
DASL: <DAV:basicsearch>
DASL: <http://example.com/foo/natural-language-query>

⁶⁷ This WebDAV property is required for any server supporting either [RFC3253] and/or [ACL] and identifies the XML based query grammars that are supported by the search arbiter resource.¶

⁶⁸ ANY value: a query grammar element type¶

⁶⁹ This example shows that the server supports search on the /somefolder resource with the query grammars: DAV:basicsearch, http://foobar.test/syntax1 and http://akuma.test/syntax2. Note that every server MUST support DAV:basicsearch.¶

⁷⁰ >> Request:

OPTIONS /somefolder HTTP/1.1
Host: example.org

⁷¹ >> Response:

HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH
DASL: <DAV:basicsearch>
DASL: <http://foobar.test/syntax1> 
DASL: <http://akuma.test/syntax2>

⁷² This example shows the equivalent taking advantage of a server's support for DAV:supported-method-set and DAV:supported-query-grammar-set.¶

⁷³ >> Request:

PROPFIND /somefolder HTTP/1.1
Host: example.org
Depth: 0
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx

<?xml version="1.0" encoding="UTF-8" ?>
<propfind xmlns="DAV:">
  <prop>
    <supported-query-grammar-set/>
    <supported-method-set/>
  </prop>
</propfind>

⁷⁴ >> Response:

HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx

<?xml version="1.0" encoding="utf-8" ?>
<multistatus xmlns="DAV:">
 <response>
  <href>http://example.org/somefolder</href>
  <propstat>
   <prop>
    <supported-query-grammar-set>
     <supported-query-grammar>
      <grammar><basicsearch/></grammar>
     </supported-query-grammar>
     <supported-query-grammar>
      <grammar><syntax1 xmlns="http://foobar.test" /></grammar>
     </supported-query-grammar>
     <supported-query-grammar>
      <grammar><syntax2 xmlns="http://akuma.test/"/></grammar>
     </supported-query-grammar>
    </supported-query-grammar-set>
    <supported-method-set>
     <supported-method name="COPY" />
     <supported-method name="DELETE" />
     <supported-method name="GET" />
     <supported-method name="HEAD" />
     <supported-method name="LOCK" />
     <supported-method name="MKCOL" />
     <supported-method name="MOVE" />
     <supported-method name="OPTIONS" />
     <supported-method name="POST" />
     <supported-method name="PROPFIND" />
     <supported-method name="PROPPATCH" />
     <supported-method name="PUT" />
     <supported-method name="SEARCH" />
     <supported-method name="TRACE" />
     <supported-method name="UNLOCK" />
    </supported-method-set>
   </prop>
   <status>HTTP/1.1 200 OK</status>
  </propstat>
 </response>
</multistatus>

⁷⁵ Note that the query grammar element names marshalled as part of the DAV:supported-query-grammar-set can be directly used as element names in an XML based query.¶

⁷⁹ Each query grammar supported by DASL defines its own syntax for expressing the possible query schema. A client retrieves the schema for a given query grammar on an arbiter resource with a given scope by invoking the SEARCH method on that arbiter with that grammar and scope and with a root element of DAV:query-schema-discovery rather than DAV:searchrequest.¶

⁸⁰ Marshalling: ¶

• The request body MUST be DAV:query-schema-discovery element.

  <!ELEMENT query-schema-discovery ANY>
  ANY value: XML element defining a valid query
  

• The response body takes the form of a RFC2518 DAV:multistatus element, where DAV:response is extended to hold the returned query grammar inside a DAV:query-schema container element.

  <!ELEMENT response (href, ((href*, status)|(propstat+)),
    query-schema?, responsedescription?) >
  <!ELEMENT query-schema ANY>
  

⁸³ The content of this container is an XML element whose name and syntax depend upon the grammar, and whose value may (and likely will) vary depending upon the grammar, arbiter, and scope.¶

⁸⁸ DAV:basicsearch uses an extensible XML syntax that allows clients to express search requests that are generally useful for WebDAV scenarios. DASL-extended servers MUST accept this grammar, and MAY accept other grammars.¶

• DAV:select provides the result record definition.
• DAV:from defines the scope.
• DAV:where defines the criteria.
• DAV:orderby defines the sort order of the result set.
• DAV:limit provides constraints on the query as a whole.

⁹⁷ DAV:select defines the result record, which is a set of properties and values. This document defines two possible values: DAV:allprop and DAV:prop, both defined in [RFC2518] and revised in [RFC3253].¶

⁹⁸ DAV:from defines the query scope. This contains exactly one DAV:scope element. The scope element contains mandatory DAV:href and DAV:depth elements.¶

⁹⁹ DAV:href indicates the URI to use as a scope.¶

¹⁰⁰ When the scope is a collection, if DAV:depth is "0", the search includes only the collection. When it is "1", the search includes the (toplevel) members of the collection. When it is "infinity", the search includes all recursive members of the collection. When the scope is not a collection, the depth is ignored and the search applies just to the resource itself.¶

¹⁰⁵ The DAV:where element defines the search condition for inclusion of resources in the result set. The value of this element is an XML element that defines a search operator that evaluates to one of the Boolean truth values TRUE, FALSE, or UNKNOWN. The search operator contained by DAV:where may itself contain and evaluate additional search operators as operands, which in turn may contain and evaluate additional search operators as operands, etc. recursively.¶

¹¹⁶ The DAV:orderby element specifies the ordering of the result set. It contains one or more DAV:order elements, each of which specifies a comparison between two items in the result set. Informally, a comparison specifies a test that determines whether one resource appears before another in the result set. Comparisons are applied in the order they occur in the DAV:orderby element, earlier comparisons being more significant.¶

¹¹⁷ The comparisons defined here use only a single property from each resource, compared using the same ordering as the DAV:lt operator (ascending) or DAV:gt operator (descending). If neither direction is specified, the default is DAV:ascending.¶

¹¹⁸ In the context of the DAV:orderby element, null values are considered to collate before any actual (i.e., non null) value, including strings of zero length (this is compatible with [SQL99]).¶

¹²² The DAV:and operator performs a logical AND operation on the expressions it contains.¶

¹²³ The DAV:or operator performs a logical OR operation on the values it contains.¶

¹²⁴ The DAV:not operator performs a logical NOT operation on the values it contains.¶

¹²⁵ The DAV:eq operator provides simple equality matching on property values.¶

¹²⁶ The "caseless" attribute may be used with this element.¶

¹²⁷ The DAV:lt, DAV:lte, DAV:gt, and DAV:gte operators provide comparisons on property values, using less-than, less-than or equal, greater-than, and greater-than or equal respectively. The "caseless" attribute may be used with these elements.¶

¹²⁸ DAV:literal allows literal values to be placed in an expression.¶

¹²⁹ White space in literal values is significant in comparisons. For consistency with [RFC2518], clients SHOULD NOT specify the attribute "xml:space" (section 2.10 of [XML]) to override this behaviour.¶

¹³⁰ In comparisons, the contents of DAV:literal SHOULD be treated as string, with the following exceptions: ¶

• when operand for a comparison with a DAV:getcontentlength property, it SHOULD be treated as an integer value (the behaviour for non-integer values is undefined),
• when operand for a comparison with a DAV:creationdate or DAV:getlastmodified property, it SHOULD be treated as a date value in the ISO-8601 subset defined for the DAV:creationdate property ([RFC2518], section 13.1).
• when operand for a comparison with a property for which the type is known, it MAY be treated according to this type.

¹³⁴ There are situations in which a client may want to force a comparison not to be string-based (as defined for DAV:literal). In these cases, a typed comparison can be enforced by using DAV:typed-literal instead.¶

¹³⁵ The data type is specified using the xsi:type attribute defined in [XS1], section 2.6.1. If the type is not specified, it defaults to "xs:string".¶

¹³⁶ A server MUST reject a request with an unknown type.¶

¹⁴⁰ The DAV:is-collection operator allows clients to determine whether a resource is a collection (that is, whether it's DAV:resourcetype element contains the element DAV:collection).¶

¹⁴¹ Rationale: This operator is provided in lieu of defining generic structure queries, which would suffice for this and for many more powerful queries, but seems inappropriate to standardize at this time.¶

¹⁴³ The DAV:is-defined operator allows clients to determine whether a property is defined on a resource. The meaning of "defined on a resource" is found in Section 5.5.3.¶

¹⁴⁴ Example:

<d:is-defined>
  <d:prop><x:someprop/></d:prop>
</d:is-defined>

¹⁴⁵ The DAV:like is an optional operator intended to give simple wildcard-based pattern matching ability to clients.¶

¹⁴⁶ The operator takes two arguments.¶

¹⁴⁷ The first argument is a DAV:prop element identifying a single property to evaluate.¶

¹⁴⁸ The second argument is a DAV:literal element that gives the pattern matching string.¶

¹⁵⁴ The DAV:contains operator is an optional operator that provides content-based search capability. This operator implicitly searches against the text content of a resource, not against content of properties. The DAV:contains operator is intentionally not overly constrained, in order to allow the server to do the best job it can in performing the search.¶

¹⁵⁵ The DAV:contains operator evaluates to a Boolean value. It evaluates to TRUE if the content of the resource satisfies the search. Otherwise, It evaluates to FALSE.¶

¹⁵⁶ Within the DAV:contains XML element, the client provides a phrase: a single word or whitespace delimited sequence of words. Servers MAY ignore punctuation in a phrase. Case-sensitivity is left to the server.¶

¹⁵⁷ The following things may or may not be done as part of the search: Phonetic methods such as "soundex" may or may not be used. Word stemming may or may not be performed. Thesaurus expansion of words may or may not be done. Right or left truncation may or may not be performed. The search may be case insensitive or case sensitive. The word or words may or may not be interpreted as names. Multiple words may or may not be required to be adjacent or "near" each other. Multiple words may or may not be required to occur in the same order. Multiple words may or may not be treated as a phrase. The search may or may not be interpreted as a request to find documents "similar" to the string operand.¶

¹⁶⁵ The DAV:limit XML element contains requested limits from the client to limit the size of the reply or amount of effort expended by the server. The DAV:nresults XML element contains a requested maximum number of DAV:response elements to be returned in the response body. The server MAY disregard this limit. The value of this element is an integer.¶

¹⁶⁷ The "caseless" attribute allows clients to specify caseless matching behaviour instead of character-by-character matching for DAV:basicsearch operators.¶

¹⁶⁸ The possible values for "caseless" are "yes" or "no". The default value is server-specified. Caseless matching SHOULD be implemented as defined in [CaseMap].¶

¹⁶⁹ Support for the "caseless" attribute is optional. A server should respond with a status of 422 if it is used but cannot be supported.¶

1. the set of properties that may be either searched, returned, or used to sort, and a hint about the data type of such properties
2. the set of optional operators defined by the resource.

Feb 14, 1998

Initial Draft

Feb 28, 1998

Referring to DASL as an extension to HTTP/1.1 rather than DAV.
Added new sections "Notational Conventions", "Protocol Model", "Security Considerations".
Changed section 3 to "Elements of Protocol".
Added some stuff to introduction.
Added "result set" terminology.
Added "IANA Considerations".

Mar 9, 1998

Moved sub-headings of "Elements of Protocol" to first level and removed "Elements of Protocol" Heading.
Added an sentence in introduction explaining that this is a "sketch" of a protocol.

Mar 11, 1998

Added orderby, data typing, three valued logic, query schema property, and element definitions for schema for basicsearch.

April 8, 1998

- made changes based on last week's DASL BOF.

May 8, 1998

Removed most of DAV:searcherror; converted to DAV:searchredirect
Altered DAV:basicsearch grammar to use avoid use of ANY in DTD

June 17, 1998

-Added details on Query Schema Discovery
-Shortened list of data types

June 23, 1998

moved data types before change history
rewrote the data types section
removed the casesensitive element and replace with the casesensitive attribute
added the casesensitive attribute to the DTD for all operations that might work on a string

Jul 20, 1998

A series of changes. See Author's meeting minutes for details.

July 28, 1998

Changes as per author's meeting. QSD uses SEARCH, not PROPFIND.
Moved text around to keep concepts nearby.
Boolean literals are 1 and 0, not T and F.
contains changed to contentspassthrough.
Renamed rank to score.

July 28, 1998

Added Dale Lowry as Author

September 4, 1998

Added 422 as response when query lists unimplemented operators.
DAV:literal declares a default value for xml:space, 'preserve' (see XML spec, section 2.10)
moved to new XML namespace syntax

September 22, 1998

Changed "simplesearch" to "basicsearch"
Changed isnull to isdefined
Defined NULLness as having a 404 or 403 response
used ENTITY syntax in DTD
Added redirect

October 9, 1998

Fixed a series of typographical and formatting errors.
Modified the section of three-valued logic to use a table rather than a text description of the role of UNKNOWN in expressions.

November 2, 1998

Added the DAV:contains operator.
Removed the DAV:contentpassthrough operator.

November 18, 1998

Various author comments for submission

June 3, 1999

Cosmetic and minor editorial changes only. Fix nits reported by Jim Whitehead in email of April 26, 1999. Converted to HTML from Word 97, manually.

April 20, 2000

Removed redirection feature, since 301/302 suffices. Removed Query Schema Discovery (former chapter 4). Everyone agrees this is a useful feature, but it is apparently too difficult to define at this time, and it is not essential for DASL.

October 09, 2001

Added Julian Reschke as author.
Chapter about QSD re-added.
Formatted into RFC2629-compliant XML document.
Added first comments.
ID version number kicked up to draft-dasl-protocol-03.

October 17, 2001

Updated address information for Jim Davis.
Added issue of datatype vocabularies.
Updated issue descriptions for grammar discovery, added issues on query schema DTD.
Fixed typos in XML examples.

December 17, 2001

Re-introduced split between normative and non-normative references.

January 05, 2002

Version bumbed up to 04. Started work on resolving the issues identified in the previous version.

January 14, 2002

Fixed some XML typos.

January 22, 2002

Closed issues naming-of-elements. Fixed query search DTD and added option to discover properties of "other" (non-listed) properties.

January 25, 2002

Changed into private submission and added reference to historic DASL draft. Marked reference to DASL requirements non-normative.
Updated reference to latest deltav spec.

January 29, 2002

Added feedback from and updated contact info for Alan Babich.
Included open issues collected in http://www.webdav.org/dasl/protocol/issues.html.

February 8, 2002

Made sure that all artwork fits into 72 characters wide text.

February 18, 2002

Changed Insufficient storage handling (multistatus). Moved is-collection to operators and added to DTD. Made scope/depth mandatory.

February 20, 2002

Updated reference to SQL99.

February 28, 2002

"Non-normative References" -> "Informative References". Abstract updated. Consistently specify a charset when using text/xml (no change bars). Do not attempt to define PROPFIND's entity encoding (take out specific references to text/xml). Remove irrelevant headers (Connection:) from examples (no change bars). Added issue on querying based on DAV:href. Updated introduction to indicate relationship to DASL draft. Updated HTTP reference from RFC2068 to RFC2616. Updated XML reference to XML 1.0 2nd edition.

March 1, 2002

Removed superfluous namespace decl in 2.4.2. Reopened JW14 and suggest to drop xml:space support.

March 3, 2002

Removed "xml:space" feature on DAV:literal. Added issue about string comparison vs. collations vs. xml:lang. Updated some of the open issues with details from JimW's original mail in April 1999. Resolved scope vs relative URI references. Resolved issues about DAV:ascending (added to index) and the BNF for DAV:like (changed "octets" to "characters").

March 8, 2002

Updated reference to DeltaV (now RFC3253). Added Martin Wallmer's comments, moved JW5 into DAV:basicsearch section.

March 11, 2002

Closed open issues regaring the type of search arbiters (JW3) and their discovery (JW9). Rephrased requirements on multistatus response bodies (propstat only if properties were selected, removed requirement for responsedescription).

March 23, 2002

RFC2376 -> RFC3023. Added missing first names of authors. OPTIONS added to example for DAV:supported-method-set.

March 29, 2002

Abstract doesn't refer to DASL WG anymore.

April 7, 2002

Fixed section title (wrong property name supported-search-grammar-set. Changed DAV:casesensitve to "casesensitive" (it wasn't in the DAV: namespace after all).

May 28, 2002

Updated some issues with Jim Davis's comments.

June 10, 2002

Added proposal for different method for query schema discovery, not using pseudo-properties.

June 25, 2002

QSD marshalling rewritten. Added issue "isdefined-optional".

July 04, 2002

Added issue "scope-collection".

July 08, 2002

Closed issue "scope-collection".

August 12, 2002

Added issues "results-vs-binds" and "select-allprop".

October 22, 2002

Added issue "undefined-expressions".

November 18, 2002

Changed example host names (no change tracking).

November 25, 2002

Updated issue "DB2/DB7". Closed issues "undefined expressions", "isdefined-optional" and "select-allprop".

November 27, 2002

Added issues "undefined-properties", "like-exactlyone" and "like-wildcard-adjacent". Closed issue "query-on-href". Added acknowledgments section.

November 28, 2002

Closed issue "like-exactlyone". Added issue "mixed-content-properties".

December 14, 2002

Closed issues "undefined-properties", "results-vs-binds", "mixed-content-properties". Updated issue "like-wildcard-adjacent". Added informative reference to BIND draft. Updated reference to ACL draft.

January 9, 2003

Removed duplicate section on invalid scopes. Added comments to some open issues. Closed issues JW25/26, score-pseudo-property and null-ordering.

January 10, 2003

Issue limit-vs-ordering plus resolution. Closed issue JW17/JW24b.

January 14, 2003

New issue order-precedence. Started resolution of DB2/DB7.

January 15, 2003

Started spec of DAV:typed-literal.

January 17, 2003

Fix one DAV:like/DAV:getcontenttype example (add / to like expression, make case-insensitive).

January 28, 2003

Update issue(s) result-truncation, JW24d. Fixed response headers in OPTIONS example. Added issue qsd-optional. Closed issue(s) order-precedence, case-insensitivity-name.

February 07, 2003

Added issue scope-vs-versions. score-pseudo-property: allow DAV:orderby to explicitly specify DAV:score.

April 24, 2003

Fixed two "?" vs "_" issues (not updated in last draft).

June 13, 2003

Improve index.