Web Distributed Authoring and Versioning (WebDAV) SEARCH
Extracted elements (29)
ANSI standard three-valued logic (as in SQL) is used when evaluating the search condition to handle properties that have no value (NULL) or undefined expressions. A property not defined on a resource is NULL; NULL values are 'less than' all other values in comparisons. This aligns with widely-practiced SQL semantics.
The DAV:is-collection operator is provided as a specific shortcut for testing whether a resource's DAV:resourcetype contains DAV:collection, instead of defining generic structure queries. Generic structure queries were considered too powerful to standardize at that time.
This specification defines elements and properties in the 'DAV:' XML namespace, which is normally reserved for IETF working group specifications. An exception was made because WebDAV SEARCH originated in the IETF DASL working group and had significant deployment before the working group closed.
DASL-extended servers MUST accept the DAV:basicsearch grammar and MAY accept other grammars. Servers MUST support DAV:basicsearch as the mandatory grammar for WebDAV SEARCH.
DASL servers MUST include the DASL header in the OPTIONS response. If a resource supports the SEARCH method, the server MUST list SEARCH in the Allow header. Servers supporting RFC 3253 and/or RFC 3744 MUST also report SEARCH in DAV:supported-method-set and support the DAV:supported-query-grammar-set live property.
Each operator in the DAV:where clause MUST evaluate to TRUE, FALSE, or UNKNOWN using three-valued logic. A resource is included in the result set if and only if the search condition evaluates to TRUE. If a query contains an unsupported operator, the server MUST respond with 422 (Unprocessable Entity).
If a PROPFIND for a property value would yield a non-2xx response, that property is considered NULL. NULL values are 'less than' all other values in comparisons. Empty strings (zero length) are not NULL and are 'less than' strings of non-zero length.
Query grammar URIs are used only as identifiers. Applications SHOULD NOT attempt to retrieve these URIs even if they appear to be retrievable (e.g., those beginning with 'http://'), to avoid unintended network requests.
Servers MUST support discovery of the query grammars supported by a search arbiter resource. If the resource supports SEARCH, the DASL response header will appear in the OPTIONS response listing supported grammars.
The results of a SEARCH method SHOULD NOT be cached. Each matching resource's DAV:response MUST include a DAV:propstat element, and the DAV:href element contains the URI of the resource.
The server MUST emit an entity matching the WebDAV multistatus format (RFC 4918, Section 13) in response to a SEARCH request. If the server returns 207 (Multistatus), the response MUST include one DAV:response for each resource matching the search criteria.
The server MUST process a text/xml or application/xml request body, and MAY process request bodies in other formats. If a body is present, it MUST be either a DAV:searchrequest or a DAV:query-schema-discovery XML element.
When a server truncates the result set, the reply MUST use status code 207, return a DAV:multistatus response body, and indicate a status of 507 (Insufficient Storage) for the search arbiter URI. If partial results are included and the client requested an ordered result set, any partial results MUST be ordered as the client directed.
DAV:contains is an optional operator for content-based full-text search against a resource's content (not properties). It evaluates to TRUE if the content satisfies the search phrase. Servers MAY apply stemming, phonetics, thesaurus expansion, case-insensitive matching, or other NLP techniques at their discretion.
DAV:from defines the query scope via one or more DAV:scope elements, each containing a mandatory DAV:href and DAV:depth ("0", "1", or "infinity"). An optional DAV:include-versions child element extends scope to include all versions of version-controlled resources. Support for multiple scope elements is optional.
DAV:like is an optional wildcard pattern-matching operator. The pattern uses '_' to match exactly one character and '%' to match zero or more characters, with '\' as escape. Patterns are Unicode code points typically encoded in UTF-8 or UTF-16 in the XML document.
DAV:limit contains DAV:nresults (an unsigned integer) requesting a maximum number of DAV:response elements returned. The server MAY disregard this limit. If both DAV:limit and DAV:orderby are used, results SHOULD be those that order highest.
DAV:literal allows literal string values in expressions. White space in literal values is significant. When compared with DAV:getcontentlength, the literal SHOULD be treated as an unsigned integer; when compared with DAV:creationdate or DAV:getlastmodified, it SHOULD be treated as an ISO-8601 date value.
DAV:typed-literal (optional) forces typed comparison using the xsi:type attribute from XML Schema. The server MUST reject an unknown type with 422 (Unprocessable Entity) and SHOULD reject if the value cannot be cast to the specified type. If the property value cannot be cast, the comparison evaluates to UNKNOWN.
The 'caseless' XML attribute (values 'yes' or 'no', default server-specified) allows clients to specify case-insensitive matching for comparison and ordering operators in DAV:basicsearch. Caseless matching SHOULD follow Unicode Standard Section 5.18. Support is optional; a server should respond with 422 if it cannot support the attribute.
The DASL response header identifies server support for query grammars in the OPTIONS response. Its value is a comma-separated list of angle-bracket-enclosed URIs indicating supported grammar types (e.g., DASL: <DAV:basicsearch>). The ABNF is: DASLHeader = "DASL" ":" 1#Coded-URL.
The DAV:basicsearch grammar has five components defined by XML elements: DAV:select (result record definition), DAV:from (search scope with depth), DAV:where (search criteria with Boolean operators), DAV:orderby (sort specification), and DAV:limit (constraint on result size). The DTD root is: <!ELEMENT basicsearch (select, from, where?, orderby?, limit?)>.
The DAV:score element is added to the DAV:response element to indicate relevance scoring for DAV:contains results. Its value is an integer from 0 to 10000 inclusive, with higher values indicating higher relevance. Scores are only meaningful within a single query result and should not be compared across different queries.
The DAV:supported-query-grammar-set is a protected WebDAV live property required for servers supporting RFC 3253 or RFC 3744. It identifies XML-based query grammars supported by the search arbiter resource, represented as a list of DAV:supported-query-grammar elements each containing a grammar element.
The Query Schema Discovery (QSD) mechanism allows clients to retrieve the schema for a specific query grammar on a given arbiter and scope by issuing a SEARCH with a DAV:query-schema-discovery root element instead of DAV:searchrequest. The response is a DAV:multistatus with DAV:query-schema container elements holding grammar-specific schema descriptions.
The SEARCH method is a new HTTP method that clients invoke to initiate a server-side search. The request body defines the query; the server executes it and returns results. SEARCH is a safe method with no side effects beyond executing the query.
This document registers the 'DASL' HTTP response header field in the permanent HTTP header registry defined in RFC 3864. The header is applicable to the http protocol, has standard status, and is defined in Section 3.2 of this specification.
A query MUST NOT allow clients to retrieve information that wouldn't have been available through GET or PROPFIND. Query constraints on properties or content for which the client does not have read access MUST be evaluated as if the property did not exist or as if GET would return a 4xx status code, preventing information leakage via search.
Servers should prepare for denial-of-service attacks where a client issues a query with a large or expensive result set. XML external entities in SEARCH request bodies are untrustworthy and can modify the effective DTD or cause large numbers of outbound HTTP GETs, creating both security and scalability risks; implementations should treat them with caution.