idnits 2.17.1 draft-reddy-dasl-protocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == There is 1 instance 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 18 longer pages, the longest (page 4) being 65 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 124 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'WebDAV' is mentioned on line 299, but not defined -- No information found for draft-reddy-dasl-requirements - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'DASLREQ' ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) == Outdated reference: A later version (-10) exists of draft-ietf-webdav-protocol-06 Summary: 9 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Saveen Reddy, Microsoft 2 draft-reddy-dasl-protocol-00.txt Del Jensen, Novell 3 Mar, 1998 Surendra Reddy, Oracle 4 Expires Aug, 1998 Rick Henderson, Netscape 5 Jim Davis, Xerox 6 Alan Babich, Filenet 8 DAV Searching and Locating 10 Status of this Memo 12 This document is an Internet draft. Internet drafts are working documents 13 of the Internet Engineering Task Force (IETF), its areas and its working 14 groups. Note that other groups may also distribute working information as 15 Internet drafts. 17 Internet Drafts are draft documents valid for a maximum of six months and 18 can be updated, replaced or obsoleted by other documents at any time. It 19 is inappropriate to use Internet drafts as reference material or to cite 20 them as other than as "work in progress". 22 To learn the current status of any Internet draft please check the "lid- 23 abstracts.txt" listing contained in the Internet drafts shadow directories 24 on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific 25 Rim), ds.internic.net (US East coast) or ftp.isi.edu (US West coast). 26 Further information about the IETF can be found at URL: 27 http://www.ietf.org/ 29 Distribution of this document is unlimited. Please send comments to the 30 Distributed Authoring and Versioning (WEBDAV) working group at , which may be joined by sending a message with 32 subject "subscribe" to . 34 Discussions of the WEBDAV working group are archived at 35 . 37 Abstract 39 This document specifies a set of methods, headers, and content-types 40 composing DASL, an application of the HTTP/1.1 protocol to efficiently 41 search for DAV resources based upon a set of client-supplied criteria. 43 INTERNET DRAFT DAV Searching and Locating 1 44 DAV Searching and Locating March 1997 46 Table of Contents 48 1 Introduction........................................................4 49 1.1 Relationship to DAV...............................................4 50 1.2 Terms.............................................................4 51 1.3 Notational Conventions............................................4 52 1.4 DASL in Operation.................................................4 53 2 The SEARCH Method...................................................5 54 2.1 Overview..........................................................5 55 2.2 Query Transport vs. Query Semantics and Query Grammar.............5 56 2.3 The Request.......................................................5 57 2.3.1 The Request-URI as Search Arbiter.............................5 58 2.3.2 The Request Body..............................................5 59 2.4 The Response......................................................5 60 2.5 Response Extensions...............................................5 61 2.6 Example...........................................................6 62 2.7 The searchrequest XML Elements....................................7 63 2.7.1 searchrequest XML Element.....................................7 64 2.7.2 type XML Element..............................................7 65 2.7.3 query XML Element.............................................7 66 3 Search Grammar Discovery : OPTIONS..................................8 67 3.1 Overview..........................................................8 68 3.2 Request...........................................................8 69 3.3 Response..........................................................8 70 3.4 Example...........................................................8 71 4 The DASL Response Header............................................9 72 4.1 Overview..........................................................9 73 4.2 Syntax............................................................9 74 4.3 Example...........................................................9 75 5 The DASL simplesearch grammar......................................10 76 5.1 Introduction.....................................................10 77 5.2 The Basic Query..................................................10 78 5.3 Example..........................................................10 79 5.4 The select XML Element...........................................11 80 5.4.1 Access to properties.........................................11 81 5.5 The from XML element.............................................11 82 5.6 The where XML Element............................................12 83 5.6.1 Overview.....................................................12 84 5.6.2 Syntax.......................................................12 85 5.7 The Comparison Operators.........................................13 86 5.8 The Contains XML Element.........................................13 87 5.8.1 Example......................................................13 88 5.9 Example..........................................................13 89 5.10 Typing..........................................................14 90 5.11 Variants........................................................14 91 5.12 Versioning......................................................14 92 5.13 Security Considerations.........................................14 93 5.14 Authentication..................................................14 94 5.15 Internationalized Content.......................................14 95 5.16 IANA Considerations.............................................15 96 6 Change History.....................................................16 98 INTERNET DRAFT DAV Searching and Locating 2 99 DAV Searching and Locating March 1997 101 7 References.........................................................17 102 8 Author's Addresses.................................................18 104 INTERNET DRAFT DAV Searching and Locating 3 105 DAV Searching and Locating March 1997 107 1 Introduction 109 This document is an early sketch of the DAV Searching and Locating (DASL) 110 protocol. This document does not imply endorsement by the authors for the 111 protocol described. This is a "strawman" for the purposes of discussion. 113 It will describe a set of methods, headers and content-types forming an 114 application of HTTP/1.1 that allows clients to perform searching 115 operations on the properties and content of DAV resources. DASL is a 116 lightweight search protocol to transport queries and result sets and 117 allows clients to make use of server-side search facilities, the 118 motivation for which is described by [DASLREQ]. 120 DASL includes the SEARCH method, the DASL response header for use with the 121 OPTIONS method, the searchrequest XML entity, and the simplesearch query 122 grammar. 124 1.1 Relationship to DAV 126 DASL relies on the resource and property model defined by [WEBDAV]. DASL 127 does not alter this model, but rather allows clients to access DAV-modeled 128 resources through server-side search. 130 1.2 Terms 132 This draft uses the terms defined in [RFC2068], [WEBDAV], and [DASLREQ]. 134 1.3 Notational Conventions 136 The augmented BNF used by this document to describe protocol elements is 137 exactly the same as the one described in Section 2.1 of [RFC2068]. Because 138 this augmented BNF uses the basic production rules provided in Section 2.2 139 of [RFC2068], those rules apply to this document as well. 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 143 "OPTIONAL" in this document are to be interpreted as described in 144 [RFC2119]. 146 1.4 DASL in Operation 148 As an application of HTTP/1.1, DASL follows the HTTP/1.1 request/response 149 chain. A client invokes the SEARCH method and includes a text/xml entity 150 containing a query. The server responds with a text/xml entity that 151 contains the corresponding result set. 153 It is an objective of DASL to minimize the complexity of clients so as to 154 facilitate widespread deployment of applications capable of utilizing the 155 DASL search mechanisms. 157 INTERNET DRAFT DAV Searching and Locating 4 158 DAV Searching and Locating March 1997 160 2 The SEARCH Method 162 2.1 Overview 164 The client invokes the SEARCH method to initiate a server-side search. The 165 text/xml body of the request defines the query. A successful response is a 166 text/xml entity matching the [WEBDAV] PROPFIND response. 168 2.2 Query Transport vs. Query Semantics and Query Grammar 170 The SEARCH method provides a framework for the transmission of a search 171 request. It does not define the grammar or semantics of any query that is 172 transmitted. That is, the SEARCH method is a transport mechanism for the 173 query. Different query grammars can be transmitted, each defining its own 174 search semantics. 176 2.3 The Request 178 The client invokes the SEARCH method on the resource named by the Request- 179 URI. 181 2.3.1 The Request-URI as Search Arbiter 183 The Request-URI identifies a resource that acts as an arbiter for the 184 search. This resource is the one performing the search but not necessarily 185 the resource that is being searched. That is, there is no implicit 186 relationship between the Request-URI and the search scope. 188 Query grammars MUST explicitly define the relationship between the search 189 scope and the request-URI. Query grammars may, for example, make the 190 request-URI correspond exactly to the search scope. 192 2.3.2 The Request Body 194 The client MUST include a text/xml request body containing the 195 searchrequest XML element. 197 The searchrequest XML element identifies the query grammar being used and 198 defines the criteria, the result record, and any other attributes for the 199 search. 201 2.4 The Response 203 If successful, the server MUST respond with a 217 Multistatus response 204 matching that of PROPFIND. Each resource listed in the Multistatus 205 response MUST meet the criteria defined by the corresponding search 206 request. 208 2.5 Response Extensions 210 INTERNET DRAFT DAV Searching and Locating 5 211 DAV Searching and Locating March 1997 213 Query grammars MUST define how the response matches the PROPFIND response. 214 Responses are free to include more information than PROPFIND responses so 215 long as the extra information does not invalidate the PROPFIND response. 217 2.6 Example 219 This example demonstrates a simple query and its response. The query 220 requests a recursive search of the entire server. No criteria are given in 221 the query, so every resource specified in the scope matches the criteria. 222 In this example, only a single resource exists on the server. The response 223 uses the same format as the PROPFIND result. 225 >> Request 227 SEARCH / HTTP/1.1 228 Host: ryu.com 229 Content-Type: text/xml 230 Connection: Close 231 Content-Length: xxxxx 233 234 235 237 238 239 DAV:simplesearch 240 241 243 � 245 247 >> Response 249 HTTP/1.1 207 Multi-Status 250 Content-Type: text/xml 251 Content-Length: xxxxx 253 254 255 257 258 259 http://ryu.com/whales.txt 260 261 262 263 Box type A 265 INTERNET DRAFT DAV Searching and Locating 6 266 DAV Searching and Locating March 1997 268 269 270 J.J. Dingleheimerschmidt 271 272 273 259 274 text/plain 275 276 HTTP/1.1 200 OK 277 278 280 282 2.7 The searchrequest XML Elements 284 The namespace for all DASL XML elements is "DAV:" 286 2.7.1 searchrequest XML Element 288 Name: searchrequest 289 Namespace: DAV: 290 Purpose: Encapsulates the entire search request 292 294 2.7.2 type XML Element 296 Name: type 297 Namespace: DAV: 298 Purpose: Provides a URI which identifies the query grammar 299 Value: href ; see section 11.3 of [WebDAV] 301 302 304 2.7.3 query XML Element 306 Name: query 307 Namespace: DAV: 308 Purpose: A string of the grammar identified by the type XML element which 309 defines the criterion and attributes for the search. 310 Parent:searchrequest 312 314 INTERNET DRAFT DAV Searching and Locating 7 315 DAV Searching and Locating March 1997 317 3 Search Grammar Discovery : OPTIONS 319 3.1 Overview 321 The OPTIONS method allows the client to discover if a resource supports 322 the SEARCH method and to determine the list of search grammars supported 323 for that resource. 325 3.2 Request 327 The client issues the OPTIONS method against a resource named by the 328 Request-URI. This is a normal invocation of OPTIONS defined in [RFC2068]. 330 3.3 Response 332 If a resource supports the SEARCH method, then the server MUST list SEARCH 333 in the OPTIONS response as defined by [RFC2068]. 335 DASL servers MUST include the DASL header in the OPTIONS response. This 336 header identifies the search grammars supported by that resource. 338 3.4 Example 340 This example shows that the server supports search on the /somefolder 341 resource with the following query grammars: http://foo.bar.com/syntax1 and 342 http://akuma.com/syntax2. 344 >> Request 346 OPTIONS /somefolder HTTP/1.1 347 Connection: Close 348 Host: ryu.com 350 >> Response 352 HTTP/1.1 200 OK 353 Date: Tue, 20 Jan 1998 20:52:29 GMT 354 Connection: close 355 Accept-Ranges: none 356 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 357 PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH 358 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 359 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, SEARCH 360 DASL: 362 INTERNET DRAFT DAV Searching and Locating 8 363 DAV Searching and Locating March 1997 365 4 The DASL Response Header 367 4.1 Overview 369 The DASL response header indicates server support for query grammars in 370 the OPTIONS method. The value of this header is a list of URLs. Each URL 371 indicates support for a query grammar. 373 4.2 Syntax 375 DASLHeader = "DASL" ":" URL-List 376 URL-List = 1#Coded-URL ; defined in section 8.5 of [WEBDAV] 378 4.3 Example 380 DASL: 382 INTERNET DRAFT DAV Searching and Locating 9 383 DAV Searching and Locating March 1997 385 5 The DASL simplesearch grammar 387 5.1 Introduction 389 The simplesearch grammar is a query language that allows clients to 390 express search requests that are generally useful for WEBDAV scenarios. 391 DASL-extended servers MUST accept this grammar. 393 The following URI identifies the simplesearch grammar. It is to be used in 394 the Type XML Element. 396 DAV:simplesearch 398 5.2 The Basic Query 400 The simplesearch query grammar is an XML-based syntax that has several 401 components, each an XML element, that defines the query. 403 The select XML element defines the result record. That is, it specifies 404 the properties that will appear in the search result. 406 The from XML element defines the scope of the query. 408 The where XML element defines the criteria for a resource to contribute to 409 the search result. 411 5.3 Example 413 This query will recursively retrieve the content length values for all 414 resources located under the server's "/container1/" URI namespace whose 415 length exceeds 10000. 417 418 419 420 421 422 423 424 425 426 /container1/ 427 infinite 428 429 430 431 432 433 434 435 437 INTERNET DRAFT DAV Searching and Locating 10 438 DAV Searching and Locating March 1997 440 441 442 443 10000 444 445 446 447 448 449 451 5.4 The select XML Element 453 Name: select 454 Namespace: DAV: 455 Purpose: Defines the result record. 457 458 459 461 If the allprops element is present, then all properties defined on 462 matching resources to which the user has access should be listed in the 463 result record. 465 If the prop element is present, then it will name all properties to 466 include in the result record. Each property named by the props element 467 must be referenced in the Multistatus response for the search method. 469 The rules governing the status codes for each property match those of the 470 PROPFIND method defined in [WEBDAV]. 472 5.4.1 Access to properties 474 The select element clause allows any property defined by DAV to be 475 included in the result set. 477 5.5 The from XML element 479 Name: from, scopelist, scope, depth, uri 480 Namespace: DAV: 481 Purpose: Defines the search scope. 483 484 485 486 487 489 The from element defines the scope of the search. 491 INTERNET DRAFT DAV Searching and Locating 11 492 DAV Searching and Locating March 1997 494 The scopelist element contains a list of scopes to search. 496 The scope element defines the collection to search through the uri element 497 and the depth of the search through the depth element. The values for 498 depth are "1" or "infinite". 500 5.6 The where XML Element 502 5.6.1 Overview 504 The where element defines the search criteria, an expression that is 505 evaluated against the each resource contained in the search scope. A 506 resource is only included in the result set if the expression evaluates to 507 true. 509 Clients should be prepared for restrictions on what can be reasonably 510 searched. For example, servers may not be able to provide searches on 511 live-properties whose values are determined dynamically. Additionally, 512 servers may not be able to perform searches that involve arithmetic 513 comparisons. When such restrictions affect a search, servers SHOULD 514 provide the proper status codes in the multistatus response. 516 The WHERE clause supports the typical joining of search terms through the 517 "AND" and "OR" operators. Each search term defines a condition or 518 criterion for a resource property. 520 5.6.2 Syntax 522 Name: where, expr, and, or, not 523 Namespace: DAV: 524 Purpose: Defines the search criteria. 526 527 528 529 530 532 535 536 537 538 539 540 542 544 546 INTERNET DRAFT DAV Searching and Locating 12 547 DAV Searching and Locating March 1997 549 550 551 553 5.7 The Comparison Operators 555 The lt, lte, eq, neq, gt, and gte elements allow comparisons between 556 values. 558 If two values cannot be compared, then the result of a comparison operator 559 is Unknown. 561 5.8 The Contains XML Element 563 The contains operator allows content-based matching for text resource and 564 allows for additional matching of properties that store string values. 566 The contains operator attempts to find a single word or phrase in a 567 resource's text content or property. This is done without regard to case. 568 The search is sensitive to the order of words in a phrase. 570 If a property name is included in the contains element, then the matching 571 is done for that property only. If no property is specified, then the 572 matching is done for the text content of the entire resource. 574 5.8.1 Example 576 Targets text resources that contain the phrase "telecommunications 577 industry". 579 580 581 582 telecommunications industry 583 584 585 587 5.9 Example 589 Targets documents where the foo:author property contains the word "Smith". 591 592 593 594 595 596 597 Smith 598 599 601 INTERNET DRAFT DAV Searching and Locating 13 602 DAV Searching and Locating March 1997 604 606 5.10 Typing 608 When property values are typed, then those types should influence any 609 comparisons performed in the WHERE clause. 611 Servers SHOULD indicate when the query failed because of typing. 613 When a type for a property is unknown, the server SHOULD treat the 614 property as plain text. For example properties with arbitrary XML values 615 to be searched as plain-text strings. 617 5.11 Variants 619 If a server supports resource variants, then the server SHOULD expose 620 those variants through the simplesearch queries. 622 Variants in terms of the query are resources that share the same URI but 623 differ with respect to DAV-properties. For example, the /index.html 624 resource may be available in the content type of "text/plain" or 625 "text/html." Searches that match both resources should include those 626 variants in the response. It is up to the client to define the proper 627 result record, if variants of this sort are to be found. 629 If a server received a query whose criteria match multiple variants of a 630 single resource, then the server SHOULD return records for those variants 631 in the result set. 633 5.12 Versioning 635 TBD. 637 5.13 Security Considerations 639 This section is provided to detail issues concerning security implications 640 of which DASL applications need to be aware. All of the security 641 consideration of HTTP/1.1 also apply to DASL. In addition, this section 642 will include security risks inherent in searching and retrieval of 643 resource properties and content. 645 5.14 Authentication 647 Authentication mechanisms defined in WEBDAV will also apply to DASL. 649 5.15 Internationalized Content 651 All string values in the query are assumed to be in the character set used 652 by the containing XML document. If the XML document uses a character set 653 not understood by the server, then the server MUST respond with 400 (Bad 654 Request). 656 INTERNET DRAFT DAV Searching and Locating 14 657 DAV Searching and Locating March 1997 659 5.16 IANA Considerations 661 This document uses the namespace defined by [WEBDAV] for XML elements. All 662 other IANA considerations mentioned in [WEBDAV] also applicable to DASL. 664 INTERNET DRAFT DAV Searching and Locating 15 665 DAV Searching and Locating March 1997 667 6 Change History 669 Feb, 14 670 - Initial Draft 672 Feb, 28 674 - Referring to DASL as an extension to HTTP/1.1 rather than DAV 675 - Added new sections "Notational Conventions", "Protocol Model", 676 "Security Considerations" 677 - Changed section 3 to "Elements of Protocol" 678 - Added some stuff to introduction 679 - Added "result set" terminology 680 - Added "IANA Considerations". 682 Mar, 9 683 - Moved sub-headings of "Elements of Protocol" to first level and removed 684 "Elements of Protocol" Heading. 685 - Added an sentence in introduction explaining that this is a "sketch" of 686 a protocol. 688 Mar, 11 689 - Accepted all changes from Jim Davis. Added use of HREF element and 690 fixed the DTD, other corrections. 692 INTERNET DRAFT DAV Searching and Locating 16 693 DAV Searching and Locating March 1997 695 7 References 697 [DASLREQ] S. Reddy, J.Slein, "Requirements for DAV Searching and 698 Locating", February 1998, internet-draft, work-in-progress, draft-reddy- 699 dasl-requirements-01.txt 701 [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. Berners- 702 Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, U.C. Irvine, 703 DEC, MIT/LCS, January 1997. 705 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement 706 Levels." RFC 2119, BCP 14. Harvard University. March, 1997. 708 [WEBDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D.Jenson, 709 "Extensions for Distributed Authoring on the World Wide Web", October, 710 1997, internet-draft, work-in-progress, 711 draft-ietf-webdav-protocol-06. 713 INTERNET DRAFT DAV Searching and Locating 17 714 DAV Searching and Locating March 1997 716 8 Author's Addresses 718 Saveen Reddy 719 Microsoft 720 One Microsoft Way 721 Redmond WA, 9085-6933 722 Email: saveenr@microsoft.com 724 Del Jensen 725 Novell 726 1555 N. Technology Way 727 M/S ORM F111 728 Orem, UT 84097-2399 729 Email: dcjensen@novell.com 731 Surendra Reddy 732 Oracle Corporation 733 600 Oracle Parkway, M/S 6op3, 734 Redwoodshores, CA 94065 735 Email: skreddy@us.oracle.com 736 Phone:(650) 506 5441 738 Rick Henderson 739 Netscape 740 Email: rickh@netscape.com 742 Jim Davis 743 Xerox 744 Email: jdavis@parc.xerox.com 746 Alan Babich 747 Filenet 748 Email: ababich@filenet.com 750 Expires Aug, 1998 752 INTERNET DRAFT DAV Searching and Locating 18 753 DAV Searching and Locating March 1997 755 INTERNET DRAFT DAV Searching and Locating 19