idnits 2.17.1 draft-ietf-dasl-protocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 is more than 15 pages and seems to lack a Table of Contents. == 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 2 longer pages, the longest (page 11) being 60 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 74 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** There is 1 instance of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 577 has weird spacing: '...LIST lt cas...' == Line 580 has weird spacing: '...IST lte case...' == Line 583 has weird spacing: '...LIST gt cas...' == Line 586 has weird spacing: '...IST gte case...' == Line 589 has weird spacing: '...LIST eq cas...' == 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 (June 24, 1999) is 9071 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: 'RFC 2376' is mentioned on line 135, but not defined ** Obsolete undefined reference: RFC 2376 (Obsoleted by RFC 3023) == Missing Reference: 'WEBDAV' is mentioned on line 405, but not defined == Missing Reference: 'REC-XML' is mentioned on line 1222, but not defined == Unused Reference: 'XMLNS' is defined on line 1294, but no explicit reference was found in the text -- No information found for draft-dasl-requirements - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'DASLREQ' ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2376 (Obsoleted by RFC 3023) ** Obsolete normative reference: RFC 2518 (ref. 'WebDAV') (Obsoleted by RFC 4918) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XMLNS' Summary: 11 errors (**), 0 flaws (~~), 14 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Saveen Reddy, 2 Microsoft 3 draft-ietf-dasl-protocol-00.txt Dale Lowry, Novell 4 Surendra Reddy, 5 Oracle 6 Rick Henderson, 7 Netscape 8 Jim Davis, CourseNet 9 Alan Babich, Filenet 11 Expires December 24, 1999 June 24, 1999 13 DAV Searching & Locating 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. Internet drafts are 19 working documents of the Internet Engineering Task Force (IETF), 20 its areas and its working groups. Note that other groups may also 21 distribute working information as Internet drafts. 23 Internet Drafts are draft documents valid for a maximum of six months 24 and can be updated, replaced or obsoleted by other documents at any 25 time. It is inappropriate to use Internet drafts as reference material 26 or to cite them as other than as "work in progress". 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 Distribution of this document is unlimited. Please send comments to 35 the mailing list at , which may be joined by 36 sending a message with subject "subscribe" to 37 . 39 Discussions of the list are archived at . 42 Abstract 44 This document specifies a set of methods, headers, and content-types 45 composing DASL, an application of the HTTP/1.1 protocol to efficiently 46 search for DAV resources based upon a set of client-supplied criteria. 48 1. Introduction 50 1.1 DASL 52 This document defines DAV Searching & Locating (DASL), an application 53 of HTTP/1.1 forming a lightweight search protocol to transport queries 54 and result sets and allows clients to make use of server-side search 55 facilities. [DASLREQ] describes the motivation for DASL. 57 DASL 59 DASL will minimize the complexity of clients so as to facilitate 60 widespread deployment of applications capable of utilizing the DASL 61 search mechanisms. 63 DASL consists of: 64 * the SEARCH method, 65 * the DASL response header, 66 * the DAV:searchrequest XML element, 67 * the DAV:queryschema property, 68 * the DAV:basicsearch XML element and query grammar, and 69 * the DAV:basicsearchschema XML element. 71 1.2 Relationship to DAV 73 DASL relies on the resource and property model defined by [WebDAV]. 74 DASL does not alter this model. Instead, DASL allows clients to access 75 DAV-modeled resources through server-side search. 77 1.3 Terms 79 This draft uses the terms defined in [RFC2068], [WebDAV], and 80 [DASLREQ]. 82 1.4 Notational Conventions 84 The augmented BNF used by this document to describe protocol elements 85 is exactly the same as the one described in Section 2.1 of [RFC2068]. 86 Because this augmented BNF uses the basic production rules provided in 87 Section 2.2 of [RFC2068], those rules apply to this document as well. 89 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 90 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 91 document are to be interpreted as described in [RFC2119]. 93 1.5 An Overview of DASL at Work 95 One can express the basic usage of DASL in the following steps: 96 * The client constructs a query using the DAV:basicsearch grammar. 97 * The client invokes the SEARCH method on a resource that will 98 perform the search (the search arbiter) and includes a text/xml 99 request entity that contains the query. 100 * The search arbiter performs the query. 101 * The search arbiter sends the results of the query back to the 102 client in the response. The server MUST send a text/xml entity 103 that matches the [WebDAV] PROPFIND response. 105 2. The SEARCH Method 106 DASL 108 2.1 Overview 110 The client invokes the SEARCH method to initiate a server-side search. 111 The body of the request defines the query. The server MUST emit 112 text/xml entity matching the [WebDAV] PROPFIND response. 114 The SEARCH method plays the role of transport mechanism for the query 115 and the result set. It does not define the semantics of the query. The 116 type of the query defines the semantics. 118 2.2 The Request 120 The client invokes the SEARCH method on the resource named by the 121 Request-URI. 123 2.2.1 The Request-URI 125 The Request-URI identifies the search arbiter. 127 The SEARCH method defines no relationship between the arbiter and the 128 scope of the search, rather the particular query grammar used in the 129 query defines the relationship. For example, the FOO query grammar may 130 force the request-URI to correspond exactly to the search scope. 132 2.2.2 The Request Body 134 The server MUST process a text/xml or application/xml request body, 135 and MAY process request bodies in other formats. See [RFC 2376] for 136 guidance on packaging XML in requests. 138 If the client sends a text/xml or application/xml body, it MUST 139 include the DAV:searchrequest XML element. The DAV:searchrequest XML 140 element identifies the query grammar, defines the criteria, the result 141 record, and any other details needed to perform the search. 143 2.3 The DAV:searchrequest XML Element 145 The DAV:searchrequest XML element 146 contains a single XML element that defines the query. The name of the 147 query element defines the type of the query. The value of that element 148 defines the query itself. 150 2.4 The Successful 207 (Multistatus) Response 152 If the server returns 207 (Multistatus), then the search proceeded 153 successfully and the response MUST match that of a PROPFIND. 155 There MUST be one DAV:response for each resource that matched the 156 search criteria. For each such response, the DAV:href element contains 157 the URI of the resource, and the response MUST include a DAV:propstat 158 element. 160 DASL 162 In addition, the server MAY include DAV:response items in the reply where 163 the DAV:href element contains a URI that is not a matching resource, 164 e.g. that of a scope or the query arbiter. Each such response item 165 MUST NOT contain a DAV:propstat element, and MUST contain a DAV:status 166 . It SHOULD contain a DAV:responsedescription . 168 2.4.1 Extending the PROPFIND Response 170 A response MAY include more information than PROPFIND defines so long 171 as the extra information does not invalidate the PROPFIND response. 172 Query grammars SHOULD define how the response matches the PROPFIND 173 response. 175 2.4.1 Example: A Simple Request and Response 177 This example demonstrates the request and response framework. The 178 following XML document shows a simple (hypothetical) natural language 179 query. The name of the query element is FOO:natural-language-query, 180 thus the type of the query is FOO:natural-language-query. The actual 181 query is "Find the locations of good Thai restaurants in Los Angeles". 182 For this hypothetical query, the arbiter returns two properties for 183 each selected resource.SEARCH / HTTP/1.1 184 Host: ryu.com 185 Content-Type: text/xml 186 Connection: Close 187 Content-Length: 243 189 190 191 192 Find the locations of good Thai restaurants in Los Angeles 193 194 >> ResponseHTTP/1.1 207 Multi-Status 195 Content-Type: text/xml 196 Content-Length: 333 198 199 201 202 http://siamiam.com/ 203 204 205 259 W. Hollywood 206 4 207 208 209 210 211 DASL 213 2.5 Unsuccessful Responses 215 If an error occurred that prevented execution of the query, the server 216 MUST indicate the failure with the appropriate status code and SHOULD 217 include a DAV:multistatus element to point out errors associated with 218 scopes. 220 400 Bad Request. The query could not be executed. The request may be 221 malformed (not valid XML for example). Additionally, this can be used 222 for invalid scopes and search redirections. 224 422 Unprocessable entity. The query could not be executed. If a 225 text/xml request entity was provided, then it may have been valid 226 (well-formed) but may have contained an unsupported or unimplemented 227 query operator. 229 507 (Insufficient Storage). The query produced more results than the 230 server was willing to transmit. Partial results have been transmitted. 231 The server MUST send a body that matches that for 207, except that 232 there MAY exist resources that matched the search criteria for which 233 no corresponding DAV:response exists in the reply. 235 2.5.1 Example: Result Set Truncation 237 A server MAY limit the number of resources in a reply, for example to 238 limit the amount of resources expended in processing a query. If it 239 does so, the reply MUST use status code 507. It SHOULD include the 240 partial results. 242 When a result set is truncated, there may be many more resources that 243 satisfy the search criteria but that were not examined. 245 If partial results are included and the client requested an ordered 246 result set in the original request, then any partial results that are 247 returned MUST be ordered as the client directed. 249 Note that the partial results returned MAY be any subset of the result 250 set that would have satisfied the original query.SEARCH / HTTP/1.1 251 Host: gdr.com 252 Content-Type: text/xml 253 Connection: Close 254 Content-Length: xxxxx 256 257 258 259 � the query goes here � 260 261 >> Response 263 HTTP/1.1 507 Insufficient Storage 264 Content-Type: text/xml 265 DASL 267 Content-Length: 738 269 270 271 272 http://www.gdr.com/sounds/unbrokenchain.au 273 274 275 HTTP/1.1 200 OK 276 277 278 279 http://tech.mit.edu/archive96/photos/Lesh1.jpg 280 281 282 HTTP/1.1 200 OK 283 284 285 286 http://gdr.com 287 HTTP/1.1 507 Insufficient Storage 288 289 Only first two matching records were returned 290 291 292 294 2.6 Invalid Scopes & Search Redirections 296 2.6.1 Indicating an Invalid Scope 298 A client may submit a scope that the arbiter may be unable to query. 299 The inability to query may be due to network failure, administrative 300 policy, security, etc. This raises the condition described as an 301 "invalid scope". 303 To indicate an invalid scope, the server MUST respond with a 400 (Bad 304 Request). 306 The response includes a text/xml body with a DAV:multistatus element. 307 Each DAV:resource in the DAV:multistatus identifies a scope. To 308 indicate that this scope is the source of the error, the server MUST 309 include the DAV:scopeerror element. 311 2.6.2 Example of an Invalid Scope 313 HTTP/1.1 400 Bad-Request 314 Content-Type: text/xml 315 Content-Length: xxxxx 316 DASL 318 320 321 322 http://www.foo.com/X 323 HTTP/1.1 404 Object Not Found 324 325 326 328 2.6.3 Redirections 330 As described above, a server can indicate only that the scope is 331 invalid. Some search arbiters may be able to indicate that other 332 search arbiters exist for that scope. 334 In this case, the server MUST: 336 (1) include the DAV:scopeerror element 338 (2) include the DAV:status element for that scope. The value of this 339 element MUST be a 303 (See Other) response. 341 (3) include the DAV:redirectarbiter element for each arbiter the 342 client should use for the redirect. The value of this element is the 343 URI of the arbiter to use. Multiple DAV:redirectarbiter elements are 344 allowed. 346 2.6.4 Example of a Search Redirection 348 HTTP/1.1 400 Bad-Request 349 Content-Type: text/xml 350 Content-Length: xxxxx 352 353 355 356 357 http://www.foo.com/X 358 HTTP/1.1 303 See Other 359 360 http://bar.com/B 361 http://baz.com/B 362 363 365 2.6.5 Syntax for DAV:scopeerror 367 368 DASL 370 2.6.6 Syntax for DAV:redirectarbiter 372 The contents must 373 be a URL. 375 3. Discovery of Supported Query Grammars 377 Servers MUST support discovery of the query grammars supported by a 378 search arbiter resource. 380 Clients can determine which query grammars are supported by an arbiter 381 by invoking OPTIONS on the search arbiter. If the resource supports 382 SEARCH, then the DASL response header will appear in the response. The 383 DASL response header lists the supported grammars. 385 3.1 The OPTIONS Method 387 The OPTIONS method allows the client to discover if a resource 388 supports the SEARCH method and to determine the list of search 389 grammars supported for that resource. 391 The client issues the OPTIONS method against a resource named by the 392 Request-URI. This is a normal invocation of OPTIONS defined in 393 [RFC2068]. 395 If a resource supports the SEARCH method, then the server MUST list 396 SEARCH in the OPTIONS response as defined by [RFC2068]. 398 DASL servers MUST include the DASL header in the OPTIONS response. 399 This header identifies the search grammars supported by that resource. 401 3.2 The DASL Response Header 403 DASLHeader = "DASL" ":" Coded-URL-List 404 Coded-URL-List : Coded-URL [ "," Coded-URL-List ] 405 Coded-URL ; defined in section 9.4 of [WEBDAV] The DASL response 406 header indicates server support for a query grammar in the OPTIONS 407 method. The value is a URI that indicates the type of grammar. This 408 header MAY be repeated. 410 For example:DASL: 411 DASL: 412 DASL: 414 3.3 Example: Grammar Discovery 416 This example shows that the server supports search on the /somefolder 417 resource with the query grammars: DAV:basicsearch, 418 http://foo.bar.com/syntax1 and http://akuma.com/syntax2 . Note that 419 every server MUST support DAV:basicsearch . 421 DASL 423 >>Request 424 OPTIONS /somefolder HTTP/1.1 425 Connection: Close 426 Host: ryu.com >> ResponseHTTP/1.1 200 OK 427 Date: Tue, 20 Jan 1998 20:52:29 GMT 428 Connection: close 429 Accept-Ranges: none 430 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 431 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH 432 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 433 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH 434 DASL: 435 DASL: 436 DASL: 438 4. Query Schema Discovery: QSD 440 Servers MAY support the discovery of the schema for a query grammar. 442 The DASL response header provides means for clients to discover the 443 set of query grammars supported by a resource. This alone is not 444 sufficient information for a client to generate a query. For example, 445 the DAV:basicsearch grammar defines a set of queries consisting of a 446 set of operators applied to a set of properties and values, but the 447 grammar itself does not specify which properties may be used in the 448 query. QSD for the DAV:basicsearch grammar allows a client to discover 449 the set of properties that are searchable, selectable, and sortable. 450 Moreover, although the DAV:basicsearch grammar defines a minimal set 451 of operators, it is possible that a resource might support additional 452 operators in a query. For example, a resource might support a optional 453 operator that can be used to express content-based queries in a 454 proprietary syntax. QSD allows a client to discover these operators 455 and their syntax. The set of discoverable quantities will differ from 456 grammar to grammar, but each grammar can define a means for a client 457 to discover what can be discovered. 459 In general, the schema for a given query grammar depends on both the 460 resource (the arbiter) and the scope. A given resource might have 461 access to one set of properties for one potential scope, and another 462 set for a different scope. For example, consider a server able to 463 search two distinct collections, one holding cooking recipes, the 464 other design documents for nuclear weapons. While both collections 465 might support properties such as author, title, and date, the first 466 might also define properties such as calories and preparation time, 467 while the second defined properties such as yield and applicable 468 patents. Two distinct arbiters indexing the same collection might also 469 have access to different properties. For example, the recipe 470 collection mentioned above might also indexed by a value-added server 471 that also stored the names of chefs who had tested the recipe. Note 472 also that the available query schema might also depend on other 473 factors, such as the identity of the principal conducting the search, 474 but these factors are not exposed in this protocol. 476 DASL 478 Each query grammar supported by DASL defines its own syntax for 479 expressing the possible query schema. A client retrieves the schema 480 for a given query grammar on an arbiter resource with a given scope by 481 invoking the SEARCH method on that arbiter, with that grammar and 482 scope, with a query whose DAV:select element includes the 483 DAV:queryschema property. This property is defined only in the context 484 of such a search, a server SHOULD not treat it as defined in the 485 context of a PROPFIND on the scope. The content of this property is an 486 XML element whose name and syntax depend upon the grammar, and whose 487 value may (and likely will) vary depending upon the grammar, arbiter, 488 and scope. 490 The query schema for DAV:basicsearch is defined in section 5.19. 492 4.1 The DAV:queryschema Property 494 496 4.1.1 Example of query schema discovery 498 In this example, the arbiter is recipes.com, the grammar is 499 DAV:basicsearch , the scope is also recipes.com.SEARCH / HTTP/1.1 500 Host: recipes.com 501 Content-Type: application/xml 502 Connection: Close 503 Content-Length: xxx 505 506 507 508 509 510 512 http://recipes.com 513 514 Response:HTTP/1.1 207 Multistatus 515 Content-Type: application/xml 516 Content-Length: xxx 518 519 520 521 http://recipes.com 522 523 524 525 526 See section 5.19.9 for actual contents 527 528 529 530 DASL 532 HTTP/1.1 200 Okay 533 534 535 537 5 The DAV:basicsearch Grammar 539 5.1 Introduction 541 DAV:basicsearch uses an extensible XML syntax that allows clients to 542 express search requests that are generally useful for WebDAV 543 scenarios. DASL-extended servers MUST accept this grammar, and MAY 544 accept others grammars. 546 DAV:basicsearch has several components: 547 * DAV:select provides the result record definition. 548 * DAV:from defines the scope. 549 * DAV:where defines the criteria. 550 * DAV:orderby defines the sort order of the result set. 551 * DAV:limit provides constraints on the query as a whole. 553 5.2 The DAV:basicsearch DTD 555 557 559 560 562 563 564 565 567 570 572 574 576 577 579 580 582 583 585 586 588 589 591 592 594 595 596 598 599 602 603 605 606 607 DASL 609 5.2.1 Example Query 611 This query retrieves the content length values for all resources 612 located under the server's "/container1/" URI namespace whose length 613 exceeds 10000. 614 615 616 617 618 619 620 /container1/ 621 infinity 622 623 624 625 626 627 10000 628 629 630 631 632 633 634 635 636 637 639 5.3 DAV:select 641 DAV:select defines the result record, which is a set of properties and 642 values. This document defines two possible values: DAV:allprop and 643 DAV:prop , both defined in [WebDAV]. 645 If the value is DAV:allprop , the result record for a given resource 646 includes all the properties for that resource. 648 If the value is DAV:prop , then the result record for a given resource 649 includes only those properties named by the DAV:prop element. Each 650 property named by the DAV:prop element must be referenced in the 651 Multistatus response. 653 DASL 655 The rules governing the status codes for each property match those of 656 the PROPFIND method defined in [WebDAV]. 658 5.4 DAV:from 660 DAV:from defines the query scope. This contains exactly one DAV:scope 661 element. The scope element contains a mandatory DAV:href element and 662 an optional DAV:depth element. 664 DAV:href indicates the URI for a collection to use as a scope. 666 When the scope is a collection, if DAV:depth is "0", the search 667 includes only the collection. When it is "1", the search includes the 668 (toplevel) members of the collection. When it is "infinity", the 669 search includes all recursive members of the collection. 671 5.4.1 Relationship to the Request-URI 673 If the DAV:scope element is an absolute URI, the scope is exactly that 674 URI. 676 If the DAV:scope element is a relative URI, the scope is taken to be 677 relative to the request-URI. 679 5.4.2 Scope 681 A Scope can be an arbitrary URI. 683 Servers, of course, may support only particular scopes. This may 684 include limitations for particular schemes such as "http:" or "ftp:" 685 or certain URI namespaces. 687 If a scope is given that is not supported the server MUST respond with 688 a 400 status code that includes a Multistatus error. A scope in the 689 query appears as a resource in the response and must include an 690 appropriate status code indicating its validity with respect to the 691 search arbiter. 693 Example:HTTP/1.1 400 Bad Request 694 Content-Type: text/xml 695 Content-Length: 428 697 698 699 700 http://www.foo.com/scope1 701 HTTP/1.1 502 Bad Gateway 702 703 This example shows the response if there is a scope 704 error. The response provides a Multistatus with a status for the 705 scope. In this case, the scope cannot be reached because the server 706 cannot search another server (502). 708 DASL 710 5.5 DAV:where 712 DAV:where element defines the search condition for inclusion of 713 resources in the result set. The value of this element is an XML 714 element that defines a search operator that evaluates to one of the 715 Boolean truth values TRUE, FALSE, or UNKNOWN. The search operator 716 contained by DAV:where may itself contain and evaluate additional 717 search operators as operands, which in turn may contain and evaluate 718 additional search operators as operands, etc. recursively. 720 5.5.1 Use of Three-Valued Logic in Queries 722 Each operator defined for use in the where clause that returns a 723 Boolean value MUST evaluate to TRUE, FALSE, or UNKNOWN. The resource 724 under scan is included as a member of the result set if and only if 725 the search condition evaluates to TRUE. 727 Consult Appendix A for details on the application of three-valued 728 logic in query expressions. 730 5.5.2 Handling Optional operators 732 If a query provides an operator that is not supported by the server, 733 then the server MUST respond with a 422 (Unprocessable Entity) status 734 code. 736 5.5.3 Treatment of NULL Values 738 If a SEARCH PROPFIND for a property value would yield a 404 or 403 739 response for that property, then that property is considered NULL. 741 NULL values are "less than" all other values in comparisons. 743 Empty strings (zero length strings) are not NULL values. An empty 744 string is "less then" a string with length greater than zero. 746 The DAV:isdefined operator is defined to test if the value of a 747 property is NULL. 749 5.5.4 Example: Testing for Equality 751 The example shows a single operator ( DAV:eq ) applied in the 752 criteria. 753 754 755 100 756 758 759 DASL 761 5.5.5 Example: Relative Comparisons 763 The example shows a more complex operation involving several operators 764 ( DAV:and , DAV:eq , DAV:gt ) applied in the criteria. This DAV:where 765 expression matches those resources that are "image/gifs" over 4K in 766 size. 767 768 769 770 image/gif 771 772 773 774 4096 775 776 778 780 5.6 DAV:orderby 782 The DAV:orderby element specifies the ordering of the result set. It 783 contains one or more DAV:order elements, each of which specifies a 784 comparison between two items in the result set. Informally, a 785 comparison specifies a test that determines whether one resource 786 appears before another in the result set. Comparisons are applied in 787 the order they occur in the DAV:orderby element, earlier comparisons 788 being more significant. 790 The comparisons defined here use only a single property from each 791 resource, compared using the same ordering as the DAV:lt operator 792 (ascending) or DAV:gt operator (descending). If neither direction is 793 specified, the default is DAV:ascending . 795 In the context of the DAV:orderby element, null values are considered 796 to collate before any actual (i.e., non null) value, including strings 797 of zero length (as in ANSI standard SQL, [ANSISQL]). 799 5.6.1 Comparing Natural Language Strings. 801 Comparisons on strings take into account the language defined for that 802 property. Clients MAY specify the language using the xml:lang 803 attribute. If no language is specified either by the client or defined 804 for that property by the server or if a comparison is performed on 805 strings of two different languages, the results are undefined. 807 The DAV:casesensitive attribute may be used to indicate 808 case-sensitivity for comparisons. 810 DASL 812 5.6.2 Example of Sorting 814 This sort orders first by last name of the author, and then by size, 815 in descending order, so that the largest works appear first. 816 817 818 819 820 821 822 823 824 825 827 5.7 Boolean Operators: DAV:and , DAV:or , and DAV:not 829 The DAV:and operator performs a logical AND operation on the 830 expressions it contains. 832 The DAV:or operator performs a logical OR operation on the values it 833 contains. 835 The DAV:not operator performs a logical NOT operation on the values it 836 contains. 838 5.8 DAV:eq 840 The DAV:eq operator provides simple equality matching on property 841 values. 843 The DAV:casesensitive attribute may be used with this element. 845 5.9 DAV:lt , DAV:lte , DAV:gt , DAV:gte 847 The DAV:lt , DAV:lte , DAV:gt , and DAV:gte operators provide 848 comparisons on property values, using less-than, less-than or equal, 849 greater-than, and greater-than or equal respectively. The 850 DAV:casesensitive attribute may be used with these elements. 852 5.10 DAV:literal 854 DAV:literal allows literal values to be placed in an expression. 856 Because white space in literal values is significant in comparisons, 857 DAV:literal makes use of the xml:space attribute to identify this 858 significance. The default value of this attribute for DAV:literal is 859 preserve. Consult section 2.10 of [XML] for more information on the 860 use of this attribute. 862 DASL 864 5.11 DAV:isdefined 866 The DAV:isdefined operator allows clients to determine whether a 867 property is defined on a resource. The meaning of "defined on a 868 resource" is found in section 5.5.3. 870 Example: 871 872 873 875 The DAV:isdefined operator is optional. 877 5.12 DAV:like 879 The DAV:like is an optional operator intended to give simple 880 wildcard-based pattern matching ability to clients. 882 The operator takes two arguments. 884 The first argument is a DAV:prop element identifying a single property 885 to evaluate. 887 The second argument is a DAV:literal element that gives the pattern 888 matching string. 890 5.12.1 Syntax for the Literal Pattern 892 Pattern := [wildcard] 0*( text [wildcard] ) 893 wildcard := exactlyone | zeroormore 894 text := 1*( | escapesequence ) 895 exactlyone : = "?" 896 zeroormore := "%" 897 escapechar := "\" 898 escapesequence := "\" ( exactlyone | zeroormore | escapechar ) The 899 value for the literal is composed of wildcards separated by segments 900 of text. Wildcards may begin or end the literal. Wildcards may not be 901 adjacent. 903 The "?" wildcard matches exactly one character. 905 The "%" wildcard matches zero or more characters 907 The "\" character is an escape sequence so that the literal can 908 include "?" and "%". To include the "\" character in the pattern, the 909 escape sequence "\\" is used.. 911 5.12.2 Example of DAV:like 913 This example shows how a client might use DAV:like to identify those 914 resources whose content type was a subtype of image. 915 916 917 image% 918 919 DASL 921 923 5.13 DAV:contains 925 The DAV:contains operator is an optional operator that provides 926 content-based search capability. This operator implicitly searches 927 against the text content of a resource, not against content of 928 properties. The DAV:contains operator is intentionally not overly 929 constrained, in order to allow the server to do the best job it can in 930 performing the search. 932 The DAV:contains operator evaluates to a Boolean value. It evaluates 933 to TRUE if the content of the resource satisfies the search. 934 Otherwise, It evaluates to FALSE. 936 Within the DAV:contains XML element, the client provides a phrase: a 937 single word or whitespace delimited sequence of words. Servers MAY 938 ignore punctuation in a phrase. Case-sensitivity is left to the 939 server. 941 The following things may or may not be done as part of the search: 942 Phonetic methods such as "soundex" may or may not be used. Word 943 stemming may or may not be performed. Thesaurus expansion of words may 944 or may not be done. Right or left truncation may or may not be 945 performed. The search may be case insensitive or case sensitive. The 946 word or words may or may not be interpreted as names. Multiple words 947 may or may not be required to be adjacent or "near" each other. 948 Multiple words may or may not be required to occur in the same order. 949 Multiple words may or may not be treated as a phrase. The search may 950 or may not be interpreted as a request to find documents "similar" to 951 the string operand. 953 The DAV:score property is intended to be useful to rank documents 954 satisfying the DAV:contains operator. 956 5.13.1 Examples 958 The example below shows a search for the phrase "Peter Forsberg". 960 Depending on its support for content-based searching, a server MAY 961 treat this as a search for documents that contain the words "Peter" 962 and "Forsberg". 963 Peter Forsberg 964 The example below shows a search for resources that contain 965 "Peter" and "Forsberg". 966 967 Peter 968 Forsberg 969 970 971 DASL 973 5.14 The DAV:limit XML Element 975 The DAV:limit XML element contains 976 requested limits from the client to limit the size of the reply or 977 amount of effort expended by the server. 979 5.15 The DAV:nresults XML Element 981 ;only digits The DAV:nresults XML 982 element contains a requested maximum number of records to be returned 983 in a reply. The server MAY disregard this limit. The value of this 984 element is an integer. 986 5.16 The DAV:casesensitive XML attribute 988 The DAV:casesensitive attribute allows clients to specify 989 case-sensitive or case-insensitive behavior for DAV:basicsearch 990 operators. 992 The possible values for DAV:casesensitive are "1" or "0". The "1" 993 value indicates case-sensitivity. The "0" value indicates 994 case-insensitivity. The default value is server-specified. 996 Support for the DAV:casesensitive is optional. A server should respond 997 with an error 422 if the DAV:casesensitive attribute is used but 998 cannot be supported. 1000 5.17 The DAV:score Property 1002 The DAV:score XML element is a synthetic 1003 property whose value is defined only in the context of a query result 1004 where the server computes a score, e.g. based on relevance. It may be 1005 used in DAV:select or DAV:orderby elements. Servers SHOULD support 1006 this property. The value is a string representing the score, an 1007 integer from zero to 10000 inclusive, where a higher value indicates a 1008 higher score (e.g. more relevant). 1010 Clients should note that, in general, it is not meaningful to compare 1011 the numeric values of scores from two different queries unless both 1012 were executed by the same underlying search system on the same 1013 collection of resources. 1015 5.18 The DAV:iscollection Property 1017 The DAV:iscollection XML element is 1018 a synthetic property whose value is defined only in the context of a 1019 query. 1021 DASL 1023 The property is TRUE (the literal string "1") of a resource if and only 1024 if a PROPFIND of the DAV:resourcetype property for that resource would 1025 contain the DAV:collection XML element. The property is FALSE (the 1026 literal string "0") otherwise. 1028 Rationale : This property is provided in lieu of defining generic 1029 structure queries, which would suffice for this and for many more 1030 powerful queries, but seems inappropriate to standardize at this time. 1032 5.18.1 Example of DAV:iscollection 1034 This example shows a search criterion that picks out all and only the 1035 resources in the scope that are collections. 1036 1037 1038 1 1039 1040 1042 5.19 QuerySchema for DAV:basicsearch 1044 The DAV:basicsearch grammar defines a search criteria that is a 1045 Boolean-valued expression, and allows for an arbitrary set of 1046 properties to be included in the result record. The result set may be 1047 sorted on a set of property values. Accordingly the DTD for schema 1048 discovery for this grammar allows the server to express: 1049 1 the set of optional operators defined by the resource. 1051 5.19.1 DTD for DAV:basicsearch QSD 1053 1054 1055 1056 1057 1058 1059 The DAV:properties element 1060 holds a list of descriptions of properties. 1062 The DAV:operators element describes the optional operators that may be 1063 used in a DAV:where element. 1065 5.19.2 DAV:propdesc Element 1067 Each instance of a DAV:propdesc element describes the property or 1068 properties in the DAV:prop element it contains. All subsequent 1069 elements are descriptions that apply to those properties. All 1070 descriptions are optional and may appear in any order. Servers SHOULD 1071 support all the descriptions defined here, and MAY define others. 1073 DASL 1075 DASL defines five descriptions. The first, DAV:datatype , provides a 1076 hint about the type of the property value, and may be useful to a user 1077 interface prompting for a value. The remaining four ( DAV:searchable , 1078 DAV:selectable , DAV:sortable , and DAV:casesensitive ) identify 1079 portions of the query ( DAV:where , DAV:select , and DAV:orderby , 1080 respectively). If a property has a description for a section, then the 1081 server MUST allow the property to be used in that section. These 1082 descriptions are optional. If a property does not have such a 1083 description, or is not described at all, then the server MAY still 1084 allow the property to be used in the corresponding section. 1086 5.19.3 The DAV:datatype Property Description 1088 The DAV:datatype element contains a single XML element that provides a 1089 hint about the domain of the property, which may be useful to a user 1090 interface prompting for a value to be used in a query. The namespace 1091 for expressing a DASL defined data type is 1092 "urn:uuid:C2F41010-65B3-11d1-A29F-00AA00C14882/". DASL defines the following data type elements: Name example 1094 boolean 1, 0 1095 string Foobar 1096 dateTime.iso8601tz 1994-11-05T08:15:5Z 1097 float .314159265358979E+1 1098 int -259, 23 1100 If the data type of a property is not given, then the data type 1101 defaults to string. 1103 5.19.4 The DAV:searchable Property Description 1105 If this element is 1106 present, then the server MUST allow this property to appear within a 1107 DAV:where element where an operator allows a property. Allowing a 1108 search does not mean that the property is guaranteed to be defined on 1109 every resource in the scope, it only indicates the server's 1110 willingness to check. 1112 5.19.5 The DAV:selectable Property Description 1114 This element indicates 1115 that the property may appear in the DAV:select element. 1117 5.19.6 The DAV:sortable Property Description 1119 This element indicates that the property may appear in the DAV:orderby 1120 element 1121 DASL 1123 5.19.7 The DAV:casesensitive Property Description 1125 This element only applies to properties whose data type is "string" as 1126 per the DAV:datatype property description. Its presence indicates that 1127 compares performed for searches, and the comparisons for ordering 1128 results on the string property will be case sensitive. (The default is 1129 case insensitive.) 1131 5.19.8 The DAV:operators XML Element 1133 The DAV:operators element describes every optional operator supported 1134 in a query. (Mandatory operators are not listed since they are 1135 mandatory and permit no variation in syntax.). All optional operators 1136 that are supported MUST be listed in the DAV:operators element. The 1137 listing for an operator consists of the operator (as an empty 1138 element), followed by one element for each operand. The operand MUST 1139 be either DAV:operand _property or DAV:operand _literal, which 1140 indicate that the operand in the corresponding position is a property 1141 or a literal value, respectively. If an operator is polymorphic 1142 (allows more than one operand syntax) then each permitted syntax MUST 1143 be listed separately. 1144 1146 5.19.9 Example of Query Schema for DAV:basicsearch 1148 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 This response lists four properties. The 1175 DASL 1177 datatype of the last three properties is not given, so it defaults to 1178 string. All are selectable, and the first three may be searched. All 1179 but the last may be used in a sort. Of the optional DAV operators, 1180 DAV:isdefined and DAV:like are supported. 1182 Note: The schema discovery defined here does not provide for discovery 1183 of supported values of the DAV:casesensitive attribute. This may 1184 require that the reply also list the mandatory operators. 1186 6 Internationalization Considerations 1188 Clients have the opportunity to tag properties when they are stored in 1189 a language. The server SHOULD read this language-tagging by examining 1190 the xml:lang attribute on any properties stored on a resource. 1192 The xml:lang attribute specifies a nationalized collation sequence 1193 when properties are compared. 1195 Comparisons when this attribute differs have undefined order. 1197 7 Security Considerations 1199 This section is provided to detail issues concerning security 1200 implications of which DASL applications need to be aware. All of the 1201 security considerations of HTTP/1.1 also apply to DASL. In addition, 1202 this section will include security risks inherent in searching and 1203 retrieval of resource properties and content. 1205 A query must not allow one to retrieve information about values or 1206 existence of properties that one could not obtain via PROPFIND. (e.g. 1207 by use in DAV:orderby , or in expressions on properties.) 1209 A server should prepare for denial of service attacks. For example a 1210 client may issue a query for which the result set is expensive to 1211 calculate or transmit because many resources match or must be 1212 evaluated. 7.1 Implications of XML External Entities 1214 XML supports a facility known as "external entities", defined in 1215 section 4.2.2 of [REC-XML], which instruct an XML processor to 1216 retrieve and perform an inline include of XML located at a particular 1217 URI. An external XML entity can be used to append or modify the 1218 document type declaration (DTD) associated with an XML document. An 1219 external XML entity can also be used to include XML within the content 1220 of an XML document. For non-validating XML, such as the XML used in 1221 this specification, including an external XML entity is not required 1222 by [REC-XML]. However, [REC-XML] does state that an XML processor may, 1223 at its discretion, include the external XML entity. 1225 DASL 1227 External XML entities have no inherent trustworthiness and are subject 1228 to all the attacks that are endemic to any HTTP GET request. 1229 Furthermore, it is possible for an external XML entity to modify the 1230 DTD, and hence affect the final form of an XML document, in the worst 1231 case significantly modifying its semantics, or exposing the XML 1232 processor to the security risks discussed in [RFC2376]. Therefore, 1233 implementers must be aware that external XML entities should be 1234 treated as untrustworthy. 1236 There is also the scalability risk that would accompany a widely 1237 deployed application which made use of external XML entities. In this 1238 situation, it is possible that there would be significant numbers of 1239 requests for one external XML entity, potentially overloading any 1240 server which fields requests for the resource containing the external 1241 XML entity. 1243 8 Scalability 1245 Query grammars are identified by URIs. Applications SHOULD not attempt 1246 to retrieve these URIs even if they appear to be retrievable (for 1247 example, those that begin with "http://") 1249 9 Authentication 1251 Authentication mechanisms defined in WebDAV will also apply to DASL. 1253 10 IANA Considerations 1255 This document uses the namespace defined by [WebDAV] for XML elements. 1256 All other IANA considerations mentioned in [WebDAV] also applicable to 1257 DASL 1259 11 Copyright 1261 To be supplied. 1263 12 Intellectual Property 1265 To be supplied. 1267 13 References 1269 13.1 Normative References 1271 [DASLREQ] J. Davis, S. Reddy, J. Slein, "Requirements for DAV 1272 Searching and Locating", Feb 24, 1999, internet-draft, 1273 work-in-progress, draft-dasl-requirements-01.txt 1274 DASL 1276 [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. 1277 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, U.C. 1278 Irvine, DEC, MIT/LCS, January 1997. 1280 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 1281 Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1282 1997. 1284 [RFC2376] E. Whitehead, M. Murata, "XML Media Types". RFC 2376, July 1285 1998. 1287 [WebDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D. Jenson, 1288 "HTTP Extensions for Distributed Authoring -- WebDAV", RFC 2518, 1289 February 1999. 1291 [XML] T. Bray, J. Paoli, C. M. Sperberg-McQueen, "Extensible Markup 1292 Language (XML) 1.0", September 16, 1998, W3C Recommendation. 1294 [XMLNS] T. Bray, D. Hollander, A. Layman, "Namespaces in XML", 1295 14-January-1999, W3C Recommendation. 1296 http://www.w3.org/TR/REC-xml-names/ . 1298 13.2 Non-Normative References 1300 [ANSISQL] ANSI, "Information Systems - Database Language - SQL 1301 (includes ANSI X3.168-1989)", ANSI X3.135-1992 (R1998), 1992. 1303 14 Author's Addresses 1305 Saveen Reddy 1306 Microsoft 1307 One Microsoft Way 1308 Redmond WA, 9085-6933 1309 Email:saveenr@microsoft.com 1311 Dale Lowry 1312 Novell 1313 1555 N. Technology Way 1314 M/S ORM-M-314 1315 Orem, UT 84097 1316 Email: dlowry@novell.com 1318 Surendra Reddy 1319 Oracle Corporation 1320 600 Oracle Parkway, M/S 6op3, 1321 Redwoodshores, CA 94065 1322 Email: skreddy@us.oracle.com 1323 Phone:(650) 506 5441 1325 Rick Henderson 1326 Netscape 1327 DASL 1329 Email: rickh@netscape.com 1331 Jim Davis 1332 CourseNet Systems 1333 San Francisco, CA 1334 Email: jrd3@alum.mit.edu 1336 Alan Babich 1337 Filenet 1338 3565 Harbor Blvd. 1339 Costa Mesa, CA 92626 1340 714-966-3403 1341 Email: ababich@filenet.com 1343 15 APPENDICES 1345 Three-Valued Logic in DAV:basicsearch 1347 ANSI standard three valued logic is used when evaluating the search 1348 condition (as defined in the ANSI standard SQL specifications, for 1349 example in ANSI X3.135-1992, section 8.12, pp. 188-189, section 8.2, 1350 p. 169, General Rule 1)a), etc.). 1352 ANSI standard three valued logic is undoubtedly the most widely 1353 practiced method of dealing with the issues of properties in the 1354 search condition not having a value (e.g., being null or not defined) 1355 for the resource under scan, and with undefined expressions in the 1356 search condition (e.g., division by zero, etc.). Three valued logic 1357 works as follows. 1359 Undefined expressions are expressions for which the value of the 1360 expression is not defined. Undefined expressions are a completely 1361 separate concept from the truth value UNKNOWN, which is, in fact, well 1362 defined. Property names and literal constants are considered 1363 expressions for purposes of this section. If a property in the current 1364 resource under scan has not been set to a value (either because the 1365 property is not defined for the current resource, or because it is 1366 null for the current resource), then the value of that property is 1367 undefined for the resource under scan. DASL 1.0 has no arithmetic 1368 division operator, but if it did, division by zero would be an 1369 undefined arithmetic expression. 1371 If any subpart of an arithmetic, string, or datetime subexpression is 1372 undefined, the whole arithmetic, string, or datetime subexpression is 1373 undefined. 1375 DASL 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 condition, 1381 arithmetic, string, and datetime expressions are always arguments to 1382 other operators. Examples of operators that convert arithmetic, 1383 string, and datetime expressions to Boolean values are the six 1384 relational operators ("greater than", "less than", "equals", etc.). If 1385 either or both operands of a relational operator have undefined 1386 values, then the relational operator evaluates to UNKNOWN. Otherwise, 1387 the relational operator evaluates to TRUE or FALSE, depending upon the 1388 outcome of the comparison. 1390 The Boolean operators DAV:and , DAV:or and DAV:not are evaluated 1391 according to the following rules: 1393 UNKNOWN and UNKNOWN = UNKNOWN 1395 UNKNOWN or UNKKNOWN = UNKNOWN 1397 not UNKNOWN = UNKNOWN 1399 UNKNOWN and TRUE = UNKNOWN 1401 UNKNOWN and FALSE = FALSE 1403 UNKNOWN and UNKNOWN = UNKNOWN 1405 UNKNOWN or TRUE = TRUE 1407 UNKNOWN or FALSE = UNKNOWN 1409 UNKNOWN or UNKNOWN = UNKNOWN 1411 16 Change History 1413 Feb 14, 1998 1414 Initial Draft 1415 Feb 28, 1998 1416 Referring to DASL as an extension to HTTP/1.1 rather than DAV 1418 Added new sections "Notational Conventions", "Protocol Model", 1419 "Security Considerations" 1420 Changed section 3 to "Elements of Protocol" 1421 Added some stuff to introduction 1422 Added "result set" terminology 1423 Added "IANA Considerations". 1424 Mar 9, 1998 1425 Moved sub-headings of "Elements of Protocol" to first level and 1426 removed "Elements of Protocol" Heading. 1428 DASL 1430 Added an sentence in introduction explaining that this is a "sketch" 1431 of a protocol. 1432 Mar 11, 1998 1433 Added orderby, data typing, three valued logic, query schema 1434 property, and element definitions for schema for basicsearch. 1435 April 8, 1998 1436 - made changes based on last week�s DASL BOF. 1437 May 8, 1998 1438 Removed most of DAV:searcherror ; converted to DAV:searchredirect 1440 Altered DAV:basicsearch grammar to use avoid use of ANY in DTD 1441 June 17, 1998 1442 -Added details on Query Schema Discovery 1444 -Shortened list of data types 1445 June 23, 1998 1446 moved data types before change history 1448 rewrote the data types section 1449 removed the casesensitive element and replace with the casesensitive 1450 attribute 1451 added the casesensitive attribute to the DTD for all operations that 1452 might work on a string 1453 Jul 20, 1998 1454 A series of changes. See Author�s meeting minutes for details. 1455 July 28, 1998 1456 Changes as per author's meeting. QSD uses SEARCH, not PROPFIND. 1458 Moved text around to keep concepts nearby. 1459 Boolean literals are 1 and 0, not T and F. 1460 contains changed to contentspassthrough. 1461 Renamed rank to score. 1462 July 28, 1998 1463 Added Dale Lowry as Author 1464 September 4, 1998 1465 Added 422 as response when query lists unimplemented operators. 1467 DAV:literal declares a default value for xml:space, 'preserve' (see 1468 XML spec, section 2.10) 1469 moved to new XML namespace syntax 1470 September 22, 1998 1471 Changed "simplesearch" to "basicsearch" 1473 Changed isnull to isdefined 1474 Defined NULLness as having a 404 or 403 response 1475 used ENTITY syntax in DTD 1476 Added redirect 1477 October 9, 1998 1478 Fixed a series of typographical and formatting errors. 1480 Modified the section of three-valued logic to use a table rather than 1481 DASL 1483 a text description of the role of UNKNOWN in expressions. 1484 November 2, 1998 1485 Added the DAV:contains operator. 1487 Removed the DAV:contentpassthrough operator. 1488 November 18, 1998 1489 Various author comments for submission 1490 June 3, 1999 1491 Cosmetic and minor editorial changes only. Fix nits reported by 1492 Jim Whitehead in email of April 26, 1999. Converted to HTML from 1493 Word 97, manually.