- From: Jim Davis <jdavis@parc.xerox.com>
- Date: Sun, 14 Jun 1998 13:05:29 PDT
- To: www-webdav-dasl@w3.org
I have tried to get the current protocol draft from the internet drafts FTP
site without luck. ds.internic.net (referenced from the DASL home page at
http://www.ics.uci.edu/pub/ietf/dasl/) never seems to answer, and
ftp.isi.edu only has an old copy of the protocol.
Saveen: I think it would be good for the DASL web page to keep a local
copy of the relevant documents (IDs both submitted and still being edited)
in both Word and text, so we don't rely on the slow ISI FTP server.
For everyone else who might have tried, here is an UNOFFICIAL version of
the most recent version of the protocol draft, which I created myself from
a version in Word. I am sure Saveen has a better version, so please do not
consider this one in any way official (even less official than Internet
Drafts, that's very unofficial). It includes the changes I mentioned in
email earlier this weekend.
If you find this helpful, good. If not, please ignore it.
DAV Searching & Locating protocol UNOFFICIAL DRAFT
Saveen Reddy, Microsoft
Del Jensen, Novell
Surendra Reddy, Oracle
Rick Henderson, Netscape
Jim Davis, Xerox
Alan Babich, Filenet
May 3, 1998 Expires Nov 3, 1998
Created 14 June 1998 by Jim Davis from Word version 013. This
document is not an internet draft because it does not conform to the
syntax requirements for such a draft. I am providing it now only so
that those who cannot read Microsoft Word (which we have been using as
an internal editing format) can at least see a text version of the
draft we've been talking about.
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.
1. Introduction
This document describes a set of methods, headers and content-types
forming DASL, 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 DAV:searchrequest XML element, and the
DAV:simplesearch query grammar.
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.
1.1 Relationship to DAV
DASL relies on the resource and property model defined by
[WEBDAV]. DASL does not alter this model. Instead, DASL 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
The prototypical usage of DASL is the following series of steps.
1. The client issues the SEARCH method on a resource (the search
arbiter) and includes a text/xml entity that contains the query.
2. If the resource performs the query.
3. The resource responds with a text/xml entity that represents the
result set for the query.
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 only provides a framework for the transmission of a
search request. It does not define the syntax 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. The SEARCH method defines no relationship between the
Request-URI and the scope of the search. Such a relationship MUST be
defined by the query grammar. For example, query grammars may force
the request-URI to correspond exactly to the search scope.
2.3.2 The Request Body
The client MUST include a text/xml request body containing the
DAV:searchrequest XML element. The name of the contained XML element
identifies the query grammar being used and defines the criteria, the
result record, and any other details needed to perform the search.
2.4 The Response
2.4.1 217 Multistatus
The search proceeded successfully. The response matches that of a
PROPFIND. Each resource listed in the Multistatus response MUST meet
the criteria defined by the corresponding search request. The server
MAY limit the size of the response, for example because the query
might match more items than the server was willing to process. See
section 2.4.6.
2.4.2 400 Bad Request
The search query was unable to be processed. The search was not
initiated. The server MAY provide a text/xml body that describes the
cause for the error. The server MAY include the DAV:searchredirect XML
element to provide for redirection of the search to other search
arbiters.
2.4.3 422 Unprocessable entity
The query could not be processed. The DAV:searchrequest element may be
missing, may contain an unrecognized query grammar, or the query
itself may be malformed.
2.4.4 PROPFIND Response Extensions
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.4.5 Example
This example demonstrates the request and response framework.
>> Request
SEARCH / HTTP/1.1
Host: ryu.com
Content-Type: text/xml
Connection: Close
Content-Length: xxxxx
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:searchrequest>
<D:simplesearch>
... the query goes here ...
</D:simplesearch>
</D:searchrequest>
>> Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<?xml:namespace ns="http://www.foo.bar/propschema" prefix="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>
</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:response>
</D:multistatus>
2.4.6 Example of result set truncation
A server MAY limit the number of resources in a reply, for example to
limit the amount of resources expended in processing a query. If it
does so, the reply MUST include a response element whose href is that
of the request URI and whose status is 425.
SEARCH / HTTP/1.1
Host: gdr.com
Content-Type: text/xml
Connection: Close
Content-Length: xxxxx
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:searchrequest>
<D:simplesearch>
... the query goes here ...
</D:simplesearch>
</D:searchrequest>
>> Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxxx
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<D:multistatus>
<D:response>
<D:href>http://www.gdr.com/sounds/unbrokenchain.au</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://tech.mit.edu/archive96/photos/Lesh1.jpg</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
...
<D:response>
<D:href>http://gdr.com/</D:href>
<D:status>HTTP/1.1 425 Insufficient Space on Resource</D:status>
<D:responsedescription>Too many hits</D:responsedescription>
</D:response>
</D:multistatus>
3. The DAV:searchrequest XML Element
<!ELEMENT searchrequest (ANY) >
The value of DAV:searchrequest is a single element that defines the
query. The type of the query is identified by the element name. The
value of that element defines the query itself. For example, the
following XML document shows a simple natural language query. The type
of the query is FOO:natural-language query. The actual query is "Find
the locations of good Thai restaurants in Los Angeles".
<?xml version="1.0"?>
<?xml:namespace ns="DAV:" prefix="D"?>
<?xml:namespace ns="FOO:" prefix="F"?>
<D:searchrequest>
<F:natural-language-query>
Find the locations of good Thai restaurants in Los Angeles
</F:natural-language-query>
</D:searchrequest>
3.1 DAV:searchredirect
<!ELEMENT searchredirect ( scope arbiter* ) >
<!ELEMENT scope (#PCDATA) >
<!ELEMENT arbiter (#PCDATA) >
DAV:scope contains the URI identifying the scope. The optional
DAV:arbiter element contains a URI that identifies an arbiter that
will be able to handle the query for that scope. Multiple DAV:arbiter
elements can be used to show that multiple arbiters cans search on
that scope. If no DAV:arbiter appears then this indicate that the
scope cannot be searched by the search arbiter and that no the search
arbiter knows of no other arbiter to handle the query for the scope.
4. Discovery Mechanisms
4.1 Query Grammars
Servers MUST support discovery of the query grammars supported by a
resource. Clients can determine which query grammars are supported by
an arbiter by invoking OPTIONS on the search arbiter. If the resource
supports SEARCH, then the DASL response header will appear in the
response. The DASL response header lists which grammars are supported.
Consult the section on the OPTIONS method and the DASL response header
for more information.
4.2 Query Grammar Schema Discovery
Servers MAY support the discovery of the schema for a query grammar.
The DASL response header provides means for clients to discover the
set of query grammars supported by a resource. This alone is not
sufficient information for a client to generate a query. For example,
the DAV:simplesearch grammar defines a set of queries consisting of a
set of operators applied to a set of properties and values, but the
grammar itself does not specify which properties may be used in the
query. Moreover, while the DAV:simplesearch grammar defines a minimal
set of operators, it is possible that a resource might support
additional operators. Search schema discovery allows a client to
discover such information. The schema for a given query grammar on a
resource is stored as a property of that resource. The name of the
property is the same as the name of the query grammar itself. The
property value is a DAV:queryschema XML element. The contents of this
element depend upon the particular query grammar.
5. The OPTIONS Method
5.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.
5.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].
5.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.
5.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>
6. New Headers
6.1 The DASL Response Header
6.1.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.
6.1.2 Syntax
DASLHeader = "DASL" ":" URL-List
URL-List = 1#Coded-URL ; defined in section 8.5 of [WEBDAV]
6.1.3 Example
DASL: <http://foo.bar.com/syntax1> <http://akuma.com/syntax2>
7. The DAV:simplesearch grammar
7.1 Introduction
DAV:simplesarch 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.
DAV:simplesearch has several major components: DAV:select, DAV:from,
DAV:where, and DAV:sortby. DAV:select provides the result record
definition. DAV:from defines the scope. DAV:where defines the
criteria. DAV:sortby defines the sort order of the result set.
7.2 Typing
DAV:simplesearch uses [XML-DATA] a typing mechanism for literal values.
7.3 DTD
<!ELEMENT simplesearch (select, from, where?, sortby?, limit?) >
<!ELEMENT select (allprop | prop) >
<!ELEMENT from (scope+) >
<!ELEMENT scope (uri, depth?) >
<!ELEMENT where (and | or | not | eq | lt | gt
| lte | gte | contains | extension ) >
<!ELEMENT and ( (and | or | not | eq | lt | gt
| lte | gte | contains | extension) +) >
<!ELEMENT or ( (and | or | not | eq | lt | gt
| lte | gte | contains | extension) +) >
<!ELEMENT lt ( prop , literal ) >
<!ELEMENT lte ( prop , literal ) >
<!ELEMENT gt ( prop , literal) >
<!ELEMENT gte ( prop , literal ) >
<!ELEMENT eq ( prop , literal ) >
<!ELEMENT literal (#PCDATA)>
<!ELEMENT contains ( prop?, literal ) >
<!ELEMENT sortby (prop)*>
<!ELEMENT limit (nresults)
<!ELEMENT nresults (#PCDATA)7.3.1 Example
This query will retrieves the content length values for all resources
located under the server's "/container1/" URI namespace whose length
exceeds 10000.
<d:searchrequest>
<d:simplesearch>
<d:select>
<d:prop><d:getcontentlength/></d:prop>
</d:select>
<d:from>
<d:scope>
<d:href>/container1/</d:href>
<d:depth>infinity</d:depth>
</d:scope>
</d:from>
<d:where>
<d:gt>
<d:prop><d:getcontentlength/></d:prop>
<d:literal>10000</d:literal>
</d:gt>
</d:where>
<d:sortby>
<d:prop><d:getcontentlength/><d:prop>
</d:sortby>
</d:simplesearch>
</d:searchrequest>
7.4 DAV:select
DAV:select defines the result record. This document defines two
possible values: DAV:allprop and DAV:prop, both defined in [WEBDAV].
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 [WEBDAV].
7.5 DAV:from
DAV:from defines the query scope. This a list of one or more DAV:scope
elements. Each scope element contains a mandatory DAV:uri element and
an optional DAV:depth element. DAV:href indicates the URI for a
collection to use as a scope. DAV:depth has the value of "1" or
"infinity" indicating non-recursive and recursive searching of a
scope, respectively.
7.5.1 Relationship to the Request URI
For each absolute URI in a DAV:scope element, the scope is exactly
that URI For each relative URI in a DAV:scope element, the scope is
taken to be relative to the request-URI.
7.6 DAV:where
DAV:where defines the criteria for inclusion in the result set. The
value of this element is a XML element that defines a search operator
that evaluates to True, False, or Unknown. The search operator
contained by DAV:where may itself contain and evaluate additional
search operators. Each search operator defined for use in the where
clause MUST evaluate True, False, or Unknown. If and only if the
criteria evaluate to True for a resource, then the resource is
included as a member of the result set.
7.6.1 Example
The example shows a single operator (DAV:eq) applied in the criteria.
<D:where>
<D:eq>
<d:prop> <d:getcontenlength/> </d:prop>
<d:literal> 100 </d:literal>
</D:eq>
</D:where>
7.6.2
7.6.2 Example
The example shows a more complex operation involving several operators
(DAV:and, DAV:eq, DAV:gt) applied in the criteria. This DAV:where
expression matches those resources that are "image/gifs" over 4K in
size. <D:where> <D:and> <D:eq> <D:prop> <D:getcontenttype/> </D:prop>
<D:literal> image/gif </D:literal> </D:eq> <D:gt> <D:prop>
<D:getcontentlength/> </D:prop> <D:literal> 4096 </D:literal> </D:gt>
</D:and> </D:where>
7.7 DAV:sortby
DAV:sortby specifies the ordering of the result set. This contains a
list of properties for each resource in the result set upon which to
sort
7.8 DAV:and
The DAV:and operator performs a logical AND operation on the
expressions it contains.
7.9 DAV:or
The DAV:or operator performs a logical OR operation on the values it
contains. The DAV:casesensitive attribute may be used with this
element.
7.10 DAV:not
The DAV:not operator performs a logical NOT operation on the values it
contains. The DAV:casesensitive attribute may be used with this
element.
7.11 DAV:eq
The DAV:eq operator provides simple equality matching on property
values. The DAV:casesensitive attribute may be used with this
element.
7.12 DAV:lt, DAV:lte, DAV:gt, DAV:gte
The DAV:lt, DAV:lte, DAV:gt, and DAV:gte operators provide comparisons
on property values. For string values the comparison is
case-sensitive. The DAV:casesensitive attribute may be used with this
element.
7.13 DAV:contains
The DAV:contains operator provides a content-based comparisons on
property values or the text-content of a resource. If a DAV:prop is
given, then the operation applies to the single property named by
DAV:prop. Otherwise, the operation applies to text content of the
resource. The DAV:casesensitive attribute may be used with this
element.
7.13.1 Example
The example below matches those text resources that contain the phrase
"playoff hockey".
<D:contains>
<D:literal>playoff hockey</D:literal>
</D:contains>
7.13.2 Example
The example below matches those text resources where the foo:author
property contains the word "Orr" with case-sensitivity enabled.
<D:contains d:cassensitive="t">
<D:prop><foo:author/></D:prop>
<D:literal>Orr</D:literal>
</D:contains>
7.14 DAV:literal
DAV:literal allows typed, literal values to be placed in an
expression. Typing is specified through [XMLDATA]. If no typing is
specified, then the type string defined by [XMLDATA] is assumed.
7.15
7.15 DAV:limit
Name: limit
Namespace: DAV
Purpose: Contains requested limits from the client to limit the size
of the reply or amount of effort expended by the server.
Description:
<!ELEMENT limit (nresults)
7.15.1 DAV:nresults
Name: nresults
Namespace: DAV
Purpose: Contains a requested maximum number of records to be
returned in a reply. The server MAY disregard this limit.
Description: Contains an integer
<!ELEMENT nresults (#PCDATA) ;only digits
7.16 XML Attributes
7.16.1 DAV:casesensitive
The DAV:casesensitive attribute allows clients to specify
case-sensitive or case-insensitive behavior for DAV:simplesearch
operators. Operators used in DAV:extension MAY also use this
attribute to indicate case-sensitive behavior. The possible values
for DAV:casesensitive are "t" or "f". The "t" value indicates
case-sensitivity. The "f" value indicates case-insensitivity.
7.17 Properties
7.17.1 DAV:rank
<!ELEMENT rank EMPTY>
The rank XML element is a pseudo property whose value is defined only
in the context of a query result where the server computes a ranking,
e.g. based on relevance.
7.18 Query Schema for DAV:simplesearch
<!ELEMENT simplesearchschema (searchable selectable sortable operators)>
<!ELEMENT searchable (propdesc)*>
<!ELEMENT selectable (prop)*>
<!ELEMENT sortable (rank|prop|allprop)*>
<!ELEMENT operators (opdesc)*>
<!ELEMENT propdesc (prop (datatype)? (indexed)? (equivalents)?>
<!ELEMENT indexed EMPTY>
<!ELEMENT equivalents (prop)*>
<!ELEMENT opdesc op arglist>
<!ELEMENT arglist (argdesc*)>
<!ELEMENT argdesc datatype (prop)*>
7.19 Internationalized Content
All literal strings in the query are encoded in XML and take on the
character set of the text/xml document containing the literal. If the
character set of the text/xml request cannot be understood, then the
server MUST respond with a 400 (Bad Request).
8. 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.
9. Authentication
Authentication mechanisms defined in WEBDAV will also apply to DASL.
10. IANA Considerations
This document uses the namespace defined by [WEBDAV] for XML
elements. All other IANA considerations mentioned in [WEBDAV] also
applicable to DASL.
11. 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
- Added sortby, datatyping, three valued logic, query schema property, and
element definitions for schema for simplesearch.
April 8
- made changes based on last week's DASL BOF.
May 8
- Removed most of DAV:searcherror; converted to DAV:searchredirect
- Altered DAV:simplesearch grammar to use avoid use of ANY in DTD
June 12 (Jim Davis)
* added result set truncation and limit tag
* Removed elements DAV already defined (e.g. depth)
* Typo: allprops -> allprop
* Got rid of extension
* updated references to DASLREQ and WEBDAV
* updated date in header to match date on title
12. References
[DASLREQ] S. Reddy, J.Slein, "Requirements for DAV Searching and
Locating", March 1998, internet-draft, work-in-progress,
draft-reddy-dasl-requirements-02.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",
April. 1998, internet-draft, work-in-progress,
draft-ietf-webdav-protocol-08.
[XMLDATA] A. Layman, E. Jung, E. Maler, H.S. Thompson, J. Paoli,
J. Tiguw, N.H. Mikula, S. De Rose, "XML-DATA", Jan, 1998,
work-in-progress, http://www.w3.org/TR/1998/NOTE-XML-data/
13. 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 PARC
3333 Coyote Hill Road
Palo Alto CA 94304
650-812-4301
Email: jdavis@parc.xerox.com
Alan Babich
Filenet
Email: ababich@filenet.com
Received on Sunday, 14 June 1998 16:08:06 UTC