idnits 2.17.1 draft-ietf-webdav-ordering-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: ---------------------------------------------------------------------------- ** 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. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 19 longer pages, the longest (page 2) being 59 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 70 instances of lines with control characters in the document. ** The abstract seems to contain references ([B], [RR]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 6 instances of lines with non-RFC2606-compliant FQDNs in the document. 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.) -- The document date (February 20, 2000) is 8831 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: 'Alvestrand' is mentioned on line 981, but not defined ** Obsolete normative reference: RFC 2396 (ref. 'URI') (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' ** Obsolete normative reference: RFC 2616 (ref. 'HTTP') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2518 (ref. 'WebDAV') (Obsoleted by RFC 4918) == Outdated reference: A later version (-02) exists of draft-ietf-webdav-binding-protocol-00 -- Possible downref: Normative reference to a draft: ref. 'B' == Outdated reference: A later version (-13) exists of draft-ietf-webdav-redirectref-protocol-00 ** Downref: Normative reference to an Experimental draft: draft-ietf-webdav-redirectref-protocol (ref. 'RR') Summary: 10 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 WEBDAV Working Group J. Slein, Xerox 2 INTERNET DRAFT E.J. Whitehead Jr., UC Irvine 3 J. Davis, CourseNet 4 G. Clemm, Rational 5 C. Fay, FileNet 6 J. Crawford, IBM 7 T. Chihaya, DataChannel 8 August 20, 1999 9 Expires February 20, 2000 11 WebDAV Ordered Collections Protocol 13 Status of this Memo 15 This document is an Internet-Draft and is in full conformance with all 16 provisions of Section 10 of RFC2026. Internet-Drafts are working 17 documents of the Internet Engineering Task Force (IETF), its areas, and 18 its working groups. Note that other groups may also distribute working 19 documents as Internet-Drafts. 21 The list of current Internet-Drafts can be accessed at 22 http://www.ietf.org/ietf/1id-abstracts.txt 24 The list of Internet-Draft Shadow Directories can be accessed at 25 http://www.ietf.org/shadow.html. 27 Distribution of this document is unlimited. Please send comments to the 28 Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject 30 "subscribe" to . 32 Discussions of the WEBDAV working group are archived at URL: 33 . 35 Abstract 37 The WebDAV Distributed Authoring Protocol provides basic support for 38 collections, offering the ability to create and list unordered 39 collections. 41 This specification is one of a group of three specifications that 42 supplement the WebDAV Distributed Authoring Protocol to increase the 43 power of WebDAV collections. This specification defines a protocol 44 supporting server-side ordering of collection members. The companion 45 specifications [B] and [RR] define two mechanisms for allowing a single 46 resource to appear in more than one collection. 48 Table of Contents 50 1 Notational Conventions.......................................2 51 2 Introduction.................................................3 52 3 Terminology..................................................3 53 4 Overview of Ordered Collections..............................4 54 5 Creating an Ordered Collection...............................4 55 5.1 Overview.....................................................4 56 5.2 Example: Creating an Ordered Collection......................5 57 6 Setting the Position of a Collection Member..................5 58 6.1 Overview.....................................................5 59 6.2 Status Codes.................................................6 60 6.3 Examples: Setting the Position of a Collection Member........6 61 7 Changing the Semantics of a Collection Ordering..............6 62 8 Changing the Position of a Collection Member.................7 63 8.1 ORDERPATCH Method............................................7 64 8.1.1 Status Codes.................................................7 65 8.1.2 Example: Changing Positions in an Ordered Collection.........7 66 8.1.3 Example: Failure of an ORDERPATCH Request....................9 67 9 Listing the Members of an Ordered Collection................10 68 9.1 Example: PROPFIND on an Ordered Collection..................10 69 10 Headers.....................................................12 70 10.1 Ordered Entity Header.......................................12 71 10.2 Position Request Header.....................................12 72 11 Status Codes................................................13 73 11.1 425 Unordered Collection....................................13 74 12 Properties..................................................13 75 12.1 orderingtype Property.......................................13 76 13 XML Elements................................................14 77 13.1 unordered XML Element.......................................14 78 13.2 custom XML Element..........................................14 79 13.3 order XML Element...........................................14 80 13.4 ordermember XML Element.....................................14 81 13.5 position XML Element........................................15 82 13.6 first XML Element...........................................15 83 13.7 last XML Element............................................15 84 13.8 before XML Element..........................................15 85 13.9 after XML Element...........................................15 86 13.10 options XML Element.........................................16 87 13.11 orderingoptions XML Element.................................16 88 14 Capability Discovery........................................16 89 14.1 Example: Discovery of Support for Ordering..................16 90 14.2 Additional Capabilities.....................................17 91 14.3 Example: Discovery of Ordering Options......................17 92 15 Security Considerations.....................................18 93 15.1 Denial of Service and DAV:orderingtype......................18 94 16 Internationalization Considerations.........................18 95 17 IANA Considerations.........................................19 96 18 Copyright...................................................19 97 19 Intellectual Property.......................................19 98 20 Acknowledgements............................................19 99 21 References..................................................19 100 22 Authors' Addresses..........................................20 101 23 Appendices..................................................20 102 23.1 Appendix 1: Extensions to the WebDAV Document Type 103 Definition..................................................21 105 1 Notational Conventions 107 Since this document describes a set of extensions to the HTTP/1.1 108 protocol, the augmented BNF used here to describe protocol elements is 109 exactly the same as described in Section 2.1 of [HTTP]. Since this 110 augmented BNF uses the basic production rules provided in Section 2.2 of 111 [HTTP], these rules apply to this document as well. 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in [RFC2119]. 117 2 Introduction 119 The simple collections that the WebDAV Distributed Authoring Protocol 120 specification supports are powerful enough to be widely useful. They 121 provide for the hierarchical organization of resources, with mechanisms 122 for creating and deleting collections, copying and moving them, locking 123 them, adding members to them and removing members from them, and getting 124 listings of their members. Delete, copy, move, list, and lock 125 operations can be applied recursively, so that a client can operate on 126 whole hierarchies with a single request. 128 This specification is one of a family of three specifications that build 129 on the infrastructure defined in [HTTP] and [WebDAV] to extend the 130 capabilities of collections. The companion specifications [B] and [RR] 131 define mechanisms for allowing the same resource to appear in multiple 132 collections. The present specification defines protocol extensions to 133 support ordered collections. 135 The WebDAV Distributed Authoring Protocol added to the Web the ability 136 to navigate Web resources hierarchically, complementing existing 137 hypertext navigation facilities. In hypertext navigation, links appear 138 in a specific order in a document. By contrast, hierarchical navigation 139 has fewer mechanisms for expressing the ordering of a set of resources. 141 There are many scenarios where it is useful to impose an ordering on a 142 collection, such as expressing a recommended access order, or a revision 143 history order. Orderings may be based on property values, but they may 144 be completely independent of any properties on the resources identified 145 by the collection's internal member URIs. Orderings based on properties 146 can be obtained using a search protocol, but orderings not based on 147 properties need some other mechanism. These orderings generally need to 148 be maintained by a human user. The ordering protocol defined here 149 focuses on support for such human-maintained orderings, but also allows 150 for server-maintained orderings. 152 3 Terminology 154 The terminology used here follows that in the WebDAV Distributed 155 Authoring Protocol specification [WebDAV]. Definitions of the terms 156 resource, Uniform Resource Identifier (URI), and Uniform Resource 157 Locator (URL) are provided in [URI]. Definitions of the terms URI 158 mapping, path segment, binding, collection, and internal member URI are 159 provided in [B]. 161 Ordered Collection 162 A collection for which the results from a PROPFIND request are 163 guaranteed to be in the order specified for that collection 165 Unordered Collection 166 A collection for which the client cannot depend on the 167 repeatability of the ordering of results from a PROPFIND request 169 Client-Maintained Ordering 170 An ordering of collection members that is maintained on the server 171 based on client requests specifying the position of each 172 collection member in the ordering 174 Server-Maintained Ordering 175 An ordering of collection members that is maintained automatically 176 by the server, based on a client's choice of ordering semantics 178 4 Overview of Ordered Collections 180 When responding to a PROPFIND on a collection, the server orders the 181 response elements according to the ordering defined on the collection. 182 If a collection is unordered, the client cannot depend on the 183 repeatability of the ordering of results from a PROPFIND request. 185 Collections on a compliant server may be ordered, but need not be. It 186 is up to the client to decide whether a given collection is ordered and, 187 if so, to specify the semantics to be used for ordering its bindings. 188 If a collection is ordered, each of its bindings, and hence internal 189 member URIs, MUST be in the ordering exactly once, and the ordering MUST 190 NOT include any binding that is not contained by the collection. Only 191 one ordering can be attached to any collection. An ordering is 192 considered to be part of the state of a collection resource, and hence 193 is the same across all URI mappings to the collection. Multiple 194 orderings of the same resources can be achieved by creating multiple 195 collections referencing those resources, and attaching a different 196 ordering to each collection. 198 The server is responsible for enforcing these constraints on orderings. 199 The server MUST remove a binding (and its derived internal member URI) 200 from the ordering when it is removed from the collection. The server 201 MUST add a binding (and its derived internal member URI) to the ordering 202 when it is added to the collection. 204 5 Creating an Ordered Collection 206 5.1 Overview 208 When a collection is created, the client MAY request that it be ordered 209 and specify the semantics of the ordering by using the new Ordered 210 header (defined in Section 8.1) with a MKCOL request. 212 For collections that are ordered, the client SHOULD identify the 213 semantics of the ordering with a URI in the Ordered header. This URI 214 may identify a server-maintained ordering. Clients can discover the 215 available server-maintained orderings using the mechanism defined in 216 Section 12.2. The URI may identify a semantics for a client-maintained 217 ordering, providing the information a human user or software package 218 needs to insert new collection members into the ordering intelligently. 219 Although the URI in the Ordered header MAY point to a resource that 220 contains a definition of the semantics of the ordering, clients are 221 discouraged from accessing that resource, in order to avoid 222 overburdening its server. The client MAY set the header value to 223 DAV:custom to indicate that the collection is ordered, but the semantics 224 of the ordering are not being advertised. If the client does not want 225 the collection to be ordered, it may omit the Ordered header, or use it 226 with the value DAV:unordered. 228 If the server does not recognize the value of the Ordered header as one 229 of its server-maintained orderings, it MUST assume that a client- 230 maintained ordering is intended. If the value of the Ordered header is 231 one of the server-maintained orderings that the server supports, it MUST 232 maintain the collection's ordering according to that ordering semantics 233 as new members are added. 235 Every collection MUST have a DAV:orderingtype property (defined in 236 Section 10.1), which indicates whether the collection is ordered and, if 237 so, identifies the semantics of the ordering. The server sets the 238 initial value of this property based on the value of the Ordering header 239 in the MKCOL request. If the collection is unordered, the 240 DAV:orderingtype property MUST have the value DAV:unordered. An 241 ordering-aware client interacting with an ordering-unaware server (e.g., 242 one that is implemented only according to [WebDAV]) SHOULD assume that 243 if a collection does not have the DAV:orderingtype property, the 244 collection is unordered. 246 5.2 Example: Creating an Ordered Collection 248 >>Request: 250 MKCOL /theNorth/ HTTP/1.1 251 Host: www.server.org 252 Ordered: 254 >>Response: 256 HTTP/1.1 201 Created 258 In this example a new, ordered collection was created. Its 259 DAV:orderingtype property has as its value the URI from the Ordered 260 header, http://www.server.org/orderings/compass.html. In this case, the 261 URI identifies the semantics governing a client-maintained ordering. As 262 new members are added to the collection, clients or end users can use 263 the semantics to determine where to position the new members in the 264 ordering. 266 6 Setting the Position of a Collection Member 268 6.1 Overview 270 When a new member is added to a collection with a client-maintained 271 ordering (for example, with PUT, MKREF, or MKCOL), its position in the 272 ordering can be set with the new Position header (defined in Section 273 8.2). The Position header allows the client to specify that the member 274 should be first in the collection's ordering, last in the collection's 275 ordering, immediately before some other binding in the collection's 276 ordering, or immediately after some other binding in the collection's 277 ordering. 279 6.2 Status Codes 281 409 (Conflict): The request specifies a position that is before or after 282 a URI that is not an internal member URI of the collection, or before or 283 after itself. 285 425 (Unordered Collection): The request specifies a collection position 286 in an unordered collection or in a collection with a server-maintained 287 ordering. 289 6.3 Examples: Setting the Position of a Collection Member 291 >>Request: 293 MKREF /~whitehead/dav/spec08.ref HTTP/1.1 294 HOST: www.ics.uci.edu 295 Ref-Target: 296 Position: after 298 >>Response: 300 HTTP/1.1 201 Created 302 This request resulted in the creation of a new referential resource at 303 www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource 304 identified by the Ref-Target header. The Position header in this 305 example caused the server to set its position in the ordering of the 306 /~whitehead/dav/ collection immediately after requirements.html. 308 >>Request: 310 MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 311 Host: www.ics.uci.edu 312 Destination: http://www.ics.uci.edu/~whitehead/dav/draft-webdav- 313 protocol-08.txt 314 Position: first 316 >>Response: 318 HTTP/1.1 425 Unordered Collection 320 In this case, the server returned a 425 (Unordered Collection) status 321 code because the /~whitehead/dav/ collection is an unordered collection. 322 Consequently, the server was unable to satisfy the Position header. 324 7 Changing the Semantics of a Collection Ordering 326 After a collection has been created, a client can change its ordering 327 semantics, or change an ordered collection to an unordered collection or 328 vice versa, by using PROPPATCH to change the value of its 329 DAV:orderingtype property (defined in Section 10.1). If the new value 330 identifies a client-maintained ordering, the client is then responsible 331 for updating the collection's ordering according to the new semantics. 332 If it identifies a server-maintained ordering, the server MUST reorder 333 the collection according to the new semantics. PROPPATCH is defined in 334 [WebDAV], Section 7.2. 336 8 Changing the Position of a Collection Member 338 8.1 ORDERPATCH Method 340 The ORDERPATCH method alters the ordering of bindings in the collection 341 identified by the Request-URI, based on instructions in the order XML 342 element. The order XML element identifies the bindings whose positions 343 are to be changed, and describes their new positions in the ordering. 344 Each new position can be specified as first in the ordering, last in the 345 ordering, immediately before some other binding, or immediately after 346 some other binding. 348 The server MUST apply the changes in the order they appear in the order 349 XML element. The server MUST either apply all the changes or apply none 350 of them. If any error occurs during processing, all executed changes 351 MUST be undone and a proper error result returned. 353 8.1.1 Status Codes 355 Since multiple changes can be requested in a single ORDERPATCH request, 356 the server MUST return a 207 (Multi-Status) response, as defined in 357 [WebDAV]. 359 The following are examples of response codes one would expect to be used 360 in a 207 (Multi-Status) response for this method: 362 200 (OK): The change in ordering was successfully made. 364 409 (Conflict): The request specifies a position that is before or after 365 a URI that is not an internal member URI of the collection, or before or 366 after itself. 368 425 (Unordered Collection): The request specifies a collection position 369 in an unordered collection or in a collection with a server-maintained 370 ordering. 372 A request to reposition a binding at the same place in the ordering is 373 not an error. 375 8.1.2 Example: Changing Positions in an Ordered Collection 377 Consider a collection /coll-1/ with bindings ordered as follows: 379 nunavut.map 380 nunavut.img 381 baffin.map 382 baffin.desc 383 baffin.img 384 iqaluit.map 385 nunavut.desc 386 iqaluit.img 387 iqaluit.desc 389 >> Request: 391 ORDERPATCH /coll-1/ HTTP/1.1 392 Host: www.nunanet.com 393 Content-Type: text/xml 394 Content-Length: xxx 396 397 398 399 nunavut.desc 400 401 402 nunavut.map 403 404 405 406 407 iqaluit.img 408 409 410 411 412 414 >> Response: 416 HTTP/1.1 207 Multi-Status 417 Content-Type: text/xml 418 Content-Length: xxx 420 421 422 423 http://www.nunanet.com/coll-1/nunavut.desc 424 HTTP/1.1 200 OK 425 426 427 http://www.nunanet.com/coll-1/iqaluit.img 428 HTTP/1.1 200 OK 429 430 432 If the href elements are relative URIs, as in this example, they are 433 interpreted relative to the collection that is being reordered. In this 434 example, after the request has been processed, the collection's ordering 435 is as follows: 437 nunavut.map 438 nunavut.desc 439 nunavut.img 440 baffin.map 441 baffin.desc 442 baffin.img 443 iqaluit.map 444 iqaluit.desc 445 iqaluit.img 447 8.1.3 Example: Failure of an ORDERPATCH Request 449 Consider a collection /coll-1/ with bindings ordered as follows: 451 nunavut.map 452 nunavut.img 453 baffin.map 454 baffin.desc 455 baffin.img 456 iqaluit.map 457 nunavut.desc 458 iqaluit.img 459 iqaluit.desc 461 >> Request: 463 ORDERPATCH /coll-1/ HTTP/1.1 464 Host: www.nunanet.com 465 Content-Type: text/xml 466 Content-Length: xxx 468 469 470 471 nunavut.desc 472 473 474 nunavut.map 475 476 477 478 479 iqaluit.map 480 481 482 pangnirtung.img 483 484 485 486 488 >> Response: 490 HTTP/1.1 207 Multi-Status 491 Content-Type: text/xml 492 Content-Length: xxx 494 495 496 497 http://www.nunanet.com/coll-1/nunavut.desc 498 HTTP/1.1 424 Failed Dependency 499 500 501 http://www.nunanet.com/coll-1/iqaluit.map 502 HTTP/1.1 409 Conflict 503 pangnirtung.img is not a collection 504 member. 505 506 508 In this example, the client attempted to position iqaluit.map after a 509 binding that is not contained in the collection /coll-1/. The server 510 responded to this client error with a 409 (Conflict) status code. 511 Because ORDERPATCH is an atomic method, the request to reposition 512 nunavut.desc (which would otherwise have succeeded) failed with a 424 513 (Failed Dependency) status code. 515 9 Listing the Members of an Ordered Collection 517 A PROPFIND request is used to retrieve a listing of the members of an 518 ordered collection, just as it is used to retrieve a listing of the 519 members of an unordered collection. 521 However, when responding to a PROPFIND on an ordered collection, the 522 server MUST order the response elements according to the ordering 523 defined on the collection. If a collection is unordered, the client 524 cannot depend on the repeatability of the ordering of results from a 525 PROPFIND request. 527 When responding to a PROPFIND on an ordered collection, the server 528 SHOULD include the DAV:orderingtype property in the DAV:response element 529 for the collection, even if the client did not explicitly request it. 531 9.1 Example: PROPFIND on an Ordered Collection 533 Suppose a PROPFIND request is submitted to the following collection, 534 which has its members ordered according to their distance from the 535 equator. 537 /MyCollection/ 538 lakehazen.html 539 siorapaluk.html 540 iqaluit.html 541 newyork.html 543 >> Request: 545 PROPFIND /MyCollection/ HTTP/1.1 546 Host: www.svr.com 547 Depth: 1 548 Content-Type: text/xml 549 Content-Length: xxxx 550 551 552 553 554 555 556 558 >> Response: 560 HTTP/1.1 207 Multi-Status 561 Content-Type: text/xml 562 Content-Length: xxxx 564 565 567 568 http://www.svr.com/MyCollection/ 569 570 571 572 573 http://www.svr.com/jslatitudedesc 574 575 576 HTTP/1.1 200 OK 577 578 579 580 581 582 HTTP/1.1 404 Not Found 583 584 585 586 http://www.svr.com/MyCollection/lakehazen.html 587 588 589 590 82N 591 592 HTTP/1.1 200 OK 593 594 595 596 http://www.svr.com/MyCollection/siorapaluk.html 597 598 599 600 78N 601 602 HTTP/1.1 200 OK 603 604 605 606 http://www.svr.com/MyCollection/iqaluit.html 607 608 609 610 62N 611 612 HTTP/1.1 200 OK 613 614 615 616 http://www.svr.com/MyCollection/newyork.html 617 618 619 620 45N 621 622 HTTP/1.1 200 OK 623 624 625 627 In this example, the server responded with a list of the collection 628 members ordered according to their distance from the equator, as 629 specified by the value of DAV:orderingtype. Although the client did not 630 explicitly ask for the value of DAV:orderingtype, the server provided it 631 as one of the collection properties, allowing the client to tell that 632 the collection is ordered and to identify the ordering semantics. 634 10 Headers 636 10.1 Ordered Entity Header 638 Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) 640 The Ordered header may be used with MKCOL to request that the new 641 collection be ordered and to specify its ordering semantics. A value of 642 "DAV:unordered" indicates that the collection is not ordered. A value of 643 "DAV:custom" indicates that the collection is to be ordered, but the 644 semantics of the ordering is not being advertised. Any other Coded-url 645 value indicates that the collection is ordered, and identifies the 646 semantics of the ordering. 648 10.2 Position Request Header 650 Position = "Position" ":" ("first" | "last" | 651 (("before" | "after") Generic-Coded-url)) 652 Generic-Coded-url = "<" (absoluteURI | relativeURI) ">" 653 absoluteURI is defined in Section 3 of [URI]. 654 relativeURI is defined in Section 5 of [URI]. 656 The Position header may be used with any method that adds a binding to a 657 collection with a client-maintained ordering, to tell the server where 658 in the collection ordering to position the new binding being added to 659 the collection. Examples of methods that add bindings to collections 660 are BIND, PUT, COPY, MOVE, etc. 662 If the Generic-Coded-url is a relative URL, it is interpreted relative 663 to the collection to which the new binding is being added. 665 The server MUST insert the new binding into the ordering at the location 666 specified in the Position header, if one is present (and if the 667 collection has a client-maintained ordering). 669 The "first" keyword indicates the new binding is put in the beginning 670 position in the collection's ordering, while "last" indicates the new 671 binding is put in the final position in the collection's ordering. The 672 "before" keyword indicates the new binding is added to the collection's 673 ordering immediately prior to the position of the binding identified in 674 the Generic-Coded-url. Likewise, the "after" keyword indicates the new 675 binding is added to the collection's ordering immediately following the 676 position of the binding identified in the Generic-Coded-url. 678 If the request is replacing an existing resource, and the Position 679 header is present, the server MUST remove the binding from its previous 680 position, and then insert it at the requested position. 682 If the Position request header is not used when adding a binding to a 683 collection with a client-maintained ordering, then: 685 o If the request is replacing an existing resource, the server MUST 686 preserve the present ordering. 688 o If the request is adding a new binding to the collection, the server 689 MUST append the new binding to the end of the ordering. 691 If an attempt is made to use the Position header on a collection that is 692 unordered or that has a server-maintained ordering, the server MUST fail 693 the request with a 425 (Unordered) status code. 695 11 Status Codes 697 11.1 425 Unordered Collection 699 The 425 (Unordered Collection) status code indicates that the client 700 attempted to set the position of an internal collection member in an 701 unordered collection or in a collection with a server-maintained 702 ordering. 704 12 Properties 706 12.1 orderingtype Property 708 Name: orderingtype 709 Namespace: DAV: 710 Purpose: Indicates whether the collection is ordered and, if so, 711 uniquely identifies the semantics of the ordering being 712 used. May also point to an explanation of the semantics in 713 human and / or machine-readable form. At a minimum, this 714 allows human users who add members to the collection to 715 understand where to position them in the ordering. 716 Value: The value unordered indicates that the collection is not 717 ordered. The value custom indicates that the collection is 718 ordered, but the semantics governing the ordering are not 719 being advertised. If the value is an href element, it 720 contains a URI that uniquely identifies the semantics of the 721 collection's ordering. 723 725 13 XML Elements 727 13.1 unordered XML Element 729 Name: unordered 730 Namespace: DAV: 731 Purpose: A value of the DAV:orderingtype property that indicates that 732 the collection is not ordered. That is, the client cannot 733 depend on the repeatability of the ordering of results from 734 a PROPFIND request. 736 738 13.2 custom XML Element 740 Name: custom 741 Namespace: DAV: 742 Purpose: A value of the DAV:orderingtype property that indicates that 743 the collection is ordered, but the semantics of the ordering 744 are not being advertised. 746 748 13.3 order XML Element 750 Name: order 751 Namespace: DAV: 752 Purpose: For use with the new ORDERPATCH method. Describes a change 753 to be made in a collection ordering. 754 Value: A description of the new positions of the bindings a 755 collection contains in its ordering. 757 759 13.4 ordermember XML Element 761 Name: ordermember 762 Namespace: DAV: 763 Purpose: Occurs in the order XML element, and describes the new 764 position of a single binding in the collection's ordering. 765 Value: An href containing a binding's path segment, and a 766 description of its new position in the ordering. The href 767 XML element is defined in [WebDAV], Section 11.3. 769 770 13.5 position XML Element 772 Name: position 773 Namespace: DAV: 774 Purpose: Occurs in the ordermember XML element. Describes the new 775 position in a collection's ordering of one of the bindings 776 it contains. 777 Value: The new position can be described as first in the 778 collection's ordering, last in the collection's ordering, 779 immediately before some other binding, or immediately after 780 some other binding. 782 784 13.6 first XML Element 786 Name: first 787 Namespace: DAV: 788 Purpose: Occurs in the position XML element. Specifies that the 789 binding should be placed first in the collection's ordering. 791 793 13.7 last XML Element 795 Name: last 796 Namespace: DAV: 797 Purpose: Occurs in the position XML element. Specifies that the 798 binding should be placed last in the collection's ordering. 800 802 13.8 before XML Element 804 Name: before 805 Namespace: DAV: 806 Purpose: Occurs in the position XML element. Specifies that the 807 binding should be placed immediately before the binding in 808 the enclosed href XML element in the collection's ordering. 809 Value: href of the member it precedes in the ordering 811 813 13.9 after XML Element 815 Name: after 816 Namespace: DAV: 817 Purpose: Occurs in the position XML element. Specifies that the 818 binding should be placed immediately after the binding in 819 the enclosed href XML element in the collection's ordering. 820 Value: href of the member it follows in the ordering 822 823 13.10 options XML Element 825 Name: options 826 Namespace: DAV: 827 Purpose: Used in OPTIONS requests to ask for more detailed 828 information about capabilities than can be provided in the 829 DAV: response header. Used in OPTIONS responses to provide 830 that information. 831 Value: List of elements identifying or providing the additional 832 information desired. 834 836 13.11 orderingoptions XML Element 838 Name: orderingoptions 839 Namespace: DAV: 840 Purpose: Used in OPTIONS requests to ask for the list of server- 841 maintained orderings that can be supported at the request- 842 URI. Used in OPTIONS responses to provide that information. 843 These values can be used in the Ordered header or the 844 DAV:orderingtype property to request that a particular 845 server-maintained ordering be applied to the collection. 846 Value: EMPTY on requests. On responses, it is the list of server- 847 maintained orderings available for the request-URI. 849 851 14 Capability Discovery 853 Sections 9.1 and 15 of [WebDAV] describe the use of compliance classes 854 with the DAV header in responses to OPTIONS, to indicate which parts of 855 the Web Distributed Authoring protocols the resource supports. This 856 specification defines an OPTIONAL extension to [WebDAV]. It defines a 857 new compliance class, called orderedcoll, for use with the DAV header in 858 responses to OPTIONS requests. If a collection resource does support 859 ordering, its response to an OPTIONS request MUST indicate that it does, 860 by listing the new ORDERPATCH method as one it supports, and by listing 861 the new orderedcoll compliance class in the DAV header. 863 When responding to an OPTIONS request, only a collection or a null 864 resource can include orderedcoll in the value of the DAV header. By 865 including orderedcoll, the resource indicates that its bindings can be 866 ordered. It implies nothing about whether any collections identified by 867 its internal member URIs can be ordered. 869 14.1 Example: Discovery of Support for Ordering 871 >> Request: 873 OPTIONS /somecollection/ HTTP/1.1 874 HOST: somehost.org 876 >> Response: 878 HTTP/1.1 200 OK 879 Date: Tue, 20 Jan 1998 20:52:29 GMT 880 Connection: close 881 Accept-Ranges: none 882 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 883 PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 884 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 885 PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH 886 DAV: 1, 2, orderedcoll 888 The DAV header in the response indicates that the resource 889 /somecollection/ is level 1 and level 2 compliant, as defined in 890 [WebDAV]. In addition, /somecollection/ supports ordering. The Allow 891 header indicates that ORDERPATCH requests can be submitted to 892 /somecollection/. The Public header shows that other Request-URIs on 893 the server support additional methods. 895 14.2 Additional Capabilities 897 Clients may need detailed information about specific areas of Web 898 Distributed Authoring functionality. This information can be requested 899 by sending an OPTIONS request with an XML body that includes a 900 DAV:options element. The DAV:options element contains a list of empty 901 elements identifying the information the client needs. 903 As described in Section 4, servers may offer a set of server-maintained 904 orderings on collections. Clients can discover the list of server- 905 maintained orderings available for the request-URI by including an empty 906 DAV:orderingoptions element in the DAV:options element. The response 907 will include a DAV:orderingoptions element with the list of supported 908 server-maintained orderings. Servers SHOULD advertise the server- 909 maintained orderings available using this mechanism. 911 14.3 Example: Discovery of Ordering Options 913 >> Request: 915 OPTIONS /somecollection/ HTTP/1.1 916 HOST: somehost.org 918 919 920 921 923 >> Response: 925 HTTP/1.1 200 OK 926 Date: Tue, 20 Jan 1998 20:52:29 GMT 927 Connection: close 928 Accept-Ranges: none 929 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 930 PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 931 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 932 PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH 933 DAV: 1, sharing, orderedcoll 935 936 937 938 939 940 941 942 944 This response indicates that the resource /somecollection/ is level 1 945 compliant, as defined in [WebDAV]. In addition, /somecollection/ 946 supports ordering. The client also asked for a list of the server- 947 maintained orderings that are supported for /somecollection/. The 948 response indicates that the orderings Xerox:author-ascending, 949 Xerox:title-ascending, and Xerox:date-descending are supported. 951 15 Security Considerations 953 This section is provided to make WebDAV applications aware of the 954 security implications of this protocol. 956 All of the security considerations of HTTP/1.1 and the WebDAV 957 Distributed Authoring Protocol specification also apply to this protocol 958 specification. In addition, ordered collections introduce a new 959 security concern. This issue is detailed here. 961 15.1 Denial of Service and DAV:orderingtype 963 There may be some risk of denial of service at sites that are advertised 964 in the DAV:orderingtype property of collections. However, it is 965 anticipated that widely-deployed applications will use hard-coded values 966 for frequently-used ordering semantics rather than looking up the 967 semantics at the location specified by DAV:orderingtype. In addition, 968 Section 4 discourages clients from looking up the semantics at that 969 location. 971 16 Internationalization Considerations 973 This specification follows the practices of [WebDAV] in encoding all 974 human-readable content using XML [XML] and in the treatment of names. 975 Consequently, this specification complies with the IETF Character Set 976 Policy [Alvestrand]. 978 WebDAV applications MUST support the character set tagging, character 979 set encoding, and the language tagging functionality of the XML 980 specification. This constraint ensures that the human-readable content 981 of this specification complies with [Alvestrand]. 983 As in [WebDAV}, names in this specification fall into three categories: 984 names of protocol elements such as methods and headers, names of XML 985 elements, and names of properties. Naming of protocol elements follows 986 the precedent of HTTP, using English names encoded in USASCII for 987 methods and headers. The names of XML elements used in this 988 specification are English names encoded in UTF-8. 990 For error reporting, [WebDAV] follows the convention of HTTP/1.1 status 991 codes, including with each status code a short, English description of 992 the code (e.g., 423 Locked). Internationalized applications will ignore 993 this message, and display an appropriate message in the user's language 994 and character set. 996 For rationales for these decisions and advice for application 997 implementors, see [WebDAV]. 999 17 IANA Considerations 1001 This document uses the namespaces defined by [WebDAV] for properties and 1002 XML elements. All other IANA considerations mentioned in [WebDAV] also 1003 apply to this document. 1005 18 Copyright 1007 To be supplied by the RFC Editor. 1009 19 Intellectual Property 1011 To be supplied by the RFC Editor. 1013 20 Acknowledgements 1015 This draft has benefited from thoughtful discussion by Jim Amsden, Steve 1016 Carter, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Mark Day, 1017 Rajiv Dulepet, David Durand, Roy Fielding, Yaron Goland, Fred Hitt, Alex 1018 Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, 1019 Daniel LaLiberte, Steve Martin, Larry Masinter, Jeff McAffer, Surendra 1020 Koduru Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness, John 1021 Stracke, John Tigue, John Turner, and others. 1023 21 References 1025 [URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource 1026 Identifiers (URI): Generic Syntax." RFC 2396. MIT/LCS, U.C. Irvine, 1027 Xerox. August, 1998. 1029 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement 1030 Levels." RFC 2119, BCP 14. Harvard University. March, 1997. 1032 [XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup 1033 Language (XML)." World Wide Web Consortium Recommendation REC-xml- 1034 19980210. http://www.w3.org/TR/1998/REC-xml-19980210. 1036 [HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. 1037 Leach, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC 1038 2616. UC Irvine, Compaq, W3C, Xerox, Microsoft. June, 1999. 1040 [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. 1041 Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." RFC 2518. 1042 Microsoft, U.C. Irvine, Netscape, Novell. February, 1999. 1044 [B] J. Slein, E.J. Whitehead Jr., J. Davis, G. Clemm, C. Fay, J. 1045 Crawford, T. Chihaya, "WebDAV Bindings." Internet Draft (work in 1046 progress) draft-ietf-webdav-binding-protocol-00. Xerox, UC Irvine, 1047 CourseNet, Rational, FileNet, IBM, DataChannel. August, 1999. 1049 [RR] J. Slein, E.J. Whitehead Jr., J. Davis, G. Clemm, C. Fay, J. 1050 Crawford, T. Chihaya, "WebDAV Redirect References." Internet Draft (work 1051 in progress) draft-ietf-webdav-redirectref-protocol-00. Xerox, UC 1052 Irvine, CourseNet, Rational, FileNet, IBM, DataChannel. August, 1999. 1054 22 Authors' Addresses 1056 J. Slein 1057 Xerox Corporation 1058 800 Phillips Road, 105-50C 1059 Webster, NY 14580 1060 Email: jslein@crt.xerox.com 1062 E. J. Whitehead, Jr. 1063 Dept. of Information and Computer Science 1064 University of California, Irvine 1065 Irvine, CA 92697-3425 1066 Email: ejw@ics.uci.edu 1068 J. Davis 1069 CourseNet Systems 1070 170 Capp Street 1071 San Francisco, CA 94110 1072 Email: jrd3@alum.mit.edu 1074 G. Clemm 1075 Rational Software Corporation 1076 20 Maguire Road 1077 Lexington, MA 02173-3104 1078 Email: gclemm@rational.com 1080 C. Fay 1081 FileNet Corporation 1082 3565 Harbor Boulevard 1083 Costa Mesa, CA 92626-1420 1084 Email: cfay@filenet.com 1086 J. Crawford 1087 IBM 1088 Email: ccjason@us.ibm.com 1090 T. Chihaya 1091 DataChannel, Inc. 1092 155 108th Ave. N.E., Suite 400 1093 Bellevue, WA 98004 1094 Email: Tyson@DataChannel.com 1096 23 Appendices 1097 23.1 Appendix 1: Extensions to the WebDAV Document Type Definition 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1114 Expires February 20, 2000