idnits 2.17.1 draft-reddy-dasl-protocol-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-28) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == There are 3 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 29 longer pages, the longest (page 22) being 70 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 114 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1048 has weird spacing: '... The prope...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: 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, with a query whose DAV:select element includes the DAV:queryschema property. This property is defined only in the context of such a search, a server SHOULD not treat it as defined in the context of a PROPFIND on the scope. The content of this property 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. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: Query grammars are identified by URIs. Applications SHOULD not attempt to retrieve these URIs even if they appear to be retrievable (for example, those that begin with "http://") -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 28, 1998) is 9375 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'WEBDAV' is mentioned on line 445, but not defined -- No information found for draft-reddy-dasl-requirements - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'DASLREQ' ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) == Outdated reference: A later version (-10) exists of draft-ietf-webdav-protocol-08 Summary: 9 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Saveen Reddy, Microsoft 3 draft-reddy-dasl-protocol-02.txt Del Jensen, Novell 4 Surendra Reddy, Oracle 5 Rick Henderson, Netscape 6 Jim Davis, Xerox 7 Alan Babich, Filenet 9 Expires Jan 28, 1999 July 28, 1998 11 DAV Searching & Locating 13 Status of this Memo 15 This document is an Internet draft. Internet drafts are working 16 documents of the Internet Engineering Task Force (IETF), its areas 17 and its working groups. Note that other groups may also distribute 18 working information as Internet drafts. 20 Internet Drafts are draft documents valid for a maximum of six 21 months and can be updated, replaced or obsoleted by other documents 22 at any time. It is inappropriate to use Internet drafts as 23 reference material or to cite them as other than as "work in 24 progress". 26 To learn the current status of any Internet draft please check the 27 "lid-abstracts.txt" listing contained in the Internet drafts shadow 28 directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 29 munnari.oz.au (Pacific Rim), ftp.isi.edu (US East coast) or 30 ftp.isi.edu (US West coast). Further information about the IETF 31 can be found at URL: http://www.ietf.org/ 33 Distribution of this document is unlimited. Please send comments 34 to the mailing list at , which may be 35 joined by sending a message with subject "subscribe" to . 38 Discussions of the list are archived at 39 . 41 Abstract 43 This document specifies a set of methods, headers, and content- 44 types composing DASL, an application of the HTTP/1.1 protocol to 45 efficiently search for DAV resources based upon a set of client- 46 supplied criteria. 48 Table of Contents 50 DAV SEARCHING & LOCATING..................................1 52 TABLE OF CONTENTS.........................................2 54 1. INTRODUCTION..........................................4 55 1.1. DASL................................................4 56 1.2. Relationship to DAV.................................4 57 1.3. Terms...............................................4 58 1.4. Notational Conventions..............................4 59 1.5. An Overview of DASL at Work.........................5 61 2. THE SEARCH METHOD.....................................5 62 2.1. Overview............................................5 63 2.2. The Request.........................................5 64 2.2.1.The Request-URI...................................5 65 2.2.2.The Request Body..................................5 66 2.3. The DAV:searchrequest XML Element...................6 67 2.4. The Successful 207 (Multistatus) Response...........6 68 2.4.1.Etxending the PROPFIND Response...................6 69 2.4.2.Example: A Simple Request and Response............6 70 2.5. Unsuccessful Responses..............................7 71 2.5.1.Example: Result Set Truncation....................8 73 3. DISCOVERY OF SUPPORTED QUERY GRAMMARS.................9 74 3.1. The OPTIONS Method..................................9 75 3.2. The DASL Response Header............................9 76 3.3. Example: Grammar Discovery..........................9 78 4. QUERY SCHEMA DISCOVERY: QSD..........................10 79 4.1. The DAV:queryschema Property.......................11 80 4.1.1.Example of query schema discovery................11 82 5. THE DAV:SIMPLESEARCH GRAMMAR.........................12 83 5.1. Introduction.......................................12 84 5.2. The DAV:simplesearch DTD...........................12 85 5.2.1.Example query....................................13 86 5.3. DAV:select.........................................14 87 5.4. DAV:from...........................................14 88 5.4.1.Relationship to the Request-URI..................14 89 5.4.2.Scope............................................14 90 5.5. DAV:where..........................................15 91 5.5.1.Use of Three-Valued Logic in Queries.............15 92 5.5.2.Handling Optional operators......................15 93 5.5.3.Treatment of NULL Values.........................16 94 5.5.4.Example: Testing for Equality....................16 95 5.5.5.Example: Relative Comparisons....................16 96 5.6. DAV:sortby.........................................16 97 5.6.1.Comparing Natural Language Strings...............17 98 5.6.2.Example of Sorting...............................17 99 5.7. Boolean Operators: DAV:and, DAV:or, and DAV:not....17 100 5.8. DAV:eq.............................................18 101 5.9. DAV:lt, DAV:lte, DAV:gt, DAV:gte...................18 102 5.10.DAV:literal........................................18 103 5.11.DAV:isnull.........................................18 104 5.12.DAV:like...........................................18 105 5.12.1. Syntax for the Literal Pattern................18 106 5.12.2. Example of DAV:like...........................19 107 5.13.DAV:contentpassthrough.............................19 108 5.14.The DAV:limit XML Element..........................19 109 5.15.The DAV:nresults XML Element.......................19 110 5.16.The DAV:casesensitive XML attribute................20 111 5.17.The DAV:score Property.............................20 112 5.18.The DAV:iscollection Property......................20 113 5.18.1. Exampe of DAV:iscollection....................21 114 5.19.Query Schema for DAV:simplesearch..................21 115 5.19.1. DTD for DAV:simplesearch QSD..................21 116 5.19.2. DAV:propdesc Element..........................21 117 5.19.3. The DAV:datatype Property Description.........22 118 5.19.4. The DAV:searchable Property Description.......22 119 5.19.5. The DAV:selectable Property Description.......22 120 5.19.6. The DAV:sortable Property Description.........23 121 5.19.7. The DAV:operators XML Element.................23 122 5.19.8. Example of Query Schema for DAV:simplesearch..23 124 6. INTERNATIONALIZATION CONSIDERATIONS..................24 126 7. SECURITY CONSIDERATIONS..............................24 128 8. SCALABILITY..........................................24 130 9. AUTHENTICATION.......................................24 132 10. IANA CONSIDERATIONS................................25 134 11. COPYRIGHT..........................................25 136 12. INTELLECTUAL PROPERTY..............................25 138 13. REFERENCES.........................................25 140 14. AUTHOR'S ADDRESSES.................................25 142 15. APPENDICES.........................................26 143 Appendix A Three-Valued Logic in DAV:simplesearch......26 144 Appendix B Change History..............................27 145 Feb 14, 1998............................................27 146 Feb 28, 1998............................................27 147 Mar 9, 1998.............................................28 148 Mar 11, 1998............................................28 149 April 8, 1998...........................................28 150 May 8, 1998.............................................28 151 June 17, 1998...........................................28 152 June 23, 1998...........................................28 153 Jul 20, 1998............................................28 154 July 28, 1998...........................................28 155 July 28, 1998...........................................29 157 1. INTRODUCTION 159 1.1. DASL 161 This document defines DAV Searching & Locating (DASL), an 162 application of HTTP/1.1 forming a lightweight search protocol to 163 transport queries and result sets and allows clients to make use of 164 server-side search facilities. [DASLREQ] describes the motivation 165 for DASL. 167 DASL will minimize the complexity of clients so as to facilitate 168 widespread deployment of applications capable of utilizing the DASL 169 search mechanisms. 171 DASL consists of: 173 - the SEARCH method, 175 - the DASL response header, 177 - the DAV:searchrequest XML element, 179 - the DAV:queryschema property, 181 - the DAV:simplesearch XML element and query grammar, and 183 - the DAV:simplesearchschema XML element. 185 1.2. Relationship to DAV 187 DASL relies on the resource and property model defined by [WebDAV]. 188 DASL does not alter this model. Instead, DASL allows clients to 189 access DAV-modeled resources through server-side search. 191 1.3. Terms 193 This draft uses the terms defined in [RFC2068], [WebDAV], and 194 [DASLREQ]. 196 1.4. Notational Conventions 198 The augmented BNF used by this document to describe protocol 199 elements is exactly the same as the one described in Section 2.1 of 200 [RFC2068]. Because this augmented BNF uses the basic production 201 rules provided in Section 2.2 of [RFC2068], those rules apply to 202 this document as well. 204 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 205 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 206 this document are to be interpreted as described in [RFC2119]. 208 1.5. An Overview of DASL at Work 210 One can express the basic usage of DASL in the following steps: 212 - The client constructs a query using the DAV:simplesearch grammar. 214 - The client invokes the SEARCH method on a resource that will 215 perform the search (the search arbiter) and includes a text/xml 216 request entity that contains the query. 218 - The search arbiter performs the query. "#". 220 - The search arbiter sends the results of the query back to the 221 client in the response. The server MUST send a text/xml entity 222 that matches the [WebDAV] PROPFIND response. 224 2. THE SEARCH METHOD 226 2.1. Overview 228 The client invokes the SEARCH method to initiate a server-side 229 search. The body of the request defines the query. The server 230 MUST emit text/xml entity matching the [WebDAV] PROPFIND response. 232 The SEARCH method plays the role of transport mechanism for the 233 query and the result set. It does not define the semantics of the 234 query. The type of the query defines the semantics. 236 2.2. The Request 238 The client invokes the SEARCH method on the resource named by the 239 Request-URI. 241 2.2.1. The Request-URI 243 The Request-URI identifies the search arbiter. 245 The SEARCH method per se defines no relationship between the 246 arbiter and the scope of the search, rather the particular query 247 grammar used in the query defines the relationship. For example, 248 the FOO query grammar may force the request-URI to correspond 249 exactly to the search scope. 251 2.2.2. The Request Body 253 The server MUST process a text/xml request body, and MAY process 254 request bodies in other formats. 256 If the client sends a text/xml body, it MUST include the 257 DAV:searchrequest XML element. The DAV:searchrequest XML element 258 identifies the query grammar, defines the criteria, the result 259 record, and any other details needed to perform the search. 261 2.3. The DAV:searchrequest XML Element 263 265 The DAV:searchrequest XML element contains a single XML element 266 that defines the query. The name of the query element defines the 267 type of the query. The value of that element defines the query 268 itself. 270 2.4. The Successful 207 (Multistatus) Response 272 If the server returns 207 (Multistatus), then the search proceeded 273 successfully and the response MUST match that of a PROPFIND. 275 There MUST be one DAV:response for each resource that matched the 276 search criteria. For each such response, the DAV:href element 277 contains the URI of the resource, and the response MUST include a 278 DAV:propstat element. 280 In addition, the server MAY include DAV:response items in the reply 281 where the DAV:href element contains a URI that is not a matching 282 resource, e.g. that of a scope or the query arbiter. Each such 283 response item MUST NOT contain a DAV:propstat element, and MUST 284 contain a DAV:status. It SHOULD contain a DAV:responsedescription. 286 2.4.1. Etxending the PROPFIND Response 288 A response MAY include more information than PROPFIND defines so 289 long as the extra information does not invalidate the PROPFIND 290 response. Query grammars SHOULD define how the response matches 291 the PROPFIND response. 293 2.4.2. Example: A Simple Request and Response 295 This example demonstrates the request and response framework. The 296 following XML document shows a simple (hypothetical) natural 297 language query. The name of the query element is FOO:natural- 298 language-query, thus the type of the query is FOO:natural-language- 299 query. The actual query is "Find the locations of good Thai 300 restaurants in Los Angeles". For this hypothetical query, the 301 arbiter returns two properties for each selected resource. 303 SEARCH / HTTP/1.1 304 Host: ryu.com 305 Content-Type: text/xml 306 Connection: Close 307 Content-Length: 243 308 309 310 311 312 313 Find the locations of good Thai restaurants in Los Angeles 314 315 317 >> Response 319 HTTP/1.1 207 Multi-Status 320 Content-Type: text/xml 321 Content-Length: 333 323 324 325 326 327 328 http://siamiam.com 329 330 331 259 W. Hollywood 332 4 333 334 335 336 338 2.5. Unsuccessful Responses 340 If an error occurred that prevented execution of the query, the 341 server MUST indicate the failure with the appropriate status code 342 and SHOULD include a DAV:multistatus element to point out errors 343 associated with scopes. 345 - 400 Bad Request. The query could not be executed. The request may 346 be malformed (not valid XML for example). 348 - 422 Unprocessable entity. The query could not be executed. If a 349 text/xml request entity was provided, then it may have been valid 350 (well-formed) but may have contained an unsupported query 351 operator. 353 - 425 Insufficient Space on Resource. The query produced more 354 results than the server was willing to transmit. Partial results 355 have been transmitted. The server MUST send a body that matches 356 that for 207, except that there MAY exist resources that matched 357 the search criteria for which no corresponding DAV:response 358 exists in the reply. 360 2.5.1. Example: Result Set Truncation 362 A server MAY limit the number of resources in a reply, for example 363 to limit the amount of resources expended in processing a query. 364 If it does so, the reply MUST use status code 425. It SHOULD 365 include the partial results. 367 SEARCH / HTTP/1.1 368 Host: gdr.com 369 Content-Type: text/xml 370 Connection: Close 371 Content-Length: xxxxx 373 374 375 376 377 � the query goes here � 378 379 381 >> Response 383 HTTP/1.1 425 Insufficient Space on Resource 384 Content-Type: text/xml 385 Content-Length: 738 387 388 389 390 391 http://www.gdr.com/sounds/unbrokenchain.au 392 393 394 HTTP/1.1 200 OK 395 396 397 399 http://tech.mit.edu/archive96/photos/Lesh1.jpg 400 401 402 HTTP/1.1 200 OK 403 404 405 406 http://gdr.com 407 HTTP/1.1 425 Insufficient Space on 408 Resource 409 410 Only first two matching records were returned 411 412 413 415 3. DISCOVERY OF SUPPORTED QUERY GRAMMARS 417 Servers MUST support discovery of the query grammars supported by a 418 resource. 420 Clients can determine which query grammars are supported by an 421 arbiter by invoking OPTIONS on the search arbiter. If the resource 422 supports SEARCH, then the DASL response header will appear in the 423 response. The DASL response header lists the supported grammars. 425 3.1. The OPTIONS Method 427 The OPTIONS method allows the client to discover if a resource 428 supports the SEARCH method and to determine the list of search 429 grammars supported for that resource. 431 The client issues the OPTIONS method against a resource named by 432 the Request-URI. This is a normal invocation of OPTIONS defined in 433 [RFC2068]. 435 If a resource supports the SEARCH method, then the server MUST list 436 SEARCH in the OPTIONS response as defined by [RFC2068]. 438 DASL servers MUST include the DASL header in the OPTIONS response. 439 This header identifies the search grammars supported by that 440 resource. 442 3.2. The DASL Response Header 444 DASLHeader = "DASL" ":" Coded-URL ; defined in section 8.4 of 445 [WEBDAV] 447 The DASL response header indicates server support for a query 448 grammar in the OPTIONS method. The value is a URI that indicates 449 the type of grammar. This header MAY be repeated 451 For example: 453 DASL: 454 DASL: 455 DASL: 457 3.3. Example: Grammar Discovery 459 This example shows that the server supports search on the 460 /somefolder resource with the following query grammars: 461 http://foo.bar.com/syntax1 and http://akuma.com/syntax2. 463 >> Request 465 OPTIONS /somefolder HTTP/1.1 466 Connection: Close 467 Host: ryu.com 469 >> Response 470 HTTP/1.1 200 OK 471 Date: Tue, 20 Jan 1998 20:52:29 GMT 472 Connection: close 473 Accept-Ranges: none 474 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 475 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH 476 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 477 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH 478 DASL: 479 DASL: 481 4. QUERY SCHEMA DISCOVERY: QSD 483 Servers MAY support the discovery of the schema for a query 484 grammar. 486 The DASL response header provides means for clients to discover the 487 set of query grammars supported by a resource. This alone is not 488 sufficient information for a client to generate a query. For 489 example, the DAV:simplesearch grammar defines a set of queries 490 consisting of a set of operators applied to a set of properties and 491 values, but the grammar itself does not specify which properties 492 may be used in the query. QSD for the DAV:simplesearch grammar 493 allows a client to discover the set of properties that are 494 searchable, selectable, and sortable. Moreover, although the 495 DAV:simplesearch grammar defines a minimal set of operators, it is 496 possible that a resource might support additional operators in a 497 query. QSD allows a client to discover these operators and their 498 syntax. The set of discoverable quantities will differ from 499 grammar to grammar, but each grammar can define a means for a 500 client to discover what can be discovered. 502 In general, the schema for a given query grammar depends on both 503 the resource (the arbiter) and the scope. A given resource might 504 have access to one set of properties for one potential scope, and 505 another set for a different scope. For example, consider a server 506 able to search two distinct collections, one holding cooking 507 recipes, the other design documents for nuclear weapons. While 508 both collections might support properties such as author, title, 509 and date, the first might also define properties such as calories 510 and preparation time, while the second defined properties such as 511 yield and applicable patents. Two distinct arbiters indexing the 512 same collection might also have access to different properties. 513 For example, the recipe collection mentioned above might also 514 indexed by a value-added server that also stored the names of chefs 515 who had tested the recipe. Note also that the available query 516 schema might also depend on other factors, such as the identity of 517 the principal conducting the search, but these factors are not 518 exposed in this protocol. 520 Each query grammar supported by DASL defines its own syntax for 521 expressing the possible query schema. A client retrieves the schema 522 for a given query grammar on an arbiter resource with a given scope 523 by invoking the SEARCH method on that arbiter, with that grammar 524 and scope, with a query whose DAV:select element includes the 525 DAV:queryschema property. This property is defined only in the 526 context of such a search, a server SHOULD not treat it as defined 527 in the context of a PROPFIND on the scope. The content of this 528 property is an XML element whose name and syntax depend upon the 529 grammar, and whose value may (and likely will) vary depending upon 530 the grammar, arbiter, and scope. 532 The query schema for DAV:simplesearch is defined in section 5.19. 534 4.1. The DAV:queryschema Property 536 538 4.1.1. Example of query schema discovery 540 In this example, the arbiter is recipes.com, the grammar is 541 DAV:simplesearch, the scope is also recipes.com. 543 SEARCH / HTTP/1.1 544 Host: recipes.com 545 Content-Type: application/xml 546 Connection: Close 547 Content-Length: 257 549 550 551 552 553 554 555 557 http://recipes.com 559 560 562 Response: 564 HTTP/1.1 207 Multistatus 565 Content-Type: application/xml 566 Content-Length: 428 568 569 570 571 572 http://recipes.com 573 574 575 576 577 See section 5.19.8 for actual contents 578 580 581 582 HTTP/1.1 200 Okay 583 584 585 587 5. THE DAV:SIMPLESEARCH GRAMMAR 589 5.1. Introduction 591 DAV:simplesearch uses an extensible XML syntax that allows clients 592 to express search requests that are generally useful for WebDAV 593 scenarios. DASL-extended servers MUST accept this grammar, and MAY 594 accept others grammars. 596 DAV:simplesearch has several major components: DAV:select, 597 DAV:from, DAV:where, DAV:sortby, and DAV:limit. DAV:select 598 provides the result record definition. DAV:from defines the scope. 599 DAV:where defines the criteria. DAV:sortby defines the sort order 600 of the result set. DAV:limit provides constraints on the query as 601 a whole. 603 5.2. The DAV:simplesearch DTD 605 607 609 610 612 615 619 623 627 628 630 631 634 635 637 638 641 642 644 646 647 648 650 651 654 655 657 658 660 5.2.1. Example Query 662 This query retrieves the content length values for all resources 663 located under the server's "/container1/" URI namespace whose 664 length exceeds 10000. 666 667 668 669 670 671 672 673 /container1/ 674 infinity 675 676 677 678 679 680 10000 681 682 683 684 685 686 687 688 689 690 692 5.3. DAV:select 694 DAV:select defines the result record. This document defines two 695 possible values: DAV:allprop and DAV:prop, both defined in 696 [WebDAV]. 698 If the value is DAV:allprop, the result record for a given resource 699 includes all the properties for that resource. 701 If the value is DAV:prop, then the result record for a given 702 resource includes only those properties named by the DAV:prop 703 element. Each property named by the DAV:prop element must be 704 referenced in the Multistatus response. 706 The rules governing the status codes for each property match those 707 of the PROPFIND method defined in [WebDAV]. 709 5.4. DAV:from 711 DAV:from defines the query scope. This contains exactly one 712 DAV:scope element. The scope element contains a mandatory DAV:href 713 element and an optional DAV:depth element. 715 DAV:href indicates the URI for a collection to use as a scope. 717 When the scope is a collection, if DAV:depth is "1", the search 718 includes the members of the collection. When it is "infinity", the 719 search includes all recursive members of the collection.8.5.1. 721 5.4.1. Relationship to the Request-URI 723 If the DAV:scope element is an absolute URI, the scope is exactly 724 that URI. 726 If the DAV:scope element is a relative URI, the scope is taken to 727 be relative to the request-URI. 729 5.4.2. Scope 731 A Scope can be an arbitrary URI. 733 Servers, of course, may support only particular scopes. This may 734 include limitations for particular schemes such as "http:" or 735 "ftp:" or certain URI namespaces. 737 If a scope is given that is not supported the server MUST respond 738 with a 400 status code that includes a Multistatus error. A scope 739 in the query appears as a resource in the response and must include 740 an appropriate status code indicating its validity with respect to 741 the search arbiter. 743 Example: 745 HTTP/1.1 400 Multi-Status 746 Content-Type: text/xml 747 Content-Length: 428 749 750 751 752 753 http://www.foo.com/scope1 754 HTTP/1.1 502 Bad Gateway 755 757 758 760 This example shows the response if there is a scope error. The 761 response provides a Multistatus with a status for the scope. In 762 this case, the scope cannot be reached because the server cannot 763 search another server (502). 765 5.5. DAV:where 767 The DAV:where element defines the search condition for inclusion of 768 resources in the result set. The value of this element is an XML 769 element that defines a search operator that evaluates to one of the 770 Boolean truth values TRUE, FALSE, or UNKNOWN. The search operator 771 contained by DAV:where may itself contain and evaluate additional 772 search operators as operands, which in turn may contain and 773 evaluate additional search operators as operands, etc. recursively. 775 5.5.1. Use of Three-Valued Logic in Queries 777 Each operator defined for use in the where clause that returns a 778 Boolean value MUST evaluate to TRUE, FALSE, or UNKNOWN. The 779 resource under scan is included as a member of the result set if 780 and only if the search condition evaluates to TRUE. 782 Consult Appendix A for details on the application of three-valued 783 logic in query expressions. 785 5.5.2. Handling Optional operators 787 If a query provides an operator that is not supported by the 788 server, then the server MUST respond with a 422 (Unprocessable 789 Entity) status code. 791 5.5.3. Treatment of NULL Values 793 A NULL value for a property identifies the following conditions: 795 - The property is not defined on a resource. 797 - The property is not set on a resource. 799 - The value of the property is UNKNOWN. 801 - Security policies prevent the retrieval of the property's value. 803 NULL values are "less than" all other values in comparisons. 805 Empty strings (zero length strings) are not NULL values. An empty 806 string is "less then" a string with length greater than zero. 808 The DAV:isnull operator is defined to test if the value of a 809 property is NULL. 811 5.5.4. Example: Testing for Equality 813 The example shows a single operator (DAV:eq) applied in the 814 criteria. 816 817 818 819 100 820 821 823 5.5.5. Example: Relative Comparisons 825 The example shows a more complex operation involving several 826 operators (DAV:and, DAV:eq, DAV:gt) applied in the criteria. This 827 DAV:where expression matches those resources that are "image/gifs" 828 over 4K in size. 830 831 832 833 834 image/gif 835 836 837 838 4096 839 840 841 843 5.6. DAV:sortby 845 The DAV:sortby element specifies the ordering of the result set. 846 It contains one or more DAV:order elements, each of which specifies 847 a comparison between two items in the result set. Informally, a 848 comparison specifies a test that determines whether one resource 849 appears before another in the result set. Comparisons are applied 850 in the order they occur in the DAV:sortby element, earlier 851 comparisons being more significant. 853 The comparisons defined here use only a single property from each 854 resource, compared using the same ordering as the DAV:lt operator 855 (ascending) or DAV:gt operator (descending). If neither direction 856 is specified, the default is DAV:ascending. 858 In the context of the DAV:sortby element, null values are 859 considered to collate before any actual (i.e., non null) value, 860 including strings of zero length (as in ANSI standard SQL, c.f., 861 ANSI X3.135-1992). 863 5.6.1. Comparing Natural Language Strings. 865 Comparisons on strings take into account the language defined for 866 that property. Clients MAY specify the language using the xml:lang 867 attribute. If no language is specified either by the client or 868 defined for that property by the server or if a comparison is 869 performed on strings of two different languages, the results are 870 undefined. 872 The DAV:casesensitive attribute may be used to indicate case- 873 sensitivity for comparisons. 875 5.6.2. Example of Sorting 877 This sort orders first by last name of the author, and then by 878 size, in descending order, so that the briefest works appear first. 880 881 882 883 884 885 886 887 888 889 891 5.7. Boolean Operators: DAV:and, DAV:or, and DAV:not 893 The DAV:and operator performs a logical AND operation on the 894 expressions it contains. 896 The DAV:or operator performs a logical OR operation on the values 897 it contains. 899 The DAV:not operator performs a logical NOT operation on the values 900 it contains. 902 5.8. DAV:eq 904 The DAV:eq operator provides simple equality matching on property 905 values. 907 The DAV:casesensitive attribute may be used with this element. 909 5.9. DAV:lt, DAV:lte, DAV:gt, DAV:gte 911 The DAV:lt, DAV:lte, DAV:gt, and DAV:gte operators provide 912 comparisons on property values. The DAV:casesensitive attribute 913 may be used with these elements. 915 5.10. DAV:literal 917 DAV:literal allows literal values to be placed in an expression. 919 5.11. DAV:isnull 921 The DAV:isnull operator allows clients to determine whether a 922 property exists on a resource. The DAV:isnull operator is TRUE if 923 and only if a PROPFIND response for the property on that resource 924 would return the 403 (Forbidden) or 404 (Not Found) status code. 926 Example: 928 929 930 932 5.12. DAV:like 934 The DAV:like is an optional operator intended to give simple 935 wildcard-based pattern matching ability to clients. 937 The operator takes two arguments. 939 The first argument is a DAV:prop element identifying a single 940 property to evaluate. 942 The second argument is a DAV:literal element that gives the pattern 943 matching string. 945 5.12.1. Syntax for the Literal Pattern 947 Pattern := [wildcard] 0*( text [wildcard] ) 948 wildcard := exactlyone | zeroormore 949 text := 1*( | escapesequence ) 950 exactlyone : = "?" 951 zeroormore := "%" 952 escapechar := "\" 953 escapesequence := "\" ( exactlyone | zeroormore | escapechar ) 954 The value for the literal is composed of wildcards separated by 955 segments of text. Wildcards may begin or end the literal. Wildcards 956 may not be adjacent. 958 The "?" wildcard matches exactly one character. 960 The "%" wildcard matches zero or more characters 962 The "\" character is an escape sequence so that the literal can 963 include "?" and "%". To include the "\" character in the pattern, 964 the escape sequence "\\" is used.. 966 5.12.2. Example of DAV:like 968 This example shows how a client might use DAV:like to identify 969 those resources whose content type was a subtype of image. 971 972 973 image% 974 976 5.13. DAV:contentpassthrough 978 The DAV:contentpassthrough operator provides an "escape mechanism" 979 for accessing content-based comparisons of a resource. The content 980 is server specific, hence not interoperable. This operator is 981 optional. 983 Rationale: While it is the intent of the authors to define a set 984 of interoperable operators for content based query, (still to be 985 designed), we also recognize that advanced content retrieval 986 systems will likely have features inappropriate for this protocol, 987 and so we wish to provide means whereby as much of a query as 988 possible can be standardized while still allowing access to these 989 features. We hope that the ungainly name of this operator will 990 convey the sense that it is to be used only as a last resort. We 991 hope that we will be able to define a set of interoperable 992 operators sufficient for nearly all the common cases of content 993 based search. 995 5.14. The DAV:limit XML Element 997 999 The DAV:limit XML element contains requested limits from the client 1000 to limit the size of the reply or amount of effort expended by the 1001 server. 1003 5.15. The DAV:nresults XML Element 1005 ;only digits 1006 The DAV:nresults XML element contains a requested maximum number of 1007 records to be returned in a reply. The server MAY disregard this 1008 limit. The value of this element is an integer. 1010 5.16. The DAV:casesensitive XML attribute 1012 The DAV:casesensitive attribute allows clients to specify case- 1013 sensitive or case-insensitive behavior for DAV:simplesearch 1014 operators. 1016 The possible values for DAV:casesensitive are "1" or "0". The "1" 1017 value indicates case-sensitivity. The "0" value indicates case- 1018 insensitivity. The default value is server-specified. 1020 Support for the DAV:casesensitive is optional. A server should 1021 respond with an error 422 if the DAV:casesensitive attribute is 1022 used but cannot be supported. 1024 5.17. The DAV:score Property 1026 1028 The DAV:score XML element is a synthetic property whose value is 1029 defined only in the context of a query result where the server 1030 computes a score, e.g. based on relevance. It may be used in 1031 DAV:select or DAV:sortby elements. Servers SHOULD support this 1032 property. The value is a string representing the score, an integer 1033 from zero to 10000 inclusive, where a higher value indicates a 1034 higher score (e.g. more relevant). 1036 Clients should note that, in general, it is not meaningful to 1037 compare the numeric values of scores from two different queries 1038 unless both were executed by the same underlying search system on 1039 the same collection of resources. 1041 5.18. The DAV:iscollection Property 1043 1045 The DAV:iscollection XML element is a synthetic property whose 1046 value is defined only in the context of a query. 1048 The property is TRUE (the literal string "1") of a resource if and 1049 only if a PROPFIND of the DAV:resourcetype property for that 1050 resource would contain the DAV:collection XML element. The property 1051 is FALSE (the literal string "0") otherwise. 1053 Rationale: This property is provided in lieu of defining generic 1054 structure queries, which would suffice for this and for many more 1055 powerful queries, but seems inappropriate to standardize at this 1056 time. 1058 5.18.1. Exampe of DAV:iscollection 1060 This example shows a search criterion that picks out all and only 1061 the resources in the scope that are collections. 1063 1064 1065 1066 1 1067 1068 1070 5.19. 1071 Query Schema for DAV:simplesearch 1073 The DAV:simplesearch grammar defines a search criteria that is a 1074 Boolean-valued expression, and allows for an arbitrary set of 1075 properties to be included in the result record. The result set may 1076 be sorted on a set of property values. Accordingly the DTD for 1077 schema discovery for this grammar allows the server to express: 1079 @ the set of properties that may be either searched, returned, or 1080 used to sort, and a hint about the data type of such properties 1082 @ the set of optional operators defined by the resource. 1084 5.19.1. DTD for DAV:simplesearch QSD 1086 1087 1088 1089 1090 1091 1092 1094 The DAV:properties element holds a list of descriptions of 1095 properties. 1097 The DAV:operators element describes the optional operators that may 1098 be used in a DAV:where element. 1100 5.19.2. DAV:propdesc Element 1102 Each instance of a DAV:propdesc element describes the property or 1103 properties in the DAV:prop element it contains. All subsequent 1104 elements are descriptions that apply to those properties. All 1105 descriptions are optional and may appear in any order. Servers 1106 SHOULD support all the descriptions defined here, and MAY define 1107 others. 1109 DASL defines four descriptions. The first, DAV:datatype, provides 1110 a hint about the type of the property value, and may be useful to a 1111 user interface prompting for a value. The remaining three 1112 (DAV:searchable, DAV:selectable, and DAV:sortable) identify 1113 portions of the query (DAV:where, DAV:select, and DAV:sortby, 1114 respectively). If a property has a description for a section, then 1115 the server MUST allow the property to be used in that section. 1116 These descriptions are optional. If a property does not have such a 1117 description, or is not described at all, then the server MAY still 1118 allow the property to be used in the corresponding section. 1120 5.19.3. The DAV:datatype Property Description 1122 The DAV:datatype element contains a single XML element that 1123 provides a hint about the domain of the property, which may be 1124 useful to a user interface prompting for a value to be used in a 1125 query. The namespace for expressing a DASL defined data type is 1126 "urn:uuid:C2F41010-65B3-11d1-A29F-00AA00C14882/". 1128 1130 DASL defines the following data type elements: 1132 name contents example 1134 Boolean 1 1135 0 1137 string Foobar 1139 int -259 1140 23 1142 float .314159265358979E+1 1143 5.33 1145 dateTime.iso86 1994-11-05T08:15:5Z 1146 01tz 1148 If the data type of a property is not given, then the data type 1149 defaults to string. 1151 5.19.4. The DAV:searchable Property Description 1153 1155 If this element is present, then the server MUST allow this 1156 property to appear within a DAV:where element where an operator 1157 allows a property. Allowing a search does not mean that the 1158 property is guaranteed to be defined on every resource in the 1159 scope, it only indicates the server's willingness to check. 1161 5.19.5. The DAV:selectable Property Description 1163 1165 This element indicates that the property may appear in the 1166 DAV:select element. 1168 5.19.6. The DAV:sortable Property Description 1170 This element indicates that the property may appear in the 1171 DAV:sortby element 1173 1175 5.19.7. The DAV:operators XML Element 1177 The DAV:operators element describes every optional operator 1178 supported in a query. (Mandatory operators are not listed since 1179 they are mandatory and permit no variation in syntax.). All 1180 optional operators that are supported MUST be listed in the 1181 DAV:operators element. The listing for an operator consists of the 1182 operator (as an empty element), followed by one element for each 1183 operand. The operand MUST be either DAV:operand_property or 1184 DAV:operand_literal, which indicate that the operand in the 1185 corresponding position is a property or a literal value, 1186 respectively. If an operator is polymorphic (allows more than one 1187 operand syntax) then each permitted syntax MUST be listed 1188 separately. 1190 1193 5.19.8. Example of Query Schema for DAV:simplesearch 1195 1196 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1218 1220 1221 1222 This response lists four properties. The datatype of the last 1223 three properties is not given, so it defaults to string. All are 1224 selectable, and the first three may be searched. All but the last 1225 may be used in a sort. Of the optional DAV operators, DAV:isnull 1226 and DAV:like are supported. 1228 Note: The schema discovery defined here does not provide for 1229 discovery of supported values of the DAV:casesensitive attribute. 1230 This may require that the reply also list the mandatory operators. 1232 6. INTERNATIONALIZATION CONSIDERATIONS 1234 Clients have the opportunity to tag properties when they are stored 1235 in a language. The server SHOULD read this language-tagging by 1236 examining the xml:lang attribute on any properties stored on a 1237 resource. 1239 The xml:lang attribute specifies a nationalized collation sequence 1240 when properties are compared. 1242 Comparisons when this attribute differs have undefined order. 1244 7. SECURITY CONSIDERATIONS 1246 This section is provided to detail issues concerning security 1247 implications of which DASL applications need to be aware. All of 1248 the security considerations of HTTP/1.1 also apply to DASL. In 1249 addition, this section will include security risks inherent in 1250 searching and retrieval of resource properties and content. 1252 A query must not allow one to retrieve information about values or 1253 existence of properties that one could not obtain via PROPFIND. 1254 (e.g. by use in DAV:sortby, or in expressions on properties.) 1256 Server should prepare for denial of service attacks. For example a 1257 client may issue a query for which the result set is expensive to 1258 calculate or transmit because many resources match or must be 1259 evaluated. 1261 8. SCALABILITY 1263 Query grammars are identified by URIs. Applications SHOULD not 1264 attempt to retrieve these URIs even if they appear to be 1265 retrievable (for example, those that begin with "http://") 1267 9. AUTHENTICATION 1269 Authentication mechanisms defined in WebDAV will also apply to 1270 DASL. 1272 10. IANA CONSIDERATIONS 1274 This document uses the namespace defined by [WebDAV] for XML 1275 elements. All other IANA considerations mentioned in [WebDAV] also 1276 applicable to DASL 1278 11. COPYRIGHT 1280 To be supplied. 1282 12. INTELLECTUAL PROPERTY 1284 To be supplied. 1286 13. REFERENCES 1288 [DASLREQ] S. Reddy, J.Slein, "Requirements for DAV Searching and 1289 Locating", March 1998, internet-draft, work-in-progress, draft- 1290 reddy-dasl-requirements-02.txt 1292 [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. 1293 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, 1294 U.C. Irvine, DEC, MIT/LCS, January 1997. 1296 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 1297 Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1298 1997. 1300 [WebDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D. 1301 Jenson, "Extensions for Distributed Authoring on the World Wide 1302 Web", April. 1998, internet-draft, work-in-progress, draft-ietf- 1303 webdav-protocol-08. 1305 14. AUTHOR'S ADDRESSES 1307 Saveen Reddy 1308 Microsoft 1309 One Microsoft Way 1310 Redmond WA, 9085-6933 1311 Email:saveenr@microsoft.com 1313 Dale Lowry 1314 Novell 1315 1555 N. Technology Way 1316 M/S ORM-M-314 1317 Orem, UT 84097 1318 Email: dlowry@novell.com 1320 Surendra Reddy 1321 Oracle Corporation 1322 600 Oracle Parkway, M/S 6op3, 1323 Redwoodshores, CA 94065 1324 Email: skreddy@us.oracle.com 1325 Phone:(650) 506 5441 1327 Rick Henderson 1328 Netscape 1329 Email: rickh@netscape.com 1331 Jim Davis 1332 Xerox PARC 1333 3333 Coyote Hill Road 1334 Palo Alto CA 94304 1335 650-812-4301 1336 Email: jdavis@parc.xerox.com 1338 Alan Babich 1339 Filenet 1340 3565 Harbor Blvd. 1341 Costa Mesa, CA 92626 1342 714-966-3403 1343 Email: ababich@filenet.com 1345 15. APPENDICES 1347 Appendix A Three-Valued Logic in DAV:simplesearch 1349 ANSI standard three valued logic is used when evaluating the search 1350 condition (as defined in the ANSI standard SQL specifications, for 1351 example in ANSI X3.135-1992, section 8.12, pp. 188-189, section 1352 8.2, p. 169, General Rule 1)a), etc.). 1354 ANSI standard three valued logic is undoubtedly the most widely 1355 practiced method of dealing with the issues of properties in the 1356 search condition not having a value (e.g., being null or not 1357 defined) for the resource under scan, and with undefined 1358 expressions in the search condition (e.g., division by zero, etc.). 1359 Three valued logic works as follows. 1361 Undefined expressions are expressions for which the value of the 1362 expression is not defined. Undefined expressions are a completely 1363 separate concept from the truth value UNKNOWN, which is, in fact, 1364 well defined. Property names and literal constants are considered 1365 expressions for purposes of this section. If a property in the 1366 current resource under scan has not been set to a value (either 1367 because the property is not defined for the current resource, or 1368 because it is null for the current resource), then the value of 1369 that property is undefined for the resource under scan. DASL 1.0 1370 has no arithmetic division operator, but if it did, division by 1371 zero would be an undefined arithmetic expression. 1373 If any subpart of an arithmetic, string, or datetime subexpression 1374 is undefined, the whole arithmetic, string, or datetime 1375 subexpression is undefined. 1377 There are no manifest constants to explicitly represent undefined 1378 number, string, or datetime values. 1380 Since a Boolean value is ultimately returned by the search 1381 condition, arithmetic, string, and datetime expressions are always 1382 arguments to other operators. Examples of operators that convert 1383 arithmetic, string, and datetime expressions to Boolean values are 1384 the six relational operators ("greater than", "less than", 1385 "equals", etc.). If either or both operands of a relational 1386 operator have undefined values, then the relational operator 1387 evaluates to UNKNOWN. Otherwise, the relational operator evaluates 1388 to TRUE or FALSE, depending upon the outcome of the comparison. 1390 The Boolean combinational operators DAV:and, DAV:or and DAV:not are 1391 evaluated according to the following rules. 1393 For not, not TRUE is FALSE, not FALSE is TRUE, and not UNKNOWN is 1394 UNKNOWN. (Intuitively speaking, if we don't know if the value 1395 should be TRUE or FALSE, then if we logically negate the truth 1396 value, we still don't know whether the truth value should be TRUE 1397 or FALSE.) 1399 For and, if any of the operands are FALSE, the result is FALSE. If 1400 no operand is FALSE, then if any operands is UNKNOWN, the result is 1401 UNKNOWN. Otherwise, all of the operands are TRUE, and the result 1402 is TRUE. (Intuitively speaking, if any operand is FALSE, we don't 1403 care about any of the other operands. If all operands are TRUE, we 1404 know the result is TRUE. Otherwise, we don't know whether the 1405 value should be TRUE or FALSE.) 1407 For or, if any of the operands are TRUE, the result is TRUE. If no 1408 operand is TRUE, then if any of the operands is UNKNOWN, the result 1409 is UNKNOWN. Otherwise, all of the operands are FALSE, and thee 1410 result is FALSE. (Intuitively speaking, if any operand is TRUE, we 1411 don't care about the other operands. If all the operands are FALSE, 1412 we know the value is FALSE. Otherwise, we don't know whether the 1413 value should be TRUE or FALSE.) 1415 16. CHANGE HISTORY 1417 Feb 14, 1998 1419 Initial Draft 1421 Feb 28, 1998 1423 Referring to DASL as an extension to HTTP/1.1 rather than DAV 1425 Added new sections "Notational Conventions", "Protocol Model", 1426 "Security Considerations" 1428 Changed section 3 to "Elements of Protocol" 1430 Added some stuff to introduction 1432 Added "result set" terminology 1434 Added "IANA Considerations". 1436 Mar 9, 1998 1438 Moved sub-headings of "Elements of Protocol" to first level and 1439 removed "Elements of Protocol" Heading. 1441 Added an sentence in introduction explaining that this is a 1442 "sketch" of a protocol. 1444 Mar 11, 1998 1446 Added sortby, data typing, three valued logic, query schema 1447 property, and element definitions for schema for simplesearch. 1449 April 8, 1998 1451 - made changes based on last week�s DASL BOF. 1453 May 8, 1998 1455 Removed most of DAV:searcherror; converted to DAV:searchredirect 1457 Altered DAV:simplesearch grammar to use avoid use of ANY in DTD 1459 June 17, 1998 1461 -Added details on Query Schema Discovery 1463 -Shortened list of data types 1465 June 23, 1998 1467 moved data types before change history 1469 rewrote the data types section 1471 removed the casesensitive element and replace with the 1472 casesensitive attribute 1474 added the casesensitive attribute to the DTD for all operations 1475 that might work on a string 1477 Jul 20, 1998 1479 A series of changes. See Author�s meeting minutes for details. 1481 July 28, 1998 1483 Changes as per author's meeting. QSD uses SEARCH, not PROPFIND. 1484 Moved text around to keep concepts nearby. Boolean literals are 1 1485 and 0, not T and F. contains now contentspassthrough. Provide 1486 examples. Rename rank to score. 1488 July 28, 1998 1490 Added Dale Lowry as Author