idnits 2.17.1 draft-reddy-dasl-protocol-04.txt: -(1114): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1131): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1652): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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-04-19) 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 document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** 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. ** Missing revision: the document name given in the document, 'draft-reddy-dasl-protocol-', does not give the document revision number ~~ Missing draftname component: the document name given in the document, 'draft-reddy-dasl-protocol-', does not seem to contain all the document name components required ('draft' prefix, document source, document name, and revision) -- see https://www.ietf.org/id-info/guidelines#naming for more information. == Mismatching filename: the document gives the document name as 'draft-reddy-dasl-protocol-', but the file name used is 'draft-reddy-dasl-protocol-04' == There are 8 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 33 longer pages, the longest (page 32) being 73 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. (A line matching the expected section header was found, but with an unexpected indentation: ' scope, it only indicates the server's willingness to check.' ) ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' 7. SECURITY CONSIDERATIONS' ) ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) (A line matching the expected section header was found, but with an unexpected indentation: ' 10. IANA CONSIDERATIONS' ) ** The document seems to lack an Authors' Addresses Section. ** There are 226 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** There is 1 instance of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1109 has weird spacing: '...ence of words...' == Line 1207 has weird spacing: '... The prope...' == Line 1336 has weird spacing: '...ta type is...' == Line 1696 has weird spacing: '...tion of the r...' == 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://") == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- The document date (May 18, 1999) is 9103 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 section? 'DASLREQ' on line 1459 looks like a reference -- Missing reference section? 'WebDAV' on line 1471 looks like a reference -- Missing reference section? 'RFC2068' on line 1463 looks like a reference -- Missing reference section? 'RFC2119' on line 1467 looks like a reference -- Missing reference section? 'WEBDAV' on line 551 looks like a reference -- Missing reference section? 'XML' on line 1476 looks like a reference -- Missing reference section? 'XMLNS' on line 1480 looks like a reference Summary: 14 errors (**), 1 flaw (~~), 11 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Saveen Reddy, 3 draft-reddy-dasl-protocol- Microsoft 4 04.txt Dale Lowry, Novell 5 Surendra Reddy, Oracle 6 Rick Henderson, 7 Netscape 8 Jim Davis, Xerox 9 Alan Babich, Filenet 10 Expires May 18, 1999 11 November 18, 1998 13 DAV Searching & Locating 15 Status of this Memo 17 This document is an Internet draft. Internet drafts are working 18 documents of the Internet Engineering Task Force (IETF), its 19 areas and its working groups. Note that other groups may also 20 distribute working information as Internet drafts. 22 Internet Drafts are draft documents valid for a maximum of six 23 months and can be updated, replaced or obsoleted by other 24 documents at any time. It is inappropriate to use Internet 25 drafts as reference material or to cite them as other than as 26 "work in progress". 28 To view the entire list of current Internet-Drafts, please check 29 the "1id-abstracts.txt" listing contained in the Internet-Drafts 30 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 31 (Northern Europe), ftp.nis.garr.it (Southern Europe), 32 munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or 33 ftp.isi.edu (US West Coast). 35 Distribution of this document is unlimited. Please send comments 36 to the mailing list at , which may be 37 joined by sending a message with subject "subscribe" to . 40 Discussions of the list are archived at 41 . 43 Abstract 45 This document specifies a set of methods, headers, and content- 46 types composing DASL, an application of the HTTP/1.1 protocol to 47 efficiently search for DAV resources based upon a set of client- 48 supplied criteria. 50 Table of Contents 52 DAV SEARCHING & LOCATING..................................1 54 TABLE OF CONTENTS.........................................2 56 1. INTRODUCTION..........................................4 57 1.1. DASL 4 58 1.2. Relationship to DAV................................5 59 1.3. Terms 5 60 1.4. Notational Conventions.............................5 61 1.5. An Overview of DASL at Work........................5 63 2. THE SEARCH METHOD.....................................5 64 2.1. Overview...........................................5 65 2.2. The Request........................................6 66 2.2.1. The Request-URI...................................6 67 2.2.2. The Request Body..................................6 68 2.3. The DAV:searchrequest XML Element..................6 69 2.4. The Successful 207 (Multistatus) Response..........6 70 2.4.1. Extending the PROPFIND Response...................7 71 2.4.2. Example: A Simple Request and Response............7 72 2.5. Unsuccessful Responses.............................7 73 2.5.1. Example: Result Set Truncation....................8 74 2.6. Invalid Scopes & Search Redirections...............9 75 2.6.1. Indicating an Invalid Scope.......................9 76 2.6.2. Example of an Invalid Scope.......................9 77 2.6.3. Redirections.....................................10 78 2.6.4. Example of a Search Redirection..................10 79 2.6.5. Syntax for DAV:scopeerror........................10 80 2.6.6. Syntax for DAV:redirectarbiter...................10 82 3. DISCOVERY OF SUPPORTED QUERY GRAMMARS................11 83 3.1. The OPTIONS Method................................11 84 3.2. The DASL Response Header..........................11 85 3.3. Example: Grammar Discovery........................11 87 4. QUERY SCHEMA DISCOVERY: QSD..........................12 88 4.1. The DAV:queryschema Property......................13 89 4.1.1. Example of query schema discovery................13 91 5. THE DAV:BASICSEARCH GRAMMAR..........................14 92 5.1. Introduction......................................14 93 5.2. The DAV:basicsearch DTD...........................14 94 5.2.1. Example Query....................................15 95 5.3. DAV:select........................................16 96 5.4. DAV:from..........................................16 97 5.4.1. Relationship to the Request-URI..................16 98 5.4.2. Scope 17 99 5.5. DAV:where.........................................17 100 5.5.1. Use of Three-Valued Logic in Queries.............17 101 5.5.2. Handling Optional operators......................18 102 5.5.3. Treatment of NULL Values.........................18 103 5.5.4. Example: Testing for Equality....................18 104 5.5.5. Example: Relative Comparisons....................18 105 5.6. DAV:orderby.......................................19 106 5.6.1. Comparing Natural Language Strings...............19 107 5.6.2. Example of Sorting...............................19 108 5.7. Boolean Operators: DAV:and, DAV:or, and DAV:not...19 109 5.8. DAV:eq............................................20 110 5.9. DAV:lt, DAV:lte, DAV:gt, DAV:gte..................20 111 5.10. DAV:literal.......................................20 112 5.11. DAV:isdefined.....................................20 113 5.12. DAV:like..........................................20 114 5.12.1. Syntax for the Literal Pattern.................21 115 5.12.2. Example of DAV:like............................21 116 5.13. DAV:contains......................................21 117 5.13.1. Example.........................................22 118 5.13.2. Example.........................................22 119 5.14. The DAV:limit XML Element.........................22 120 5.15. The DAV:nresults XML Element......................22 121 5.16. The DAV:casesensitive XML attribute...............23 122 5.17. The DAV:score Property............................23 123 5.18. The DAV:iscollection Property.....................23 124 5.18.1. Exampe of DAV:iscollection.....................23 125 5.19. Query Schema for DAV:basicsearch..................24 126 5.19.1. DTD for DAV:basicsearch QSD....................24 127 5.19.2. DAV:propdesc Element...........................24 128 5.19.3. The DAV:datatype Property Description..........25 129 5.19.4. The DAV:searchable Property Description........25 130 5.19.5. The DAV:selectable Property Description........25 131 5.19.6. The DAV:sortable Property Description..........26 132 5.19.7. The DAV:casesensitive Property Description.....26 133 5.19.8. The DAV:operators XML Element..................26 134 5.19.9. Example of Query Schema for DAV:basicsearch....26 136 6. INTERNATIONALIZATION CONSIDERATIONS..................27 138 7. SECURITY CONSIDERATIONS..............................27 140 8. SCALABILITY..........................................28 142 9. AUTHENTICATION.......................................28 144 10. IANA CONSIDERATIONS................................28 146 11. COPYRIGHT..........................................28 148 12. INTELLECTUAL PROPERTY..............................28 149 13. REFERENCES.........................................28 151 14. AUTHOR'S ADDRESSES.................................29 153 15. APPENDICES.........................................29 154 Appendix A Three-Valued Logic in DAV:basicsearch........29 156 16. CHANGE HISTORY.....................................31 157 Feb 14, 1998............................................31 158 Feb 28, 1998............................................31 159 Mar 9, 1998.............................................31 160 Mar 11, 1998............................................31 161 April 8, 1998...........................................31 162 May 8, 1998.............................................31 163 June 17, 1998...........................................31 164 June 23, 1998...........................................31 165 Jul 20, 1998............................................32 166 July 28, 1998...........................................32 167 July 28, 1998...........................................32 168 September 4, 1998.......................................32 169 September 22, 1998......................................32 170 October 9, 1998.........................................32 171 November 2, 1998........................................33 172 November 18, 1998.......................................33 174 1. INTRODUCTION 176 1.1. DASL 178 This document defines DAV Searching & Locating (DASL), an 179 application of HTTP/1.1 forming a lightweight search protocol to 180 transport queries and result sets and allows clients to make use 181 of server-side search facilities. [DASLREQ] describes the 182 motivation for DASL. 184 DASL will minimize the complexity of clients so as to facilitate 185 widespread deployment of applications capable of utilizing the 186 DASL search mechanisms. 188 DASL consists of: 190 - the SEARCH method, 192 - the DASL response header, 194 - the DAV:searchrequest XML element, 196 - the DAV:queryschema property, 198 - the DAV:basicsearch XML element and query grammar, and 200 - the DAV:basicsearchschema XML element. 202 1.2. Relationship to DAV 204 DASL relies on the resource and property model defined by 205 [WebDAV]. DASL does not alter this model. Instead, DASL allows 206 clients to access DAV-modeled resources through server-side 207 search. 209 1.3. Terms 211 This draft uses the terms defined in [RFC2068], [WebDAV], and 212 [DASLREQ]. 214 1.4. Notational Conventions 216 The augmented BNF used by this document to describe protocol 217 elements is exactly the same as the one described in Section 2.1 218 of [RFC2068]. Because this augmented BNF uses the basic 219 production rules provided in Section 2.2 of [RFC2068], those 220 rules apply to this document as well. 222 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 223 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 224 "OPTIONAL" in this document are to be interpreted as described in 225 [RFC2119]. 227 1.5. An Overview of DASL at Work 229 One can express the basic usage of DASL in the following steps: 231 - The client constructs a query using the DAV:basicsearch grammar. 233 - The client invokes the SEARCH method on a resource that will 234 perform the search (the search arbiter) and includes a text/xml 235 request entity that contains the query. 237 - The search arbiter performs the query. 239 - The search arbiter sends the results of the query back to the 240 client in the response. The server MUST send a text/xml entity 241 that matches the [WebDAV] PROPFIND response. 243 2. THE SEARCH METHOD 245 2.1. Overview 247 The client invokes the SEARCH method to initiate a server-side 248 search. The body of the request defines the query. The server 249 MUST emit text/xml entity matching the [WebDAV] PROPFIND 250 response. 252 The SEARCH method plays the role of transport mechanism for the 253 query and the result set. It does not define the semantics of 254 the query. The type of the query defines the semantics. 256 2.2. The Request 258 The client invokes the SEARCH method on the resource named by the 259 Request-URI. 261 2.2.1. The Request-URI 263 The Request-URI identifies the search arbiter. 265 The SEARCH method per se defines no relationship between the 266 arbiter and the scope of the search, rather the particular query 267 grammar used in the query defines the relationship. For example, 268 the FOO query grammar may force the request-URI to correspond 269 exactly to the search scope. 271 2.2.2. The Request Body 273 The server MUST process a text/xml request body, and MAY process 274 request bodies in other formats. 276 If the client sends a text/xml body, it MUST include the 277 DAV:searchrequest XML element. The DAV:searchrequest XML element 278 identifies the query grammar, defines the criteria, the result 279 record, and any other details needed to perform the search. 281 2.3. The DAV:searchrequest XML Element 283 285 The DAV:searchrequest XML element contains a single XML element 286 that defines the query. The name of the query element defines 287 the type of the query. The value of that element defines the 288 query itself. 290 2.4. The Successful 207 (Multistatus) Response 292 If the server returns 207 (Multistatus), then the search 293 proceeded successfully and the response MUST match that of a 294 PROPFIND. 296 There MUST be one DAV:response for each resource that matched the 297 search criteria. For each such response, the DAV:href element 298 contains the URI of the resource, and the response MUST include a 299 DAV:propstat element. 301 In addition, the server MAY include DAV:response items in the 302 reply where the DAV:href element contains a URI that is not a 303 matching resource, e.g. that of a scope or the query arbiter. 304 Each such response item MUST NOT contain a DAV:propstat element, 305 and MUST contain a DAV:status. It SHOULD contain a 306 DAV:responsedescription. 308 2.4.1. Extending the PROPFIND Response 310 A response MAY include more information than PROPFIND defines so 311 long as the extra information does not invalidate the PROPFIND 312 response. Query grammars SHOULD define how the response matches 313 the PROPFIND response. 315 2.4.2. Example: A Simple Request and Response 317 This example demonstrates the request and response framework. 318 The following XML document shows a simple (hypothetical) natural 319 language query. The name of the query element is FOO:natural- 320 language-query, thus the type of the query is FOO:natural- 321 language-query. The actual query is "Find the locations of good 322 Thai restaurants in Los Angeles". For this hypothetical query, 323 the arbiter returns two properties for each selected resource. 325 SEARCH / HTTP/1.1 326 Host: ryu.com 327 Content-Type: text/xml 328 Connection: Close 329 Content-Length: 243 331 332 333 334 Find the locations of good Thai restaurants in Los Angeles 335 336 338 >> Response 340 HTTP/1.1 207 Multi-Status 341 Content-Type: text/xml 342 Content-Length: 333 344 345 347 348 http://siamiam.com 349 350 351 259 W. Hollywood 352 4 353 354 355 356 358 2.5. Unsuccessful Responses 360 If an error occurred that prevented execution of the query, the 361 server MUST indicate the failure with the appropriate status code 362 and SHOULD include a DAV:multistatus element to point out errors 363 associated with scopes. 365 400 Bad Request. The query could not be executed. The request may 366 be malformed (not valid XML for example). Additionally, this can 367 be used for invalid scopes and search redirections. 369 422 Unprocessable entity. The query could not be executed. If a 370 text/xml request entity was provided, then it may have been valid 371 (well-formed) but may have contained an unsupported or 372 unimplemented query operator. 374 507 (Insufficient Storage). The query produced more results 375 than the server was willing to transmit. Partial results have 376 been transmitted. The server MUST send a body that matches that 377 for 207, except that there MAY exist resources that matched the 378 search criteria for which no corresponding DAV:response exists in 379 the reply. 381 2.5.1. Example: Result Set Truncation 383 A server MAY limit the number of resources in a reply, for 384 example to limit the amount of resources expended in processing a 385 query. If it does so, the reply MUST use status code 507. It 386 SHOULD include the partial results. 388 When a result set is truncated, there may be many more resources 389 that satisfy the search criteria but that were not examined. 391 If partial results are included and the client requested an 392 ordered result set in the original request, then any partial 393 results that are returned MUST be ordered as the client directed. 395 Note that the partial results returned MAY be any subset of the 396 result set that would have satisfied the original query. 398 SEARCH / HTTP/1.1 399 Host: gdr.com 400 Content-Type: text/xml 401 Connection: Close 402 Content-Length: xxxxx 404 405 406 407 � the query goes here � 408 409 411 >> Response 413 HTTP/1.1 507 Insufficient Storage 414 Content-Type: text/xml 415 Content-Length: 738 416 417 418 419 http://www.gdr.com/sounds/unbrokenchain.au 420 421 422 HTTP/1.1 200 OK 423 424 425 427 http://tech.mit.edu/archive96/photos/Lesh1.jpg 428 429 430 HTTP/1.1 200 OK 431 432 433 434 http://gdr.com 435 HTTP/1.1 507 Insufficient Storage 436 437 Only first two matching records were returned 438 439 440 442 2.6. Invalid Scopes & Search Redirections 444 2.6.1. Indicating an Invalid Scope 446 A client may submit a scope that the arbiter may be unable to 447 query. The inability to query may be due to network failure, 448 administrative policy, security, etc. This raises the condition 449 described as an "invalid scope". 451 To indicate an invalid scope, the server MUST respond with a 400 452 (Bad Request). 454 The response includes a text/xml body with a DAV:multistatus 455 element. Each DAV:resource in the DAV:multistatus identifies a 456 scope. To indicate that this scope is the source of the error, 457 the server MUST include the DAV:scopeerror element. 459 2.6.2. Example of an Invalid Scope 461 HTTP/1.1 400 Bad-Request 462 Content-Type: text/xml 463 Content-Length: xxxxx 465 467 468 469 http://www.foo.com/X 470 HTTP/1.1 404 Object Not Found 471 472 473 475 2.6.3. Redirections 477 As described above, a server can indicate only that the scope is 478 invalid. Some search arbiters may be able to indicate that other 479 search arbiters exist for that scope. 481 In this case, the server MUST: 483 (1) include the DAV:scopeerror element 485 (2) include the DAV:status element for that scope. The value of 486 this element MUST be a 303 (See Other) response. 488 (3) include the DAV:redirectarbiter element for each arbiter the 489 client should use for the redirect. The value of this element is 490 the URI of the arbiter to use. Multiple DAV:redirectarbiter 491 elements are allowed. 493 2.6.4. Example of a Search Redirection 495 HTTP/1.1 400 Bad-Request 496 Content-Type: text/xml 497 Content-Length: xxxxx 499 500 502 503 504 http://www.foo.com/X 505 HTTP/1.1 303 See Other 506 507 http://bar.com/B 508 http://baz.com/B 509 510 512 2.6.5. Syntax for DAV:scopeerror 514 516 2.6.6. Syntax for DAV:redirectarbiter 518 519 3. DISCOVERY OF SUPPORTED QUERY GRAMMARS 521 Servers MUST support discovery of the query grammars supported by 522 a resource. 524 Clients can determine which query grammars are supported by an 525 arbiter by invoking OPTIONS on the search arbiter. If the 526 resource supports SEARCH, then the DASL response header will 527 appear in the response. The DASL response header lists the 528 supported grammars. 530 3.1. The OPTIONS Method 532 The OPTIONS method allows the client to discover if a resource 533 supports the SEARCH method and to determine the list of search 534 grammars supported for that resource. 536 The client issues the OPTIONS method against a resource named by 537 the Request-URI. This is a normal invocation of OPTIONS defined 538 in [RFC2068]. 540 If a resource supports the SEARCH method, then the server MUST 541 list SEARCH in the OPTIONS response as defined by [RFC2068]. 543 DASL servers MUST include the DASL header in the OPTIONS 544 response. This header identifies the search grammars supported by 545 that resource. 547 3.2. The DASL Response Header 549 DASLHeader = "DASL" ":" Coded-URL-List 550 Coded-URL-List : Coded-URL [ �,� Coded-URL-List ] 551 Coded-URL ; defined in section 8.4 of [WEBDAV] 553 The DASL response header indicates server support for a query 554 grammar in the OPTIONS method. The value is a URI that indicates 555 the type of grammar. This header MAY be repeated. 557 For example: 559 DASL: 560 DASL: 561 DASL: 563 3.3. Example: Grammar Discovery 565 This example shows that the server supports search on the 566 /somefolder resource with the following query grammars: 567 http://foo.bar.com/syntax1 and http://akuma.com/syntax2. 569 >> Request 571 OPTIONS /somefolder HTTP/1.1 572 Connection: Close 573 Host: ryu.com 574 >> Response 576 HTTP/1.1 200 OK 577 Date: Tue, 20 Jan 1998 20:52:29 GMT 578 Connection: close 579 Accept-Ranges: none 580 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 581 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH 582 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 583 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH 584 DASL: 585 DASL: 587 4. QUERY SCHEMA DISCOVERY: QSD 589 Servers MAY support the discovery of the schema for a query 590 grammar. 592 The DASL response header provides means for clients to discover 593 the set of query grammars supported by a resource. This alone is 594 not sufficient information for a client to generate a query. For 595 example, the DAV:basicsearch grammar defines a set of queries 596 consisting of a set of operators applied to a set of properties 597 and values, but the grammar itself does not specify which 598 properties may be used in the query. QSD for the 599 DAV:basicsearch grammar allows a client to discover the set of 600 properties that are searchable, selectable, and sortable. 601 Moreover, although the DAV:basicsearch grammar defines a minimal 602 set of operators, it is possible that a resource might support 603 additional operators in a query. For example, a resource might 604 support a optional operator that can be used to express content- 605 based queries in a proprietary syntax. QSD allows a client to 606 discover these operators and their syntax. The set of 607 discoverable quantities will differ from grammar to grammar, but 608 each grammar can define a means for a client to discover what can 609 be discovered. 611 In general, the schema for a given query grammar depends on both 612 the resource (the arbiter) and the scope. A given resource might 613 have access to one set of properties for one potential scope, and 614 another set for a different scope. For example, consider a 615 server able to search two distinct collections, one holding 616 cooking recipes, the other design documents for nuclear weapons. 617 While both collections might support properties such as author, 618 title, and date, the first might also define properties such as 619 calories and preparation time, while the second defined 620 properties such as yield and applicable patents. Two distinct 621 arbiters indexing the same collection might also have access to 622 different properties. For example, the recipe collection 623 mentioned above might also indexed by a value-added server that 624 also stored the names of chefs who had tested the recipe. Note 625 also that the available query schema might also depend on other 626 factors, such as the identity of the principal conducting the 627 search, but these factors are not exposed in this protocol. 629 Each query grammar supported by DASL defines its own syntax for 630 expressing the possible query schema. A client retrieves the 631 schema for a given query grammar on an arbiter resource with a 632 given scope by invoking the SEARCH method on that arbiter, with 633 that grammar and scope, with a query whose DAV:select element 634 includes the DAV:queryschema property. This property is defined 635 only in the context of such a search, a server SHOULD not treat 636 it as defined in the context of a PROPFIND on the scope. The 637 content of this property is an XML element whose name and syntax 638 depend upon the grammar, and whose value may (and likely will) 639 vary depending upon the grammar, arbiter, and scope. 641 The query schema for DAV:basicsearch is defined in section 5.19. 643 4.1. The DAV:queryschema Property 645 647 4.1.1. Example of query schema discovery 649 In this example, the arbiter is recipes.com, the grammar is 650 DAV:basicsearch, the scope is also recipes.com. 652 SEARCH / HTTP/1.1 653 Host: recipes.com 654 Content-Type: application/xml 655 Connection: Close 656 Content-Length: xxx 658 659 660 661 662 663 665 http://recipes.com 667 668 670 Response: 672 HTTP/1.1 207 Multistatus 673 Content-Type: application/xml 674 Content-Length: xxx 676 677 678 679 http://recipes.com 680 681 682 683 684 See section 5.19.9 for actual contents 685 686 687 688 HTTP/1.1 200 Okay 689 690 691 693 5. THE DAV:BASICSEARCH GRAMMAR 695 5.1. Introduction 697 DAV:basicsearch uses an extensible XML syntax that allows clients 698 to express search requests that are generally useful for WebDAV 699 scenarios. DASL-extended servers MUST accept this grammar, and 700 MAY accept others grammars. 702 DAV:basicsearch has several major components: DAV:select, 703 DAV:from, DAV:where, DAV:orderby, and DAV:limit. DAV:select 704 provides the result record definition. DAV:from defines the 705 scope. DAV:where defines the criteria. DAV:orderby defines the 706 sort order of the result set. DAV:limit provides constraints on 707 the query as a whole. 709 5.2. The DAV:basicsearch DTD 711 714 716 717 719 720 721 722 723 725 729 731 733 734 736 737 740 741 744 745 748 749 752 753 756 757 759 760 761 763 764 767 768 770 771 773 5.2.1. Example Query 775 This query retrieves the content length values for all resources 776 located under the server's "/container1/" URI namespace whose 777 length exceeds 10000. 779 780 781 782 783 784 785 786 /container1/ 787 infinity 788 789 790 791 792 793 10000 794 795 796 797 798 799 800 801 802 803 805 5.3. DAV:select 807 DAV:select defines the result record. This document defines two 808 possible values: DAV:allprop and DAV:prop, both defined in 809 [WebDAV]. 811 If the value is DAV:allprop, the result record for a given 812 resource includes all the properties for that resource. 814 If the value is DAV:prop, then the result record for a given 815 resource includes only those properties named by the DAV:prop 816 element. Each property named by the DAV:prop element must be 817 referenced in the Multistatus response. 819 The rules governing the status codes for each property match 820 those of the PROPFIND method defined in [WebDAV]. 822 5.4. DAV:from 824 DAV:from defines the query scope. This contains exactly one 825 DAV:scope element. The scope element contains a mandatory 826 DAV:href element and an optional DAV:depth element. 828 DAV:href indicates the URI for a collection to use as a scope. 830 When the scope is a collection, if DAV:depth is "1", the search 831 includes the members of the collection. When it is "infinity", 832 the search includes all recursive members of the 833 collection.8.5.1. 835 5.4.1. Relationship to the Request-URI 837 If the DAV:scope element is an absolute URI, the scope is exactly 838 that URI. 840 If the DAV:scope element is a relative URI, the scope is taken to 841 be relative to the request-URI. 843 5.4.2. Scope 845 A Scope can be an arbitrary URI. 847 Servers, of course, may support only particular scopes. This may 848 include limitations for particular schemes such as "http:" or 849 "ftp:" or certain URI namespaces. 851 If a scope is given that is not supported the server MUST respond 852 with a 400 status code that includes a Multistatus error. A 853 scope in the query appears as a resource in the response and must 854 include an appropriate status code indicating its validity with 855 respect to the search arbiter. 857 Example: 859 HTTP/1.1 400 Bad Request 860 Content-Type: text/xml 861 Content-Length: 428 863 864 866 867 http://www.foo.com/scope1 868 HTTP/1.1 502 Bad Gateway 869 871 873 This example shows the response if there is a scope error. The 874 response provides a Multistatus with a status for the scope. In 875 this case, the scope cannot be reached because the server cannot 876 search another server (502). 878 5.5. DAV:where 880 DAV:where element defines the search condition for inclusion of 881 resources in the result set. The value of this element is an XML 882 element that defines a search operator that evaluates to one of 883 the Boolean truth values TRUE, FALSE, or UNKNOWN. The search 884 operator contained by DAV:where may itself contain and evaluate 885 additional search operators as operands, which in turn may 886 contain and evaluate additional search operators as operands, 887 etc. recursively. 889 5.5.1. Use of Three-Valued Logic in Queries 891 Each operator defined for use in the where clause that returns a 892 Boolean value MUST evaluate to TRUE, FALSE, or UNKNOWN. The 893 resource under scan is included as a member of the result set if 894 and only if the search condition evaluates to TRUE. 896 Consult Appendix A for details on the application of three-valued 897 logic in query expressions. 899 5.5.2. Handling Optional operators 901 If a query provides an operator that is not supported by the 902 server, then the server MUST respond with a 422 (Unprocessable 903 Entity) status code. 905 5.5.3. Treatment of NULL Values 907 If a SEARCH PROPFIND for a property value would yield a 404 or 908 403 response for that property, then that property is considered 909 NULL. 911 NULL values are "less than" all other values in comparisons. 913 Empty strings (zero length strings) are not NULL values. An 914 empty string is "less then" a string with length greater than 915 zero. 917 The DAV:isdefined operator is defined to test if the value of a 918 property is NULL. 920 5.5.4. Example: Testing for Equality 922 The example shows a single operator (DAV:eq) applied in the 923 criteria. 925 926 927 928 100 929 930 932 5.5.5. Example: Relative Comparisons 934 The example shows a more complex operation involving several 935 operators (DAV:and, DAV:eq, DAV:gt) applied in the criteria. This 936 DAV:where expression matches those resources that are 937 "image/gifs" over 4K in size. 939 940 941 942 943 image/gif 944 945 946 947 4096 948 949 950 951 5.6. DAV:orderby 953 The DAV:orderby element specifies the ordering of the result set. 954 It contains one or more DAV:order elements, each of which 955 specifies a comparison between two items in the result set. 956 Informally, a comparison specifies a test that determines whether 957 one resource appears before another in the result set. 958 Comparisons are applied in the order they occur in the 959 DAV:orderby element, earlier comparisons being more significant. 961 The comparisons defined here use only a single property from each 962 resource, compared using the same ordering as the DAV:lt operator 963 (ascending) or DAV:gt operator (descending). If neither direction 964 is specified, the default is DAV:ascending. 966 In the context of the DAV:orderby element, null values are 967 considered to collate before any actual (i.e., non null) value, 968 including strings of zero length (as in ANSI standard SQL, c.f., 969 ANSI X3.135-1992). 971 5.6.1. Comparing Natural Language Strings. 973 Comparisons on strings take into account the language defined for 974 that property. Clients MAY specify the language using the 975 xml:lang attribute. If no language is specified either by the 976 client or defined for that property by the server or if a 977 comparison is performed on strings of two different languages, 978 the results are undefined. 980 The DAV:casesensitive attribute may be used to indicate case- 981 sensitivity for comparisons. 983 5.6.2. Example of Sorting 985 This sort orders first by last name of the author, and then by 986 size, in descending order, so that the largest works appear 987 first. 989 990 991 992 993 994 995 996 997 998 1000 5.7. Boolean Operators: DAV:and, DAV:or, and DAV:not 1002 The DAV:and operator performs a logical AND operation on the 1003 expressions it contains. 1005 The DAV:or operator performs a logical OR operation on the values 1006 it contains. 1008 The DAV:not operator performs a logical NOT operation on the 1009 values it contains. 1011 5.8. DAV:eq 1013 The DAV:eq operator provides simple equality matching on property 1014 values. 1016 The DAV:casesensitive attribute may be used with this element. 1018 5.9. DAV:lt, DAV:lte, DAV:gt, DAV:gte 1020 The DAV:lt, DAV:lte, DAV:gt, and DAV:gte operators provide 1021 comparisons on property values. The DAV:casesensitive attribute 1022 may be used with these elements. 1024 5.10. DAV:literal 1026 DAV:literal allows literal values to be placed in an expression. 1028 Because white space in literal values is significant to in 1029 comparisons, DAV:literal makes use of the xml:space attribute to 1030 identify this significance. The default value of this attribute 1031 for DAV:literal is preserve. Consult section 2.10 of [XML] for 1032 more information on the use of this attribute. 1034 5.11. DAV:isdefined 1036 The DAV:isdefined operator allows clients to determine whether a 1037 property is defined on a resource on a resource. The meaning of 1038 "defined on a resource" is found in section 5.5.3. 1040 Example: 1042 1043 1044 1046 The DAV:isdefined operator is optional. 1048 5.12. DAV:like 1050 The DAV:like is an optional operator intended to give simple 1051 wildcard-based pattern matching ability to clients. 1053 The operator takes two arguments. 1055 The first argument is a DAV:prop element identifying a single 1056 property to evaluate. 1058 The second argument is a DAV:literal element that gives the 1059 pattern matching string. 1061 5.12.1. Syntax for the Literal Pattern 1063 Pattern := [wildcard] 0*( text [wildcard] ) 1064 wildcard := exactlyone | zeroormore 1065 text := 1*( | escapesequence ) 1066 exactlyone : = "?" 1067 zeroormore := "%" 1068 escapechar := "\" 1069 escapesequence := "\" ( exactlyone | zeroormore | escapechar ) 1071 The value for the literal is composed of wildcards separated by 1072 segments of text. Wildcards may begin or end the literal. 1073 Wildcards may not be adjacent. 1075 The "?" wildcard matches exactly one character. 1077 The "%" wildcard matches zero or more characters 1079 The "\" character is an escape sequence so that the literal can 1080 include "?" and "%". To include the "\" character in the 1081 pattern, the escape sequence "\\" is used.. 1083 5.12.2. Example of DAV:like 1085 This example shows how a client might use DAV:like to identify 1086 those resources whose content type was a subtype of image. 1088 1089 1090 1091 image% 1092 1093 1095 5.13. DAV:contains 1097 The DAV:contains operator is an optional operator that provides 1098 content-based search capability. This operator implicitly 1099 searches against the text content of a resource, not against 1100 content of properties. The DAV:contains operator is intentionally 1101 not overly constrained, in order to allow the server to do the 1102 best job it can in performing the search. 1104 The DAV:contains operator evaluates to a Boolean value. It 1105 evaluates to TRUE if the content of the resource satisfies the 1106 search. Otherwise, It evaluates to FALSE. 1108 Within the DAV:contains XML element, the client provides a 1109 phrase: a single word or whitespace delimited sequence of words. 1110 Servers MAY ignore punctuation in a phrase. Case-sensitivity is 1111 left to the server. 1113 The following things may or may not be done as part of the 1114 search: Phonetic methods such as �soundex� may or may not be 1115 used. Word stemming may or may not be performed. Thesaurus 1116 expansion of words may or may not be done. Right or left 1117 truncation may or may not be performed. The search may be case 1118 insensitive or case sensitive. The word or words may or may not 1119 be interpreted as names. Multiple words may or may not be 1120 required to be adjacent or "near" each other. Multiple words may 1121 or may not be required to occur in the same order. Multiple words 1122 may or may not be treated as a phrase. The search may or may not 1123 be interpreted as a request to find documents "similar" to the 1124 string operand. 1126 The DAV:score property is intended to be useful to rank documents 1127 satisfying the DAV:Contains operator. 1129 5.13.1. Example 1131 The example below shows a search for the phrase �Peter Forsberg�. 1133 Depending on its support for content-based searching, a server 1134 MAY treat this as a search for documents that contain the words 1135 �Peter� and �Forsberg�. 1137 1138 Peter Forsberg 1139 1141 5.13.2. Example 1143 The example below shows a search for resources that contain 1144 �Peter� and �Forsberg�. 1146 1147 1148 Peter 1149 Forsberg 1150 1151 1153 5.14. The DAV:limit XML Element 1155 1157 The DAV:limit XML element contains requested limits from the 1158 client to limit the size of the reply or amount of effort 1159 expended by the server. 1161 5.15. The DAV:nresults XML Element 1163 ;only digits 1165 The DAV:nresults XML element contains a requested maximum number 1166 of records to be returned in a reply. The server MAY disregard 1167 this limit. The value of this element is an integer. 1169 5.16. The DAV:casesensitive XML attribute 1171 The DAV:casesensitive attribute allows clients to specify case- 1172 sensitive or case-insensitive behavior for DAV:basicsearch 1173 operators. 1175 The possible values for DAV:casesensitive are "1" or "0". The "1" 1176 value indicates case-sensitivity. The "0" value indicates case- 1177 insensitivity. The default value is server-specified. 1179 Support for the DAV:casesensitive is optional. A server should 1180 respond with an error 422 if the DAV:casesensitive attribute is 1181 used but cannot be supported. 1183 5.17. The DAV:score Property 1185 1187 The DAV:score XML element is a synthetic property whose value is 1188 defined only in the context of a query result where the server 1189 computes a score, e.g. based on relevance. It may be used in 1190 DAV:select or DAV:orderby elements. Servers SHOULD support this 1191 property. The value is a string representing the score, an 1192 integer from zero to 10000 inclusive, where a higher value 1193 indicates a higher score (e.g. more relevant). 1195 Clients should note that, in general, it is not meaningful to 1196 compare the numeric values of scores from two different queries 1197 unless both were executed by the same underlying search system on 1198 the same collection of resources. 1200 5.18. The DAV:iscollection Property 1202 1204 The DAV:iscollection XML element is a synthetic property whose 1205 value is defined only in the context of a query. 1207 The property is TRUE (the literal string "1") of a resource if 1208 and only if a PROPFIND of the DAV:resourcetype property for that 1209 resource would contain the DAV:collection XML element. The 1210 property is FALSE (the literal string "0") otherwise. 1212 Rationale: This property is provided in lieu of defining generic 1213 structure queries, which would suffice for this and for many more 1214 powerful queries, but seems inappropriate to standardize at this 1215 time. 1217 5.18.1. Exampe of DAV:iscollection 1219 This example shows a search criterion that picks out all and only 1220 the resources in the scope that are collections. 1222 1223 1224 1225 1 1226 1227 1229 5.19. Query Schema for DAV:basicsearch 1231 The DAV:basicsearch grammar defines a search criteria that is a 1232 Boolean-valued expression, and allows for an arbitrary set of 1233 properties to be included in the result record. The result set 1234 may be sorted on a set of property values. Accordingly the DTD 1235 for schema discovery for this grammar allows the server to 1236 express: 1238 - the set of properties that may be either searched, returned, or 1239 used to sort, and a hint about the data type of such properties 1241 - the set of optional operators defined by the resource. 1243 5.19.1. DTD for DAV:basicsearch QSD 1245 1246 1247 1248 1249 1250 1251 1253 The DAV:properties element holds a list of descriptions of 1254 properties. 1256 The DAV:operators element describes the optional operators that 1257 may be used in a DAV:where element. 1259 5.19.2. DAV:propdesc Element 1261 Each instance of a DAV:propdesc element describes the property or 1262 properties in the DAV:prop element it contains. All subsequent 1263 elements are descriptions that apply to those properties. All 1264 descriptions are optional and may appear in any order. Servers 1265 SHOULD support all the descriptions defined here, and MAY define 1266 others. 1268 DASL defines eight descriptions. The first group (DAV:datatype, 1269 DAV:searchable, DAV:selectable, DAV:sortable, and 1270 DAV:casesensitive) provide a hints about the property value, and 1271 may be useful to a user interface prompting for a value. The 1272 second group identify portions of the query (DAV:where, 1273 DAV:select, and DAV:orderby). If a property has a description 1274 for a section, then the server MUST allow the property to be 1275 used in that section. These descriptions are optional. If a 1276 property does not have such a description, or is not described at 1277 all, then the server MAY still allow the property to be used in 1278 the corresponding section. 1280 5.19.3. The DAV:datatype Property Description 1282 The DAV:datatype element contains a single XML element that 1283 provides a hint about the domain of the property, which may be 1284 useful to a user interface prompting for a value to be used in a 1285 query. The namespace for expressing a DASL defined data type is 1286 "urn:uuid:C2F41010-65B3-11d1-A29F-00AA00C14882/". 1288 1290 DASL defines the following data type elements: 1292 NAME CONTENTS EXAMPLE 1294 boolean 1 1295 0 1297 string Foobar 1299 int -259 1300 23 1302 float .314159265358979E+1 1303 5.33 1305 dateTime.tz 1994-11-05T08:15:5Z 1307 If the data type of a property is not given, then the data type 1308 defaults to string. 1310 5.19.4. The DAV:searchable Property Description 1312 1314 If this element is present, then the server MUST allow this 1315 property to appear within a DAV:where element where an operator 1316 allows a property. Allowing a search does not mean that the 1317 property is guaranteed to be defined on every resource in the 1318 scope, it only indicates the server's willingness to check. 1320 5.19.5. The DAV:selectable Property Description 1322 1324 This element indicates that the property may appear in the 1325 DAV:select element. 1327 5.19.6. The DAV:sortable Property Description 1329 This element indicates that the property may appear in the 1330 DAV:orderby element 1332 1334 5.19.7. The DAV:casesensitive Property Description 1336 This element only applies to properties whose data type is 1337 "string" as per the DAV:datatype property description. Its 1338 presence indicates that compares performed for searches, and the 1339 comparisons for ordering results on the string property will be 1340 case sensitive. (The default is case insensitive.) 1342 1344 5.19.8. The DAV:operators XML Element 1346 The DAV:operators element describes every optional operator 1347 supported in a query. (Mandatory operators are not listed since 1348 they are mandatory and permit no variation in syntax.). All 1349 optional operators that are supported MUST be listed in the 1350 DAV:operators element. The listing for an operator consists of 1351 the operator (as an empty element), followed by one element for 1352 each operand. The operand MUST be either DAV:operand_property or 1353 DAV:operand_literal, which indicate that the operand in the 1354 corresponding position is a property or a literal value, 1355 respectively. If an operator is polymorphic (allows more than 1356 one operand syntax) then each permitted syntax MUST be listed 1357 separately. 1359 1362 5.19.9. Example of Query Schema for DAV:basicsearch 1364 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1391 This response lists four properties. The datatype of the last 1392 three properties is not given, so it defaults to string. All are 1393 selectable, and the first three may be searched. All but the 1394 last may be used in a sort. Of the optional DAV operators, 1395 DAV:isdefined and DAV:like are supported. 1397 Note: The schema discovery defined here does not provide for 1398 discovery of supported values of the DAV:casesensitive attribute. 1399 This may require that the reply also list the mandatory 1400 operators. 1402 6. INTERNATIONALIZATION CONSIDERATIONS 1404 Clients have the opportunity to tag properties when they are 1405 stored in a language. The server SHOULD read this language- 1406 tagging by examining the xml:lang attribute on any properties 1407 stored on a resource. 1409 The xml:lang attribute specifies a nationalized collation 1410 sequence when properties are compared. 1412 Comparisons when this attribute differs have undefined order. 1414 7. SECURITY CONSIDERATIONS 1416 This section is provided to detail issues concerning security 1417 implications of which DASL applications need to be aware. All of 1418 the security considerations of HTTP/1.1 also apply to DASL. In 1419 addition, this section will include security risks inherent in 1420 searching and retrieval of resource properties and content. 1422 A query must not allow one to retrieve information about values 1423 or existence of properties that one could not obtain via 1424 PROPFIND. (e.g. by use in DAV:orderby, or in expressions on 1425 properties.) 1427 Server should prepare for denial of service attacks. For example 1428 a client may issue a query for which the result set is expensive 1429 to calculate or transmit because many resources match or must be 1430 evaluated. 1432 8. SCALABILITY 1434 Query grammars are identified by URIs. Applications SHOULD not 1435 attempt to retrieve these URIs even if they appear to be 1436 retrievable (for example, those that begin with "http://") 1438 9. AUTHENTICATION 1440 Authentication mechanisms defined in WebDAV will also apply to 1441 DASL. 1443 10. IANA CONSIDERATIONS 1445 This document uses the namespace defined by [WebDAV] for XML 1446 elements. All other IANA considerations mentioned in [WebDAV] 1447 also applicable to DASL 1449 11. COPYRIGHT 1451 To be supplied. 1453 12. INTELLECTUAL PROPERTY 1455 To be supplied. 1457 13. REFERENCES 1459 [DASLREQ] J. Davis, S. Reddy, J. Slein, "Requirements for DAV 1460 Searching and Locating", September 3 1998, internet-draft, work- 1461 in-progress, draft-davis-dasl-requirements-00.txt 1463 [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. 1464 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, 1465 U.C. Irvine, DEC, MIT/LCS, January 1997. 1467 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 1468 Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1469 1997. 1471 [WebDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D. 1472 Jenson, "Extensions for Distributed Authoring on the World Wide 1473 Web", November 16 1998, internet-draft, work-in-progress, draft- 1474 ietf-webdav-protocol-10.txt. 1476 [XML] T. Bray, J. Paoli, C. M. Sperberg-McQueen, "Extensible 1477 Markup Language (XML) 1.0", September 16, 1998, W3C 1478 Recommendation. 1480 [XMLNS] T. Bray, D. Hollander, A. Layman, "Namespaces in XML", 1481 November, 1998, W3C Proposed Recommendation. 1482 http://www.w3.org/TR/PR-xml-names 1483 14. AUTHOR'S ADDRESSES 1485 Saveen Reddy 1486 Microsoft 1487 One Microsoft Way 1488 Redmond WA, 9085-6933 1489 Email:saveenr@microsoft.com 1491 Dale Lowry 1492 Novell 1493 1555 N. Technology Way 1494 M/S ORM-M-314 1495 Orem, UT 84097 1496 Email: dlowry@novell.com 1498 Surendra Reddy 1499 Oracle Corporation 1500 600 Oracle Parkway, M/S 6op3, 1501 Redwoodshores, CA 94065 1502 Email: skreddy@us.oracle.com 1503 Phone:(650) 506 5441 1505 Rick Henderson 1506 Netscape 1507 Email: rickh@netscape.com 1509 Jim Davis 1510 Xerox PARC 1511 3333 Coyote Hill Road 1512 Palo Alto CA 94304 1513 650-812-4301 1514 Email: jdavis@parc.xerox.com 1516 Alan Babich 1517 Filenet 1518 3565 Harbor Blvd. 1519 Costa Mesa, CA 92626 1520 714-966-3403 1521 Email: ababich@filenet.com 1523 15. APPENDICES 1525 Appendix A Three-Valued Logic in DAV:basicsearch 1527 ANSI standard three valued logic is used when evaluating the 1528 search condition (as defined in the ANSI standard SQL 1529 specifications, for example in ANSI X3.135-1992, section 8.12, 1530 pp. 188-189, section 8.2, p. 169, General Rule 1)a), etc.). 1532 ANSI standard three valued logic is undoubtedly the most widely 1533 practiced method of dealing with the issues of properties in the 1534 search condition not having a value (e.g., being null or not 1535 defined) for the resource under scan, and with undefined 1536 expressions in the search condition (e.g., division by zero, 1537 etc.). Three valued logic works as follows. 1539 Undefined expressions are expressions for which the value of the 1540 expression is not defined. Undefined expressions are a completely 1541 separate concept from the truth value UNKNOWN, which is, in fact, 1542 well defined. Property names and literal constants are considered 1543 expressions for purposes of this section. If a property in the 1544 current resource under scan has not been set to a value (either 1545 because the property is not defined for the current resource, or 1546 because it is null for the current resource), then the value of 1547 that property is undefined for the resource under scan. DASL 1.0 1548 has no arithmetic division operator, but if it did, division by 1549 zero would be an undefined arithmetic expression. 1551 If any subpart of an arithmetic, string, or datetime 1552 subexpression is undefined, the whole arithmetic, string, or 1553 datetime subexpression is undefined. 1555 There are no manifest constants to explicitly represent undefined 1556 number, string, or datetime values. 1558 Since a Boolean value is ultimately returned by the search 1559 condition, arithmetic, string, and datetime expressions are 1560 always arguments to other operators. Examples of operators that 1561 convert arithmetic, string, and datetime expressions to Boolean 1562 values are the six relational operators ("greater than", "less 1563 than", "equals", etc.). If either or both operands of a 1564 relational operator have undefined values, then the relational 1565 operator evaluates to UNKNOWN. Otherwise, the relational operator 1566 evaluates to TRUE or FALSE, depending upon the outcome of the 1567 comparison. 1569 The Boolean operators DAV:and, DAV:or and DAV:not are evaluated 1570 according to the following rules: 1572 UNKNOWN and UNKNOWN = UNKNOWN 1574 UNKNOWN or UNKKNOWN = UNKNOWN 1576 not UNKNOWN = UNKNOWN 1578 UNKNOWN and TRUE = UNKNOWN 1580 UNKNOWN and FALSE = FALSE 1582 UNKNOWN and UNKNOWN = UNKNOWN 1584 UNKNOWN or TRUE = TRUE 1586 UNKNOWN or FALSE = UNKNOWN 1588 UNKNOWN or UNKNOWN = UNKNOWN 1589 16. CHANGE HISTORY 1591 Feb 14, 1998 1593 Initial Draft 1595 Feb 28, 1998 1597 Referring to DASL as an extension to HTTP/1.1 rather than DAV 1599 Added new sections "Notational Conventions", "Protocol Model", 1600 "Security Considerations" 1602 Changed section 3 to "Elements of Protocol" 1604 Added some stuff to introduction 1606 Added "result set" terminology 1608 Added "IANA Considerations". 1610 Mar 9, 1998 1612 Moved sub-headings of "Elements of Protocol" to first level and 1613 removed "Elements of Protocol" Heading. 1615 Added an sentence in introduction explaining that this is a 1616 "sketch" of a protocol. 1618 Mar 11, 1998 1620 Added orderby, data typing, three valued logic, query schema 1621 property, and element definitions for schema for basicsearch. 1623 April 8, 1998 1625 - made changes based on last week�s DASL BOF. 1627 May 8, 1998 1629 Removed most of DAV:searcherror; converted to DAV:searchredirect 1631 Altered DAV:basicsearch grammar to use avoid use of ANY in DTD 1633 June 17, 1998 1635 -Added details on Query Schema Discovery 1637 -Shortened list of data types 1639 June 23, 1998 1641 moved data types before change history 1642 rewrote the data types section 1644 removed the casesensitive element and replace with the 1645 casesensitive attribute 1647 added the casesensitive attribute to the DTD for all operations 1648 that might work on a string 1650 Jul 20, 1998 1652 A series of changes. See Author�s meeting minutes for details. 1654 July 28, 1998 1656 Changes as per author's meeting. QSD uses SEARCH, not PROPFIND. 1658 Moved text around to keep concepts nearby. 1660 Boolean literals are 1 and 0, not T and F. 1662 contains changed to contentspassthrough. 1664 Renamed rank to score. 1666 July 28, 1998 1668 Added Dale Lowry as Author 1670 September 4, 1998 1672 Added 422 as response when query lists unimplemented operators. 1674 dav:literal declares a default value for xml:space, 'preserve' 1675 (see XML spec, section 2.10) 1677 moved to new XML namespace syntax 1679 September 22, 1998 1681 Changed "simplesearch" to "basicsearch" 1683 Changed isnull to isdefined 1685 Defined NULLness as having a 404 or 403 response 1687 used ENTITY syntax in DTD 1689 Added redirect 1691 October 9, 1998 1693 Fixed a series of typographical and formatting errors. 1695 Modified the section of three-valued logic to use a table rather 1696 than a text description of the role of UNKNOWN in expressions. 1698 November 2, 1998 1700 Added the DAV:contains operator. 1702 Removed the DAV:contentpassthrough operator. 1704 November 18, 1998 1706 Various author comments for submission