idnits 2.17.1 draft-ietf-webdav-ordering-protocol-01.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 the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 21 longer pages, the longest (page 1) 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 69 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 (April 15, 2000) is 8775 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 1023, but not defined == Unused Reference: 'RR' is defined on line 1094, but no explicit reference was found in the text ** 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: 11 errors (**), 0 flaws (~~), 7 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 October 15, 1999 9 Expires April 15, 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 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference material 24 or to cite them other than as "work in progress". 26 To view the list Internet-Draft Shadow Directories, see 27 http://www.ietf.org/shadow.html. 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 subject 32 "subscribe" to . 34 Discussions of the WEBDAV working group are archived at URL: 35 . 37 Abstract 39 The WebDAV Distributed Authoring Protocol provides basic support for 40 collections, offering the ability to create and list unordered 41 collections. 43 This specification is one of a group of three specifications that 44 supplement the WebDAV Distributed Authoring Protocol to increase the 45 power of WebDAV collections. This specification defines a protocol 46 supporting server-side ordering of collection members. The companion 47 specifications "WebDAV Bindings"[B] and "WebDAV Redirect Reference 48 Resources"[RR] define two mechanisms for allowing a single resource to 49 appear in more than one collection. 51 Table of Contents 53 1 Notational Conventions......................................2 54 2 Introduction................................................3 55 3 Terminology.................................................3 56 4 Overview of Ordered Collections.............................4 57 5 Creating an Ordered Collection..............................5 58 5.1 Overview....................................................5 59 5.2 Example: Creating an Ordered Collection.....................5 60 6 Setting the Position of a Collection Member.................6 61 6.1 Overview....................................................6 62 6.2 Status Codes................................................6 63 6.3 Examples: Setting the Position of a Collection Member.......6 64 7 Changing a Collection Ordering..............................7 65 7.1 ORDERPATCH Method...........................................7 66 7.1.1 Status Codes................................................7 67 7.1.2 Example: Changing a Collection Ordering.....................8 68 7.1.3 Example: Failure of an ORDERPATCH Request...................9 69 8 Listing the Members of an Ordered Collection...............10 70 8.1 Example: PROPFIND on an Ordered Collection.................11 71 9 Status Codes...............................................13 72 9.1 418 Unordered Collection...................................13 73 10 Headers....................................................13 74 10.1 Ordered Entity Header......................................13 75 10.2 Position Request Header....................................13 76 11 Properties.................................................14 77 11.1 orderingtype Property......................................14 78 12 XML Elements...............................................14 79 12.1 unordered XML Element......................................14 80 12.2 custom XML Element.........................................15 81 12.3 order XML Element..........................................15 82 12.4 ordermember XML Element....................................15 83 12.5 position XML Element.......................................15 84 12.6 first XML Element..........................................15 85 12.7 last XML Element...........................................16 86 12.8 before XML Element.........................................16 87 12.9 after XML Element..........................................16 88 12.10 options XML Element........................................16 89 12.11 orderingoptions XML Element................................16 90 13 Capability Discovery.......................................17 91 13.1 Example: Discovery of Support for Ordering.................17 92 13.2 Additional Capabilities....................................18 93 13.3 Example: Discovery of Ordering Options.....................18 94 14 Security Considerations....................................19 95 14.1 Denial of Service and DAV:orderingtype.....................19 96 15 Internationalization Considerations........................19 97 16 IANA Considerations........................................19 98 17 Copyright..................................................20 99 18 Intellectual Property......................................20 100 19 Acknowledgements...........................................20 101 20 References.................................................20 102 21 Authors' Addresses.........................................20 103 22 Appendices.................................................21 104 22.1 Appendix 1: Extensions to the WebDAV Document Type 105 Definition.................................................21 107 1 Notational Conventions 109 Since this document describes a set of extensions to the WebDAV 110 Distributed Authoring Protocol [WebDAV], itself an extension to the 111 HTTP/1.1 protocol, the augmented BNF used here to describe protocol 112 elements is exactly the same as described in Section 2.1 of [HTTP]. 114 Since this augmented BNF uses the basic production rules provided in 115 Section 2.2 of [HTTP], these rules apply to this document as well. 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in [RFC2119]. 121 2 Introduction 123 The simple collections that the WebDAV Distributed Authoring Protocol 124 specification supports are powerful enough to be widely useful. They 125 provide for the hierarchical organization of resources, with mechanisms 126 for creating and deleting collections, copying and moving them, locking 127 them, adding members to them and removing members from them, and getting 128 listings of their members. Delete, copy, move, list, and lock 129 operations can be applied recursively, so that a client can operate on 130 whole hierarchies with a single request. 132 This specification is one of a family of three specifications that build 133 on the infrastructure defined in [HTTP] and [WebDAV] to extend the 134 capabilities of collections. The companion specifications "WebDAV 135 Bindings"[B] and "WebDAV Redirect Reference Resources"[RR] define 136 mechanisms for allowing the same resource to appear in multiple 137 collections. The present specification defines protocol extensions to 138 support ordered collections. 140 There are many scenarios where it is useful to impose an ordering on a 141 collection at the server, such as expressing a recommended access order, 142 or a revision history order. Orderings may be based on property values, 143 but they may be completely independent of any properties on the 144 resources identified by the collection's internal member URIs. 145 Orderings based on properties can be obtained using a search protocol, 146 but orderings not based on properties need some other mechanism. These 147 orderings generally need to be maintained by a human user. The ordering 148 protocol defined here focuses on support for such human-maintained 149 orderings, but also allows for server-maintained orderings. 151 The remainder of this document is structured as follows: Section 3 152 defines terminology that will be used throughout the specification. 153 Section 4 provides an overview of ordered collections. Section 5 154 describes how to create an ordered collection, and Section 6 discusses 155 how to set a member's position in the ordering of a collection. Section 156 7 explains how to change a collection ordering. Section 8 discusses 157 listing the members of an ordered collection. Sections 9 through 12 158 define the status codes, headers, properties, and XML elements needed to 159 support ordered collections. Section 13 describes capability discovery. 160 Sections 14 through 16 discuss security, internationalization, and IANA 161 considerations. The remaining sections provide supporting information. 163 3 Terminology 165 The terminology used here follows that in the WebDAV Distributed 166 Authoring Protocol specification [WebDAV]. Definitions of the terms 167 resource, Uniform Resource Identifier (URI), and Uniform Resource 168 Locator (URL) are provided in [URI]. Definitions of the terms URI 169 mapping, path segment, binding, collection, and internal member URI are 170 provided in [B]. 172 Ordered Collection 173 A collection for which the results from a PROPFIND request are 174 guaranteed to be in the order specified for that collection 176 Unordered Collection 177 A collection for which the client cannot depend on the 178 repeatability of the ordering of results from a PROPFIND request 180 Client-Maintained Ordering 181 An ordering of collection members that is maintained on the server 182 based on client requests specifying the position of each 183 collection member in the ordering 185 Server-Maintained Ordering 186 An ordering of collection members that is maintained automatically 187 by the server, based on a client's choice of ordering semantics 189 4 Overview of Ordered Collections 191 If a collection is unordered, the client cannot depend on the 192 repeatability of the ordering of results from a PROPFIND request. By 193 specifying an ordering for a collection, a client requires the server to 194 follow that ordering whenever it responds to a PROPFIND request on that 195 collection. 197 These server-side orderings may be client-maintained or server- 198 maintained. For client-maintained orderings, a client must specify the 199 position of each of the collection's bindings in the ordering, either 200 when the binding is added to the collection (using the Position header) 201 or later (using the ORDERPATCH method). For server-maintained 202 orderings, the server automatically positions each of the collection's 203 bindings according to the ordering semantics. 205 A collection that supports ordering may be ordered, but is not required 206 to be. It is up to the client to decide whether a given collection is 207 ordered and, if so, to specify the semantics to be used for ordering its 208 bindings. If a collection is ordered, each of its bindings, and hence 209 internal member URIs, MUST be in the ordering exactly once, and the 210 ordering MUST NOT include any binding that is not contained by the 211 collection. Only one ordering can be attached to any collection. An 212 ordering is considered to be part of the state of a collection resource, 213 and hence is the same across all URI mappings to the collection. 214 Multiple orderings of the same resources can be achieved by creating 215 multiple collections referencing those resources, and attaching a 216 different ordering to each collection. 218 The server is responsible for enforcing these constraints on orderings. 219 The server MUST remove a binding (and its derived internal member URI) 220 from the ordering when it is removed from the collection. The server 221 MUST add a binding (and its derived internal member URI) to the ordering 222 when it is added to the collection. 224 5 Creating an Ordered Collection 226 5.1 Overview 228 When a collection is created, the client MAY request that it be ordered 229 and specify the semantics of the ordering by using the new Ordered 230 header (defined in Section 10.1) with a MKCOL request. 232 For collections that are ordered, the client SHOULD identify the 233 semantics of the ordering with a URI in the Ordered header. This URI 234 may identify a server-maintained ordering. Clients can discover the 235 available server-maintained orderings using the mechanism defined in 236 Section 13.2. The URI may identify a semantics for a client-maintained 237 ordering, providing the information a human user or software package 238 needs to insert new collection members into the ordering intelligently. 239 Although the URI in the Ordered header MAY point to a resource that 240 contains a definition of the semantics of the ordering, clients are 241 discouraged from accessing that resource, in order to avoid 242 overburdening its server. The client MAY set the header value to 243 DAV:custom to indicate that the collection is ordered, but the semantics 244 of the ordering are not being advertised. If the client does not want 245 the collection to be ordered, it may omit the Ordered header, or use it 246 with the value DAV:unordered. 248 If the server does not recognize the value of the Ordered header as one 249 of its server-maintained orderings, it MUST assume that a client- 250 maintained ordering is intended. If the value of the Ordered header is 251 one of the server-maintained orderings that the server supports, it MUST 252 maintain the collection's ordering according to that ordering semantics 253 as new members are added. 255 Every collection MUST have a DAV:orderingtype property (defined in 256 Section 11.1), which indicates whether the collection is ordered and, if 257 so, identifies the semantics of the ordering. The server sets the 258 initial value of this property based on the value of the Ordering header 259 in the MKCOL request. If the collection is unordered, the 260 DAV:orderingtype property MUST have the value DAV:unordered. An 261 ordering-aware client interacting with an ordering-unaware server (e.g., 262 one that is implemented only according to [WebDAV]) SHOULD assume that 263 if a collection does not have the DAV:orderingtype property, the 264 collection is unordered. 266 5.2 Example: Creating an Ordered Collection 268 >>Request: 270 MKCOL /theNorth/ HTTP/1.1 271 Host: www.server.org 272 Ordered: 274 >>Response: 276 HTTP/1.1 201 Created 278 In this example a new, ordered collection was created. Its 279 DAV:orderingtype property has as its value the URI from the Ordered 280 header, http://www.server.org/orderings/compass.html. In this case, the 281 URI identifies the semantics governing a client-maintained ordering. As 282 new members are added to the collection, clients or end users can use 283 the semantics to determine where to position the new members in the 284 ordering. 286 6 Setting the Position of a Collection Member 288 6.1 Overview 290 When a new member is added to a collection with a client-maintained 291 ordering (for example, with PUT, MKREF, or MKCOL), its position in the 292 ordering can be set with the new Position header (defined in Section 293 10.2). The Position header allows the client to specify that the member 294 should be first in the collection's ordering, last in the collection's 295 ordering, immediately before some other binding in the collection's 296 ordering, or immediately after some other binding in the collection's 297 ordering. 299 6.2 Status Codes 301 409 (Conflict): The request specifies a position that is before or after 302 a URI that is not an internal member URI of the collection, or before or 303 after itself. 305 418 (Unordered Collection): The request specifies a collection position 306 in an unordered collection or in a collection with a server-maintained 307 ordering. 309 6.3 Examples: Setting the Position of a Collection Member 311 >> Request: 313 MKREF /~whitehead/dav/spec08.ref HTTP/1.1 314 HOST: www.ics.uci.edu 315 Ref-Target: 316 Position: after 318 >> Response: 320 HTTP/1.1 201 Created 322 This request resulted in the creation of a new referential resource at 323 www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource 324 identified by the Ref-Target header. The Position header in this 325 example caused the server to set its position in the ordering of the 326 /~whitehead/dav/ collection immediately after requirements.html. 328 >> Request: 330 MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 331 Host: www.ics.uci.edu 332 Destination: http://www.ics.uci.edu/~whitehead/dav/draft-webdav- 333 protocol-08.txt 335 Position: first 337 >> Response: 339 HTTP/1.1 418 Unordered Collection 341 In this case, the server returned a 418 (Unordered Collection) status 342 code because the /~whitehead/dav/ collection is an unordered collection. 343 Consequently, the server was unable to satisfy the Position header. 345 7 Changing a Collection Ordering 347 7.1 ORDERPATCH Method 349 The ORDERPATCH method is used to change the ordering semantics of a 350 collection or to change the order of bindings in a client-maintained 351 ordering or both. 353 The ORDERPATCH method changes the ordering semantics of the collection 354 identified by the Request-URI, based on the value of DAV:orderingtype 355 submitted in the request entity body. If the new value identifies a 356 client-maintained ordering, the client is responsible for updating the 357 collection's ordering according to the new semantics. If it identifies 358 a server-maintained ordering, the server MUST reorder the collection 359 according to the new semantics. 361 The ORDERPATCH method alters the ordering of bindings in the collection 362 identified by the Request-URI, based on instructions in the ordermember 363 XML elements in the request entity body. The ordermember XML elements 364 identify the bindings whose positions are to be changed, and describes 365 their new positions in the ordering. Each new position can be specified 366 as first in the ordering, last in the ordering, immediately before some 367 other binding, or immediately after some other binding. 369 The server MUST apply the changes in the order they appear in the order 370 XML element. The server MUST either apply all the changes or apply none 371 of them. If any error occurs during processing, all executed changes 372 MUST be undone and a proper error result returned. 374 7.1.1 Status Codes 376 Since multiple changes can be requested in a single ORDERPATCH request, 377 the server MUST return a 207 (Multi-Status) response, as defined in 378 [WebDAV]. 380 The following are examples of response codes one would expect to be used 381 in a 207 (Multi-Status) response for this method: 383 200 (OK): The change in ordering was successfully made. 385 409 (Conflict): The request specifies a position that is before or after 386 a URI that is not an internal member URI of the collection, or before or 387 after itself. 389 418 (Unordered Collection): The request specifies a collection position 390 in an unordered collection or in a collection with a server-maintained 391 ordering. 393 A request to reposition a binding at the same place in the ordering is 394 not an error. 396 7.1.2 Example: Changing a Collection Ordering 398 Consider a collection /coll-1/ whose DAV:orderingtype is DAV:unordered, 399 with bindings ordered as follows: 401 nunavut.map 402 nunavut.img 403 baffin.map 404 baffin.desc 405 baffin.img 406 iqaluit.map 407 nunavut.desc 408 iqaluit.img 409 iqaluit.desc 411 >> Request: 413 ORDERPATCH /coll-1/ HTTP/1.1 414 Host: www.nunanet.com 415 Content-Type: text/xml 416 Content-Length: xxx 418 419 420 421 http://www.nunanet.com/geog.ord 422 423 424 nunavut.desc 425 426 427 nunavut.map 428 429 430 431 432 iqaluit.img 433 434 435 436 437 439 >> Response: 441 HTTP/1.1 207 Multi-Status 442 Content-Type: text/xml 443 Content-Length: xxx 444 445 446 447 http://www.nunanet.com/coll-1/ 448 449 450 HTTP/1.1 200 OK 451 452 453 454 http://www.nunanet.com/coll-1/nunavut.desc 455 HTTP/1.1 200 OK 456 457 458 http://www.nunanet.com/coll-1/iqaluit.img 459 HTTP/1.1 200 OK 460 461 463 In this example, after the request has been processed, the previously 464 unordered collection has become an ordered collection whose ordering 465 semantics are identified by the URI http://www.nunanet.com/geog.ord. The 466 value of the collection's DAV:orderingtype property has been set to this 467 URI. Since this is a client-maintained ordering, the request also 468 contained instructions for changing the positions of the bindings in the 469 ordering to comply with the new ordering semantics. If href elements are 470 relative URIs, as in this example, they are interpreted relative to the 471 collection whose ordering is being modified. After the request has been 472 processed, the collection's ordering is as follows: 474 nunavut.map 475 nunavut.desc 476 nunavut.img 477 baffin.map 478 baffin.desc 479 baffin.img 480 iqaluit.map 481 iqaluit.desc 482 iqaluit.img 484 7.1.3 Example: Failure of an ORDERPATCH Request 486 Consider a collection /coll-1/ with bindings ordered as follows: 488 nunavut.map 489 nunavut.img 490 baffin.map 491 baffin.desc 492 baffin.img 493 iqaluit.map 494 nunavut.desc 495 iqaluit.img 496 iqaluit.desc 498 >> Request: 500 ORDERPATCH /coll-1/ HTTP/1.1 501 Host: www.nunanet.com 502 Content-Type: text/xml 503 Content-Length: xxx 505 506 507 508 nunavut.desc 509 510 511 nunavut.map 512 513 514 515 516 iqaluit.map 517 518 519 pangnirtung.img 520 521 522 523 525 >> Response: 527 HTTP/1.1 207 Multi-Status 528 Content-Type: text/xml 529 Content-Length: xxx 531 532 533 534 http://www.nunanet.com/coll-1/nunavut.desc 535 HTTP/1.1 424 Failed Dependency 536 537 538 http://www.nunanet.com/coll-1/iqaluit.map 539 HTTP/1.1 409 Conflict 540 pangnirtung.img is not a collection 541 member. 542 543 545 In this example, the client attempted to position iqaluit.map after a 546 binding that is not contained in the collection /coll-1/. The server 547 responded to this client error with a 409 (Conflict) status code. 548 Because ORDERPATCH is an atomic method, the request to reposition 549 nunavut.desc (which would otherwise have succeeded) failed with a 424 550 (Failed Dependency) status code. 552 8 Listing the Members of an Ordered Collection 553 A PROPFIND request is used to retrieve a listing of the members of an 554 ordered collection, just as it is used to retrieve a listing of the 555 members of an unordered collection. 557 However, when responding to a PROPFIND on an ordered collection, the 558 server MUST order the response elements according to the ordering 559 defined on the collection. If a collection is unordered, the client 560 cannot depend on the repeatability of the ordering of results from a 561 PROPFIND request. 563 When responding to a PROPFIND on an ordered collection, the server 564 SHOULD include the DAV:orderingtype property in the DAV:response element 565 for the collection, even if the client did not explicitly request it. 567 8.1 Example: PROPFIND on an Ordered Collection 569 Suppose a PROPFIND request is submitted to the following collection, 570 which has its members ordered according to their distance from the 571 equator. 573 /MyCollection/ 574 lakehazen.html 575 siorapaluk.html 576 iqaluit.html 577 newyork.html 579 >> Request: 581 PROPFIND /MyCollection/ HTTP/1.1 582 Host: www.svr.com 583 Depth: 1 584 Content-Type: text/xml 585 Content-Length: xxxx 587 588 589 590 591 592 593 595 >> Response: 597 HTTP/1.1 207 Multi-Status 598 Content-Type: text/xml 599 Content-Length: xxxx 601 602 604 605 http://www.svr.com/MyCollection/ 606 607 608 609 610 http://www.svr.com/jslatitudedesc 611 612 613 HTTP/1.1 200 OK 614 615 616 617 618 619 HTTP/1.1 404 Not Found 620 621 622 623 http://www.svr.com/MyCollection/lakehazen.html 624 625 626 627 82N 628 629 HTTP/1.1 200 OK 630 631 632 633 http://www.svr.com/MyCollection/siorapaluk.html 634 635 636 637 78N 638 639 HTTP/1.1 200 OK 640 641 642 643 http://www.svr.com/MyCollection/iqaluit.html 644 645 646 647 62N 648 649 HTTP/1.1 200 OK 650 651 652 653 http://www.svr.com/MyCollection/newyork.html 654 655 656 657 45N 658 659 HTTP/1.1 200 OK 660 661 662 663 In this example, the server responded with a list of the collection 664 members ordered according to their distance from the equator, as 665 specified by the value of DAV:orderingtype. Although the client did not 666 explicitly ask for the value of DAV:orderingtype, the server provided it 667 as one of the collection properties, allowing the client to tell that 668 the collection is ordered and to identify the ordering semantics. 670 9 Status Codes 672 9.1 418 Unordered Collection 674 The 418 (Unordered Collection) status code indicates that the client 675 attempted to set the position of an internal collection member in an 676 unordered collection or in a collection with a server-maintained 677 ordering. 679 10 Headers 681 10.1 Ordered Entity Header 683 Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) 685 The Ordered header may be used with MKCOL to request that the new 686 collection be ordered and to specify its ordering semantics. A value of 687 "DAV:unordered" indicates that the collection is not ordered. A value of 688 "DAV:custom" indicates that the collection is to be ordered, but the 689 semantics of the ordering is not being advertised. Any other Coded-url 690 value indicates that the collection is ordered, and identifies the 691 semantics of the ordering. 693 10.2 Position Request Header 695 Position = "Position" ":" ("first" | "last" | 696 (("before" | "after") Generic-Coded-url)) 697 Generic-Coded-url = "<" (absoluteURI | relativeURI) ">" 698 absoluteURI is defined in Section 3 of [URI]. 699 relativeURI is defined in Section 5 of [URI]. 701 The Position header may be used with any method that adds a binding to a 702 collection with a client-maintained ordering, to tell the server where 703 in the collection ordering to position the new binding being added to 704 the collection. Examples of methods that add bindings to collections 705 are BIND, PUT, COPY, MOVE, etc. 707 If the Generic-Coded-url is a relative URL, it is interpreted relative 708 to the collection to which the new binding is being added. 710 The server MUST insert the new binding into the ordering at the location 711 specified in the Position header, if one is present (and if the 712 collection has a client-maintained ordering). 714 The "first" keyword indicates the new binding is put in the beginning 715 position in the collection's ordering, while "last" indicates the new 716 binding is put in the final position in the collection's ordering. The 717 "before" keyword indicates the new binding is added to the collection's 718 ordering immediately prior to the position of the binding identified in 719 the Generic-Coded-url. Likewise, the "after" keyword indicates the new 720 binding is added to the collection's ordering immediately following the 721 position of the binding identified in the Generic-Coded-url. 723 If the request is replacing an existing resource, and the Position 724 header is present, the server MUST remove the binding from its previous 725 position, and then insert it at the requested position. 727 If the Position request header is not used when adding a binding to a 728 collection with a client-maintained ordering, then: 730 o If the request is replacing an existing resource, the server MUST 731 preserve the present ordering. 733 o If the request is adding a new binding to the collection, the server 734 MUST append the new binding to the end of the ordering. 736 If an attempt is made to use the Position header on a collection that is 737 unordered or that has a server-maintained ordering, the server MUST fail 738 the request with a 418 (Unordered) status code. 740 11 Properties 742 11.1 orderingtype Property 744 Name: orderingtype 745 Namespace: DAV: 746 Purpose: Indicates whether the collection is ordered and, if so, 747 uniquely identifies the semantics of the ordering being 748 used. May also point to an explanation of the semantics in 749 human and / or machine-readable form. At a minimum, this 750 allows human users who add members to the collection to 751 understand where to position them in the ordering. This 752 property cannot be set using PROPPATCH. Its value can only 753 be set by including the Ordered header with a MKCOL request 754 or by submitting an ORDERPATCH request. 755 Value: The value unordered indicates that the collection is not 756 ordered. The value custom indicates that the collection is 757 ordered, but the semantics governing the ordering are not 758 being advertised. If the value is an href element, it 759 contains a URI that uniquely identifies the semantics of the 760 collection's ordering. 762 764 12 XML Elements 766 12.1 unordered XML Element 768 Name: unordered 769 Namespace: DAV: 770 Purpose: A value of the DAV:orderingtype property that indicates that 771 the collection is not ordered. That is, the client cannot 772 depend on the repeatability of the ordering of results from 773 a PROPFIND request. 775 777 12.2 custom XML Element 779 Name: custom 780 Namespace: DAV: 781 Purpose: A value of the DAV:orderingtype property that indicates that 782 the collection is ordered, but the semantics of the ordering 783 are not being advertised. 785 787 12.3 order XML Element 789 Name: order 790 Namespace: DAV: 791 Purpose: For use with the new ORDERPATCH method. Describes a change 792 to be made in a collection's ordering semantics or in the 793 positions of its bindings in the ordering or both. 794 Value: An optional identifier of an ordering semantics for the 795 collection, followed by a list of changes to be made in the 796 positions of the bindings in the collection's ordering. 798 800 12.4 ordermember XML Element 802 Name: ordermember 803 Namespace: DAV: 804 Purpose: Occurs in the order XML element, and describes the new 805 position of a single binding in the collection's ordering. 806 Value: An href containing a binding's path segment, and a 807 description of its new position in the ordering. The href 808 XML element is defined in [WebDAV], Section 11.3. 810 812 12.5 position XML Element 814 Name: position 815 Namespace: DAV: 816 Purpose: Occurs in the ordermember XML element. Describes the new 817 position in a collection's ordering of one of the bindings 818 it contains. 819 Value: The new position can be described as first in the 820 collection's ordering, last in the collection's ordering, 821 immediately before some other binding, or immediately after 822 some other binding. 824 826 12.6 first XML Element 827 Name: first 828 Namespace: DAV: 829 Purpose: Occurs in the position XML element. Specifies that the 830 binding should be placed first in the collection's ordering. 832 834 12.7 last XML Element 836 Name: last 837 Namespace: DAV: 838 Purpose: Occurs in the position XML element. Specifies that the 839 binding should be placed last in the collection's ordering. 841 843 12.8 before XML Element 845 Name: before 846 Namespace: DAV: 847 Purpose: Occurs in the position XML element. Specifies that the 848 binding should be placed immediately before the binding in 849 the enclosed href XML element in the collection's ordering. 850 Value: href of the member it precedes in the ordering 852 854 12.9 after XML Element 856 Name: after 857 Namespace: DAV: 858 Purpose: Occurs in the position XML element. Specifies that the 859 binding should be placed immediately after the binding in 860 the enclosed href XML element in the collection's ordering. 861 Value: href of the member it follows in the ordering 863 865 12.10 options XML Element 867 Name: options 868 Namespace: DAV: 869 Purpose: Used in OPTIONS requests to ask for more detailed 870 information about capabilities than can be provided in the 871 DAV: response header. Used in OPTIONS responses to provide 872 that information. 873 Value: List of elements identifying or providing the additional 874 information desired. 876 878 12.11 orderingoptions XML Element 880 Name: orderingoptions 881 Namespace: DAV: 882 Purpose: Used in OPTIONS requests to ask for the list of server- 883 maintained orderings that can be supported at the request- 884 URI. Used in OPTIONS responses to provide that information. 885 These values can be used in the Ordered header or the 886 DAV:orderingtype property to request that a particular 887 server-maintained ordering be applied to the collection. 888 Value: EMPTY on requests. On responses, it is the list of server- 889 maintained orderings available for the request-URI. 891 893 13 Capability Discovery 895 Sections 9.1 and 15 of [WebDAV] describe the use of compliance classes 896 with the DAV header in responses to OPTIONS, to indicate which parts of 897 the Web Distributed Authoring protocols the resource supports. This 898 specification defines an OPTIONAL extension to [WebDAV]. It defines a 899 new compliance class, called orderedcoll, for use with the DAV header in 900 responses to OPTIONS requests. If a collection resource does support 901 ordering, its response to an OPTIONS request MUST indicate that it does, 902 by listing the new ORDERPATCH method as one it supports, and by listing 903 the new orderedcoll compliance class in the DAV header. 905 When responding to an OPTIONS request, only a collection or a null 906 resource can include orderedcoll in the value of the DAV header. By 907 including orderedcoll, the resource indicates that its bindings can be 908 ordered. It implies nothing about whether any collections identified by 909 its internal member URIs can be ordered. 911 13.1 Example: Discovery of Support for Ordering 913 >> Request: 915 OPTIONS /somecollection/ HTTP/1.1 916 HOST: somehost.org 918 >> Response: 920 HTTP/1.1 200 OK 921 Date: Tue, 20 Jan 1998 20:52:29 GMT 922 Connection: close 923 Accept-Ranges: none 924 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 925 PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 926 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 927 PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH 928 DAV: 1, 2, orderedcoll 930 The DAV header in the response indicates that the resource 931 /somecollection/ is level 1 and level 2 compliant, as defined in 932 [WebDAV]. In addition, /somecollection/ supports ordering. The Allow 933 header indicates that ORDERPATCH requests can be submitted to 934 /somecollection/. The Public header shows that other Request-URIs on 935 the server support additional methods. 937 13.2 Additional Capabilities 939 Clients may need detailed information about specific areas of Web 940 Distributed Authoring functionality. This information can be requested 941 by sending an OPTIONS request with an XML body that includes a 942 DAV:options element. The DAV:options element contains a list of empty 943 elements identifying the information the client needs. 945 As described in Section 3, servers may offer a set of server-maintained 946 orderings on collections. Clients can discover the list of server- 947 maintained orderings available for the request-URI by including an empty 948 DAV:orderingoptions element in the DAV:options element. The response 949 will include a DAV:orderingoptions element with the list of supported 950 server-maintained orderings. Servers SHOULD advertise the server- 951 maintained orderings available using this mechanism. 953 13.3 Example: Discovery of Ordering Options 955 >> Request: 957 OPTIONS /somecollection/ HTTP/1.1 958 HOST: somehost.org 960 961 962 963 965 >> Response: 967 HTTP/1.1 200 OK 968 Date: Tue, 20 Jan 1998 20:52:29 GMT 969 Connection: close 970 Accept-Ranges: none 971 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 972 PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 973 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 974 PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH 975 DAV: 1, sharing, orderedcoll 977 978 979 980 981 982 983 984 986 This response indicates that the resource /somecollection/ is level 1 987 compliant, as defined in [WebDAV]. In addition, /somecollection/ 988 supports ordering. The client also asked for a list of the server- 989 maintained orderings that are supported for /somecollection/. The 990 response indicates that the orderings Xerox:author-ascending, 991 Xerox:title-ascending, and Xerox:date-descending are supported. 993 14 Security Considerations 995 This section is provided to make WebDAV applications aware of the 996 security implications of this protocol. 998 All of the security considerations of HTTP/1.1 and the WebDAV 999 Distributed Authoring Protocol specification also apply to this protocol 1000 specification. In addition, ordered collections introduce a new 1001 security concern. This issue is detailed here. 1003 14.1 Denial of Service and DAV:orderingtype 1005 There may be some risk of denial of service at sites that are advertised 1006 in the DAV:orderingtype property of collections. However, it is 1007 anticipated that widely-deployed applications will use hard-coded values 1008 for frequently-used ordering semantics rather than looking up the 1009 semantics at the location specified by DAV:orderingtype. In addition, 1010 Section 3 discourages clients from looking up the semantics at that 1011 location. 1013 15 Internationalization Considerations 1015 This specification follows the practices of [WebDAV] in encoding all 1016 human-readable content using XML [XML] and in the treatment of names. 1017 Consequently, this specification complies with the IETF Character Set 1018 Policy [Alvestrand]. 1020 WebDAV applications MUST support the character set tagging, character 1021 set encoding, and the language tagging functionality of the XML 1022 specification. This constraint ensures that the human-readable content 1023 of this specification complies with [Alvestrand]. 1025 As in [WebDAV}, names in this specification fall into three categories: 1026 names of protocol elements such as methods and headers, names of XML 1027 elements, and names of properties. Naming of protocol elements follows 1028 the precedent of HTTP, using English names encoded in USASCII for 1029 methods and headers. The names of XML elements used in this 1030 specification are English names encoded in UTF-8. 1032 For error reporting, [WebDAV] follows the convention of HTTP/1.1 status 1033 codes, including with each status code a short, English description of 1034 the code (e.g., 423 Locked). Internationalized applications will ignore 1035 this message, and display an appropriate message in the user's language 1036 and character set. 1038 For rationales for these decisions and advice for application 1039 implementors, see [WebDAV]. 1041 16 IANA Considerations 1043 This document uses the namespaces defined by [WebDAV] for properties and 1044 XML elements. All other IANA considerations mentioned in [WebDAV] also 1045 apply to this document. 1047 In addition, this document defines a new HTTP/1.1 status code, 418 1048 (Unordered Collection) defined in Section 9.1. 1050 17 Copyright 1052 To be supplied by the RFC Editor. 1054 18 Intellectual Property 1056 To be supplied by the RFC Editor. 1058 19 Acknowledgements 1060 This draft has benefited from thoughtful discussion by Jim Amsden, Steve 1061 Carter, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Mark Day, 1062 Rajiv Dulepet, David Durand, Roy Fielding, Yaron Goland, Fred Hitt, Alex 1063 Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, 1064 Daniel LaLiberte, Steve Martin, Larry Masinter, Jeff McAffer, Surendra 1065 Koduru Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness, John 1066 Stracke, John Tigue, John Turner, and others. 1068 20 References 1070 [URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource 1071 Identifiers (URI): Generic Syntax." RFC 2396. MIT/LCS, U.C. Irvine, 1072 Xerox. August, 1998. 1074 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement 1075 Levels." RFC 2119, BCP 14. Harvard University. March, 1997. 1077 [XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup 1078 Language (XML)." World Wide Web Consortium Recommendation REC-xml- 1079 19980210. http://www.w3.org/TR/1998/REC-xml-19980210. 1081 [HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. 1082 Leach, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC 1083 2616. UC Irvine, Compaq, W3C, Xerox, Microsoft. June, 1999. 1085 [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. 1086 Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." RFC 2518. 1087 Microsoft, U.C. Irvine, Netscape, Novell. February, 1999. 1089 [B] J. Slein, E.J. Whitehead Jr., J. Davis, G. Clemm, C. Fay, J. 1090 Crawford, T. Chihaya, "WebDAV Bindings." Internet Draft (work in 1091 progress) draft-ietf-webdav-binding-protocol-00. Xerox, UC Irvine, 1092 CourseNet, Rational, FileNet, IBM, DataChannel. August, 1999. 1094 [RR] J. Slein, E.J. Whitehead Jr., J. Davis, G. Clemm, C. Fay, J. 1095 Crawford, T. Chihaya, "WebDAV Redirect References." Internet Draft (work 1096 in progress) draft-ietf-webdav-redirectref-protocol-00. Xerox, UC 1097 Irvine, CourseNet, Rational, FileNet, IBM, DataChannel. August, 1999. 1099 21 Authors' Addresses 1100 J. Slein 1101 Xerox Corporation 1102 800 Phillips Road, 105-50C 1103 Webster, NY 14580 1104 Email: jslein@crt.xerox.com 1106 E. J. Whitehead, Jr. 1107 Dept. of Information and Computer Science 1108 University of California, Irvine 1109 Irvine, CA 92697-3425 1110 Email: ejw@ics.uci.edu 1112 J. Davis 1113 CourseNet Systems 1114 170 Capp Street 1115 San Francisco, CA 94110 1116 Email: jrd3@alum.mit.edu 1118 G. Clemm 1119 Rational Software Corporation 1120 20 Maguire Road 1121 Lexington, MA 02173-3104 1122 Email: gclemm@rational.com 1124 C. Fay 1125 FileNet Corporation 1126 3565 Harbor Boulevard 1127 Costa Mesa, CA 92626-1420 1128 Email: cfay@filenet.com 1130 J. Crawford 1131 IBM 1132 Email: ccjason@us.ibm.com 1134 T. Chihaya 1135 DataChannel, Inc. 1136 155 108th Ave. N.E., Suite 400 1137 Bellevue, WA 98004 1138 Email: Tyson@DataChannel.com 1140 22 Appendices 1142 22.1 Appendix 1: Extensions to the WebDAV Document Type Definition 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1159 Expires April 15, 2000