INTERNET-DRAFT Saveen Reddy, Microsoft draft-reddy-dasl-protocol-00.txt Del Jensen, Novell Mar, 1998 Surendra Reddy, Oracle Expires Aug, 1998 Rick Henderson, Netscape Jim Davis, Xerox Alan Babich, Filenet DAV Searching and Locating Status of this Memo This document is an Internet draft. Internet drafts are working documents of the Internet Engineering Task Force (IETF), its areas and its working groups. Note that other groups may also distribute working information as Internet drafts. Internet Drafts are draft documents valid for a maximum of six months and can 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 as other than as "work in progress". To learn the current status of any Internet draft please check the "lid- abstracts.txt" listing contained in the Internet drafts shadow directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East coast) or ftp.isi.edu (US West coast). Further information about the IETF can be found at URL: http://www.ietf.org/ Distribution of this document is unlimited. Please send comments to the Distributed Authoring and Versioning (WEBDAV) working group at <www- webdav-dasl @w3.org>, which may be joined by sending a message with subject "subscribe" to <www-webdav-dasl- @w3.org>. Discussions of the WEBDAV working group are archived at <URL:http://www.w3.org/pub/WWW/Archives/Public/www-webdav-dasl>. Abstract This document specifies a set of methods, headers, and content-types composing DASL, an application of the HTTP/1.1 protocol to efficiently search for DAV resources based upon a set of client-supplied criteria. INTERNET DRAFT DAV Searching and Locating 1 DAV Searching and Locating March 1997 Table of Contents 1 Introduction........................................................4 1.1 Relationship to DAV...............................................4 1.2 Terms.............................................................4 1.3 Notational Conventions............................................4 1.4 DASL in Operation.................................................4 2 The SEARCH Method...................................................5 2.1 Overview..........................................................5 2.2 Query Transport vs. Query Semantics and Query Grammar.............5 2.3 The Request.......................................................5 2.3.1 The Request-URI as Search Arbiter.............................5 2.3.2 The Request Body..............................................5 2.4 The Response......................................................5 2.5 Response Extensions...............................................5 2.6 Example...........................................................6 2.7 The searchrequest XML Elements....................................7 2.7.1 searchrequest XML Element.....................................7 2.7.2 type XML Element..............................................7 2.7.3 query XML Element.............................................7 3 Search Grammar Discovery : OPTIONS..................................8 3.1 Overview..........................................................8 3.2 Request...........................................................8 3.3 Response..........................................................8 3.4 Example...........................................................8 4 The DASL Response Header............................................9 4.1 Overview..........................................................9 4.2 Syntax............................................................9 4.3 Example...........................................................9 5 The DASL simplesearch grammar......................................10 5.1 Introduction.....................................................10 5.2 The Basic Query..................................................10 5.3 Example..........................................................10 5.4 The select XML Element...........................................11 5.4.1 Access to properties.........................................11 5.5 The from XML element.............................................11 5.6 The where XML Element............................................12 5.6.1 Overview.....................................................12 5.6.2 Syntax.......................................................12 5.7 The Comparison Operators.........................................13 5.8 The Contains XML Element.........................................13 5.8.1 Example......................................................13 5.9 Example..........................................................13 5.10 Typing..........................................................14 5.11 Variants........................................................14 5.12 Versioning......................................................14 5.13 Security Considerations.........................................14 5.14 Authentication..................................................14 5.15 Internationalized Content.......................................14 5.16 IANA Considerations.............................................15 6 Change History.....................................................16 INTERNET DRAFT DAV Searching and Locating 2 DAV Searching and Locating March 1997 7 References.........................................................17 8 Author's Addresses.................................................18 INTERNET DRAFT DAV Searching and Locating 3 DAV Searching and Locating March 1997 1 Introduction This document is an early sketch of the DAV Searching and Locating (DASL) protocol. This document does not imply endorsement by the authors for the protocol described. This is a "strawman" for the purposes of discussion. It will describe a set of methods, headers and content-types forming an application of HTTP/1.1 that allows clients to perform searching operations on the properties and content of DAV resources. DASL is a lightweight search protocol to transport queries and result sets and allows clients to make use of server-side search facilities, the motivation for which is described by [DASLREQ]. DASL includes the SEARCH method, the DASL response header for use with the OPTIONS method, the searchrequest XML entity, and the simplesearch query grammar. 1.1 Relationship to DAV DASL relies on the resource and property model defined by [WEBDAV]. DASL does not alter this model, but rather allows clients to access DAV-modeled resources through server-side search. 1.2 Terms This draft uses the terms defined in [RFC2068], [WEBDAV], and [DASLREQ]. 1.3 Notational Conventions The augmented BNF used by this document to describe protocol elements is exactly the same as the one described in Section 2.1 of [RFC2068]. Because this augmented BNF uses the basic production rules provided in Section 2.2 of [RFC2068], 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]. 1.4 DASL in Operation As an application of HTTP/1.1, DASL follows the HTTP/1.1 request/response chain. A client invokes the SEARCH method and includes a text/xml entity containing a query. The server responds with a text/xml entity that contains the corresponding result set. It is an objective of DASL to minimize the complexity of clients so as to facilitate widespread deployment of applications capable of utilizing the DASL search mechanisms. INTERNET DRAFT DAV Searching and Locating 4 DAV Searching and Locating March 1997 2 The SEARCH Method 2.1 Overview The client invokes the SEARCH method to initiate a server-side search. The text/xml body of the request defines the query. A successful response is a text/xml entity matching the [WEBDAV] PROPFIND response. 2.2 Query Transport vs. Query Semantics and Query Grammar The SEARCH method provides a framework for the transmission of a search request. It does not define the grammar or semantics of any query that is transmitted. That is, the SEARCH method is a transport mechanism for the query. Different query grammars can be transmitted, each defining its own search semantics. 2.3 The Request The client invokes the SEARCH method on the resource named by the Request- URI. 2.3.1 The Request-URI as Search Arbiter The Request-URI identifies a resource that acts as an arbiter for the search. This resource is the one performing the search but not necessarily the resource that is being searched. That is, there is no implicit relationship between the Request-URI and the search scope. Query grammars MUST explicitly define the relationship between the search scope and the request-URI. Query grammars may, for example, make the request-URI correspond exactly to the search scope. 2.3.2 The Request Body The client MUST include a text/xml request body containing the searchrequest XML element. The searchrequest XML element identifies the query grammar being used and defines the criteria, the result record, and any other attributes for the search. 2.4 The Response If successful, the server MUST respond with a 217 Multistatus response matching that of PROPFIND. Each resource listed in the Multistatus response MUST meet the criteria defined by the corresponding search request. 2.5 Response Extensions INTERNET DRAFT DAV Searching and Locating 5 DAV Searching and Locating March 1997 Query grammars MUST define how the response matches the PROPFIND response. Responses are free to include more information than PROPFIND responses so long as the extra information does not invalidate the PROPFIND response. 2.6 Example This example demonstrates a simple query and its response. The query requests a recursive search of the entire server. No criteria are given in the query, so every resource specified in the scope matches the criteria. In this example, only a single resource exists on the server. The response uses the same format as the PROPFIND result. >> Request SEARCH / HTTP/1.1 Host: ryu.com Content-Type: text/xml Connection: Close Content-Length: xxxxx <?xml version="1.0"?> <?xml:namespace name="DAV:" as="D"?> <D:searchrequest> <D:type> <D:href> DAV:simplesearch </D:href> </D:type> <D:query> </D:query> </D:searchrequest> >> Response HTTP/1.1 207 Multi-Status Content-Type: text/xml Content-Length: xxxxx <?xml version="1.0"?> <?xml:namespace name="DAV:" as="D"?> <?xml:namespace name="FOO:" as="R"?> <D:multistatus> <D:response> <D:href>http://ryu.com/whales.txt</D:href> <D:propstat> <D:prop> <R:bigbox> <R:BoxType>Box type A</R:BoxType> INTERNET DRAFT DAV Searching and Locating 6 DAV Searching and Locating March 1997 </R:bigbox> <R:author> <R:Name>J.J. Dingleheimerschmidt</R:Name> </R:author> <D:resourcetype/> <D:getcontentlength>259</D:getcontentlength> <D:getcontenttype>text/plain<D:getcontenttype> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> <D:propstat> </D:multistatus> 2.7 The searchrequest XML Elements The namespace for all DASL XML elements is "DAV:" 2.7.1 searchrequest XML Element Name: searchrequest Namespace: DAV: Purpose: Encapsulates the entire search request <!ELEMENT searchrequest (type query) > 2.7.2 type XML Element Name: type Namespace: DAV: Purpose: Provides a URI which identifies the query grammar Value: href ; see section 11.3 of [WebDAV] <!ELEMENT type (href) > <!ELEMENT href (#PCDATA) > 2.7.3 query XML Element Name: query Namespace: DAV: Purpose: A string of the grammar identified by the type XML element which defines the criterion and attributes for the search. Parent:searchrequest <!ELEMENT query (ANY) > INTERNET DRAFT DAV Searching and Locating 7 DAV Searching and Locating March 1997 3 Search Grammar Discovery : OPTIONS 3.1 Overview 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. 3.2 Request The client issues the OPTIONS method against a resource named by the Request-URI. This is a normal invocation of OPTIONS defined in [RFC2068]. 3.3 Response If a resource supports the SEARCH method, then the server MUST list SEARCH in the OPTIONS response as defined by [RFC2068]. DASL servers MUST include the DASL header in the OPTIONS response. This header identifies the search grammars supported by that resource. 3.4 Example This example shows that the server supports search on the /somefolder resource with the following query grammars: http://foo.bar.com/syntax1 and http://akuma.com/syntax2. >> Request OPTIONS /somefolder HTTP/1.1 Connection: Close Host: ryu.com >> Response HTTP/1.1 200 OK Date: Tue, 20 Jan 1998 20:52:29 GMT Connection: close Accept-Ranges: none Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH DASL: <http://foo.bar.com/syntax1> <http://akuma.com/syntax2> INTERNET DRAFT DAV Searching and Locating 8 DAV Searching and Locating March 1997 4 The DASL Response Header 4.1 Overview The DASL response header indicates server support for query grammars in the OPTIONS method. The value of this header is a list of URLs. Each URL indicates support for a query grammar. 4.2 Syntax DASLHeader = "DASL" ":" URL-List URL-List = 1#Coded-URL ; defined in section 8.5 of [WEBDAV] 4.3 Example DASL: <http://foo.bar.com/syntax1> <http://akuma.com/syntax2> INTERNET DRAFT DAV Searching and Locating 9 DAV Searching and Locating March 1997 5 The DASL simplesearch grammar 5.1 Introduction The simplesearch grammar is a query language that allows clients to express search requests that are generally useful for WEBDAV scenarios. DASL-extended servers MUST accept this grammar. The following URI identifies the simplesearch grammar. It is to be used in the Type XML Element. DAV:simplesearch 5.2 The Basic Query The simplesearch query grammar is an XML-based syntax that has several components, each an XML element, that defines the query. The select XML element defines the result record. That is, it specifies the properties that will appear in the search result. The from XML element defines the scope of the query. The where XML element defines the criteria for a resource to contribute to the search result. 5.3 Example This query will recursively retrieve the content length values for all resources located under the server's "/container1/" URI namespace whose length exceeds 10000. <d:searchrequest> <d:select> <d:props> <d:getcontentlength/> </d:props> </d:select> <d:from> <d:scopelist> <d:scope> <d:uri>/container1/</d:uri> <d:depth>infinite</d:depth> </d:scope> </d:scopelist> </d:from> <d:where> <d:expr> <d:term> <d:gt> <d:value> INTERNET DRAFT DAV Searching and Locating 10 DAV Searching and Locating March 1997 <d:prop><d:getcontentlength/></d:prop> </d:value> <d:value> <d:literal>10000</d:literal> </d:value> </d:gt> </d:term> </d:expr> </d:where> </d:searchrequest> 5.4 The select XML Element Name: select Namespace: DAV: Purpose: Defines the result record. <!ELEMENT select (allprops | props) > <!ELEMENT props (ANY+) > <!ELEMENT allprops > If the allprops element is present, then all properties defined on matching resources to which the user has access should be listed in the result record. If the prop element is present, then it will name all properties to include in the result record. Each property named by the props element must be referenced in the Multistatus response for the search method. The rules governing the status codes for each property match those of the PROPFIND method defined in [WEBDAV]. 5.4.1 Access to properties The select element clause allows any property defined by DAV to be included in the result set. 5.5 The from XML element Name: from, scopelist, scope, depth, uri Namespace: DAV: Purpose: Defines the search scope. <!ELEMENT from (scopelist) > <!ELEMENT scopelist (scope+) > <!ELEMENT scope (depth? , uri) > <!ELEMENT depth > <!ELEMENT uri > The from element defines the scope of the search. INTERNET DRAFT DAV Searching and Locating 11 DAV Searching and Locating March 1997 The scopelist element contains a list of scopes to search. The scope element defines the collection to search through the uri element and the depth of the search through the depth element. The values for depth are "1" or "infinite". 5.6 The where XML Element 5.6.1 Overview The where element defines the search criteria, an expression that is evaluated against the each resource contained in the search scope. A resource is only included in the result set if the expression evaluates to true. Clients should be prepared for restrictions on what can be reasonably searched. For example, servers may not be able to provide searches on live-properties whose values are determined dynamically. Additionally, servers may not be able to perform searches that involve arithmetic comparisons. When such restrictions affect a search, servers SHOULD provide the proper status codes in the multistatus response. The WHERE clause supports the typical joining of search terms through the "AND" and "OR" operators. Each search term defines a condition or criterion for a resource property. 5.6.2 Syntax Name: where, expr, and, or, not Namespace: DAV: Purpose: Defines the search criteria. <!ELEMENT where (expr) > <!ELEMENT expr (term | and | or | not) > <!ELEMENT and (expr+) > <!ELEMENT or (expr+) > <!ELEMENT not (expr) > <!ELEMENT term ( lt | lte | eq | neq | gt | gte | contains ) > <!ELEMENT lt (value , value) > <!ELEMENT lte (value , value) > <!ELEMENT eq (value , value) > <!ELEMENT neq (value , value) > <!ELEMENT gt (value , value) > <!ELEMENT gte (value , value) > <!ELEMENT contains (prop? , phrase) > <!ELEMENT value (prop, literal) > INTERNET DRAFT DAV Searching and Locating 12 DAV Searching and Locating March 1997 <!ELEMENT prop ANY > <!ELEMENT literal (#PCDATA) > <!ELEMENT phrase (#PCDATA)> 5.7 The Comparison Operators The lt, lte, eq, neq, gt, and gte elements allow comparisons between values. If two values cannot be compared, then the result of a comparison operator is Unknown. 5.8 The Contains XML Element The contains operator allows content-based matching for text resource and allows for additional matching of properties that store string values. The contains operator attempts to find a single word or phrase in a resource's text content or property. This is done without regard to case. The search is sensitive to the order of words in a phrase. If a property name is included in the contains element, then the matching is done for that property only. If no property is specified, then the matching is done for the text content of the entire resource. 5.8.1 Example Targets text resources that contain the phrase "telecommunications industry". <term> <contains> <value> <literal>telecommunications industry</literal> </value> </contains> </term> 5.9 Example Targets documents where the foo:author property contains the word "Smith". <term> <contains> <prop> <foo:author/> </prop> <value> <literal>Smith</literal> </value> </contains> INTERNET DRAFT DAV Searching and Locating 13 DAV Searching and Locating March 1997 </term> 5.10 Typing When property values are typed, then those types should influence any comparisons performed in the WHERE clause. Servers SHOULD indicate when the query failed because of typing. When a type for a property is unknown, the server SHOULD treat the property as plain text. For example properties with arbitrary XML values to be searched as plain-text strings. 5.11 Variants If a server supports resource variants, then the server SHOULD expose those variants through the simplesearch queries. Variants in terms of the query are resources that share the same URI but differ with respect to DAV-properties. For example, the /index.html resource may be available in the content type of "text/plain" or "text/html." Searches that match both resources should include those variants in the response. It is up to the client to define the proper result record, if variants of this sort are to be found. If a server received a query whose criteria match multiple variants of a single resource, then the server SHOULD return records for those variants in the result set. 5.12 Versioning TBD. 5.13 Security Considerations This section is provided to detail issues concerning security implications of which DASL applications need to be aware. All of the security consideration of HTTP/1.1 also apply to DASL. In addition, this section will include security risks inherent in searching and retrieval of resource properties and content. 5.14 Authentication Authentication mechanisms defined in WEBDAV will also apply to DASL. 5.15 Internationalized Content All string values in the query are assumed to be in the character set used by the containing XML document. If the XML document uses a character set not understood by the server, then the server MUST respond with 400 (Bad Request). INTERNET DRAFT DAV Searching and Locating 14 DAV Searching and Locating March 1997 5.16 IANA Considerations This document uses the namespace defined by [WEBDAV] for XML elements. All other IANA considerations mentioned in [WEBDAV] also applicable to DASL. INTERNET DRAFT DAV Searching and Locating 15 DAV Searching and Locating March 1997 6 Change History Feb, 14 - Initial Draft Feb, 28 - 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 - 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 - Accepted all changes from Jim Davis. Added use of HREF element and fixed the DTD, other corrections. INTERNET DRAFT DAV Searching and Locating 16 DAV Searching and Locating March 1997 7 References [DASLREQ] S. Reddy, J.Slein, "Requirements for DAV Searching and Locating", February 1998, internet-draft, work-in-progress, draft-reddy- dasl-requirements-01.txt [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. Berners- Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, U.C. Irvine, DEC, MIT/LCS, January 1997. [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1997. [WEBDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D.Jenson, "Extensions for Distributed Authoring on the World Wide Web", October, 1997, internet-draft, work-in-progress, draft-ietf-webdav-protocol-06. INTERNET DRAFT DAV Searching and Locating 17 DAV Searching and Locating March 1997 8 Author's Addresses Saveen Reddy Microsoft One Microsoft Way Redmond WA, 9085-6933 Email: saveenr@microsoft.com Del Jensen Novell 1555 N. Technology Way M/S ORM F111 Orem, UT 84097-2399 Email: dcjensen@novell.com Surendra Reddy Oracle Corporation 600 Oracle Parkway, M/S 6op3, Redwoodshores, CA 94065 Email: skreddy@us.oracle.com Phone:(650) 506 5441 Rick Henderson Netscape Email: rickh@netscape.com Jim Davis Xerox Email: jdavis@parc.xerox.com Alan Babich Filenet Email: ababich@filenet.com Expires Aug, 1998 INTERNET DRAFT DAV Searching and Locating 18 DAV Searching and Locating March 1997 INTERNET DRAFT DAV Searching and Locating 19