WebDAV SEARCH

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

¹⁷ <ed:ins>2002-01-052002-01-05, julian.reschke@greenbytes.deFor WebDAV-compliant servers, it also defines a new live property DAV:supported-query-grammar-set.</ed:ins> ¶

¹⁸ 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].¶

²² <ed:issue>namespacechangeclosed<ed:item>2002-01-25julian.reschke@greenbytes.deAs this is an individual (non working group) submission, it should not use the DAV: namespace for any new elements. Need to collect feedback.</ed:item></ed:issue> <ed:ins>2002-01-052002-01-05, julian.reschke@greenbytes.deWhen 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.</ed:ins> ¶

²³ <ed:ins>2002-01-052002-02-28, julian.reschke@greenbytes.deNote 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.</ed:ins> ¶

²⁴ <ed:ins>2002-01-112002-01-05, julian.reschke@greenbytes.deSimilarily, 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.</ed:ins> ¶

²⁵ 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 <ed:ins>2002-02-282002-01-05, julian.reschke@greenbytes.deor application/xml</ed:ins>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 <ed:ins>2002-02-282002-02-28, julian.reschke@greenbytes.dean entity</ed:ins> <ed:del>2002-02-282002-02-28, julian.reschke@greenbytes.dea text/xml entity</ed:del> 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 <ed:ins>2002-02-282002-02-28, julian.reschke@greenbytes.dean entity</ed:ins> <ed:del>2002-02-282002-02-28, julian.reschke@greenbytes.detext/xml entity</ed:del> 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. <ed:ins>2002-02-032002-02-03, julian.reschke@greenbytes.deThe results of this method SHOULD NOT be cached.</ed:ins> ¶

³⁹ 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.¶

⁴⁰ 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 <ed:ins>2002-02-112002-02-11, julian.reschke@greenbytes.deelement (unless no property was selected)</ed:ins>.<ed:del>2002-02-112002-02-11, julian.reschke@greenbytes.deIt SHOULD contain a DAV:responsedescription.</ed:del> ¶

⁵² 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 <ed:ins>2002-02-182002-02-18, julian.reschke@greenbytes.deapplication/xml or</ed:ins>text/xml request entity was provided, then it may have been <ed:del>2002-02-182002-02-18, julian.reschke@greenbytes.devalid (</ed:del>well-formed<ed:del>2002-02-182002-02-18, julian.reschke@greenbytes.de)</ed:del> 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]

⁷⁶ <ed:issue>URI-vs-QNAMEchangeclosed<ed:item>2001-10-17julian.reschke@greenbytes.deHere, a grammar is represented as an URI. Later, a grammar is identified by a Qualified XML name (URI reference + local name). This means that the client needs to be aware of a mapping from a URI (that's reported here) to an XML element name (that it can use in a query). Proposal: report XML-based grammars through a different mechanism in SEARCH (details to be done).</ed:item></ed:issue> 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. <ed:ins>2002-01-052002-01-05, julian.reschke@greenbytes.deNote 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).</ed:ins> ¶

⁷⁷ This header MAY be repeated.¶

⁷⁸ For example:

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

⁸¹ This example shows that the server supports search on the /somefolder resource with the query grammars: DAV:basicsearch, http://foo.bar.com/syntax1 and http://akuma.com/syntax2. Note that every server MUST support DAV:basicsearch.¶

⁸² >> Request:

OPTIONS /somefolder HTTP/1.1
Host: ryu.com

⁸³ >> Response:

HTTP/1.1 200 OK
Date: Tue, 20 Jan 1998 20:52:29 GMT
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE,
       MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH
DASL: <DAV:basicsearch>
DASL: <http://foo.bar.com/syntax1> 
DASL: <http://akuma.com/syntax2>

⁹⁸ 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 others 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].¶

¹⁰⁸ If the value is DAV:allprop, the result record for a given resource includes all the properties for that resource.¶

¹⁰⁹ If the value is DAV:prop, then the result record for a given resource includes only those properties named by the DAV:prop element. Each property named by the DAV:prop element must be referenced in the Multistatus response.¶

¹¹⁰ The rules governing the status codes for each property match those of the PROPFIND method defined in [RFC2518].¶

¹¹¹ DAV:from defines the query scope. This contains exactly one DAV:scope element. <ed:del>2002-02-182002-02-18, julian.reschke@greenbytes.deThe scope element contains a mandatory DAV:href element and an optional DAV:depth element.</ed:del> <ed:ins>2002-02-182002-02-18, julian.reschke@greenbytes.deThe scope element contains mandatory DAV:href and DAV:depth elements.</ed:ins> ¶

¹¹² DAV:href indicates the URI for a collection 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.¶

¹²¹ 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 (<ed:ins>2002-02-202002-02-20, julian.reschke@greenbytes.deas in [SQL99]</ed:ins><ed:del>2002-02-202002-02-20, julian.reschke@greenbytes.deas in ANSI standard SQL, [ANSISQL]</ed:del>).¶

¹³⁸ 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 DAV:casesensitive 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 DAV:casesensitive attribute may be used with these elements.¶

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

¹⁴⁵ <ed:del>2002-03-032002-03-03, julian.reschke@greenbytes.deBecause white space in literal values is significant in comparisons, DAV:literal makes use of the xml:space attribute to identify this significance. The default value of this attribute for DAV:literal is "preserve". Consult section 2.10 of [XML] for more information on the use of this attribute.</ed:del> <ed:ins>2002-03-032002-03-03, julian.reschke@greenbytes.deWhite 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.</ed:ins> ¶

¹⁴⁹ The DAV:isdefined 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.¶

¹⁵¹ The DAV:isdefined operator is optional.¶

¹⁵² 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:score property is intended to be useful to rank documents satisfying the DAV:contains operator.¶

¹⁶⁹ 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 records to be returned in a reply. The server MAY disregard this limit. The value of this element is an integer.¶

¹⁷¹ <ed:issue>case-insensitivity-nameopen<ed:item>2002-01-09julian.reschke@greenbytes.deThe attribute probably should be renamed to "caseless".</ed:item></ed:issue> The DAV:casesensitive attribute allows clients to specify case-sensitive or case-insensitive behavior for DAV:basicsearch operators.¶

¹⁷² The possible values for DAV:casesensitive are "1" or "0". The "1" value indicates case-sensitivity. The "0" value indicates case-insensitivity. The default value is server-specified. <ed:ins>2002-01-092002-01-09, julian.reschke@greenbytes.deCase-insensitivity SHOULD implemented using caseless matching as defined in [CaseMap].</ed:ins> ¶

¹⁷³ Support for the DAV:casesensitive is optional. A server should respond with an error 422 if the DAV:casesensitive attribute is used but cannot be supported.¶

¹⁷⁴ The DAV:score XML element is a synthetic property whose value is defined only in the context of a query result where the server computes a score, e.g. based on relevance. It may be used in DAV:select or DAV:orderby elements. Servers SHOULD support this property. The value is a string representing the score, an integer from zero to 10000 inclusive, where a higher value indicates a higher score (e.g. more relevant).¶

¹⁷⁵ Clients should note that, in general, it is not meaningful to compare the numeric values of scores from two different query results unless both were executed by the same underlying search system on the same collection of resources.¶

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.