idnits 2.17.1 draft-ietf-webdav-ordering-protocol-04.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. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 2 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- 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 (January 2003) is 7770 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) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2518 (Obsoleted by RFC 4918) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Slein 3 Internet Draft Xerox 4 Expires: July 2003 J. Whitehead 5 U.C. Santa Cruz 6 J. Crawford 7 IBM 8 J. F. Reschke 9 greenbytes 10 January 2003 12 WebDAV Ordered Collections Protocol 13 draft-ietf-webdav-ordering-protocol-04 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. Internet-Drafts are working 19 documents of the Internet Engineering Task Force (IETF), its areas, 20 and its working groups. Note that other groups may also distribute 21 working documents as Internet-Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress". 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire in July 2003. 36 Copyright Notice 38 Copyright (C) The Internet Society (2003). All Rights Reserved. 40 Abstract 42 This specification extends the WebDAV Distributed Authoring Protocol 43 to support server-side ordering of collection members. Of particular 44 interest are orderings that are not based on property values, and so 45 cannot be achieved using a search protocol's ordering option and 46 cannot be maintained automatically by the server. Protocol elements 47 are defined to let clients specify the position in the ordering of 48 each collection member, as well as the semantics governing the 49 ordering. 51 Distribution of this document is unlimited. Please send comments to 52 the Distributed Authoring and Versioning (WebDAV) working group at 53 w3c-dist-auth@w3.org, which may be joined by sending a message with 54 subject "subscribe" to w3c-dist-auth-request@w3.org. 56 Discussions of the WEBDAV working group are archived at URL: 57 http://lists.w3.org/Archives/Public/w3c-dist-auth/. 59 Table of Contents 61 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 62 Table of Contents . . . . . . . . . . . . . . . . . . . . . . 3 63 1 Notational Conventions . . . . . . . . . . . . . . . . . . . 4 64 2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6 66 4 Overview of Ordered Collections . . . . . . . . . . . . . . 7 67 4.1 Additional Collection properties . . . . . . . . . . . . 7 68 4.1.1 DAV:orderingtype (protected) . . . . . . . . . . . . 8 69 5 Creating an Ordered Collection . . . . . . . . . . . . . . . 9 70 5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 9 71 5.2 Example: Creating an Ordered Collection . . . . . . . . 10 72 6 Setting the Position of a Collection Member . . . . . . . . 11 73 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 11 74 6.2 Examples: Setting the Position of a Collection Member . 12 75 7 Changing a Collection Ordering: ORDERPATCH method . . . . . 14 76 7.1 Example: Changing a Collection Ordering . . . . . . . . 16 77 7.2 Example: Failure of an ORDERPATCH Request . . . . . . . 18 78 8 Listing the Members of an Ordered Collection . . . . . . . . 20 79 8.1 Example: PROPFIND on an Ordered Collection . . . . . . . 20 80 9 Relationship to versioned collections . . . . . . . . . . . 24 81 9.1 Additional semantics for collection version properties . 24 82 10 Capability Discovery . . . . . . . . . . . . . . . . . . . 25 83 10.1 Example: Using OPTIONS for the Discovery of Support for 84 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 85 10.2 Example: Using Live Properties for the Discovery of 86 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 87 11 Security Considerations . . . . . . . . . . . . . . . . . . 28 88 11.1 Denial of Service and DAV:orderingtype . . . . . . . . 28 89 12 Internationalization Considerations . . . . . . . . . . . . 29 90 13 IANA Considerations . . . . . . . . . . . . . . . . . . . . 30 91 14 Copyright . . . . . . . . . . . . . . . . . . . . . . . . . 31 92 15 Intellectual Property . . . . . . . . . . . . . . . . . . . 32 93 16 Acknowledgements . . . . . . . . . . . . . . . . . . . . . 33 94 Normative References . . . . . . . . . . . . . . . . . . . . . 34 95 Author's Addresses . . . . . . . . . . . . . . . . . . . . . . 34 96 A Extensions to the WebDAV Document Type Definition . . . . . 36 97 B Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 37 98 B.1 Since draft-ietf-webdav-ordering-protocol dated December 99 1999 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 100 B.2 Since draft-ietf-webdav-ordering-protocol-02 . . . . . . 37 101 B.3 Since draft-ietf-webdav-ordering-protocol-03 . . . . . . 37 102 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 104 1 Notational Conventions 106 Since this document describes a set of extensions to the WebDAV 107 Distributed Authoring Protocol [RFC2518], itself an extension to the 108 HTTP/1.1 protocol, the augmented BNF used here to describe protocol 109 elements is exactly the same as described in Section 2.1 of HTTP 110 [RFC2616]. Since this augmented BNF uses the basic production rules 111 provided in Section 2.2 of HTTP, these rules apply to this document 112 as well. 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 116 document are to be interpreted as described in [RFC2119]. 118 2 Introduction 120 This specification builds on the collection infrastructure provided 121 by the WebDAV Distributed Authoring Protocol, adding support for the 122 server-side ordering of collection members. 124 There are many scenarios where it is useful to impose an ordering on 125 a collection at the server, such as expressing a recommended access 126 order, or a revision history order. The members of a collection might 127 represent the pages of a book, which need to be presented in order if 128 they are to make sense. Or an instructor might create a collection of 129 course readings, which she wants to be displayed in the order they 130 are to be read. 132 Orderings may be based on property values, but this is not always the 133 case. The resources in the collection may not have properties that 134 can be used to support the desired ordering. Orderings based on 135 properties can be obtained using a search protocol's ordering option, 136 but orderings not based on properties cannot. These orderings 137 generally need to be maintained by a human user. 139 The ordering protocol defined here focuses on support for such human- 140 maintained orderings. Its protocol elements allow clients to specify 141 the position of each collection member in the collection's ordering, 142 as well as the semantics governing the ordering. The protocol is 143 designed to allow support to be added in the future for orderings 144 that are maintained automatically by the server. 146 The remainder of this document is structured as follows: section 3 147 defines terminology that will be used throughout the specification. 148 Section 4 provides an overview of ordered collections. Section 5 149 describes how to create an ordered collection, and section 6 150 discusses how to set a member's position in the ordering of a 151 collection. Section 7 explains how to change a collection ordering. 152 Section 8 discusses listing the members of an ordered collection. 153 section 9 discusses the impact on version-controlled collections (as 154 defined in [RFC3253]. Section 10 describes capability discovery. 155 Section 11 through section 13 discuss security, internationalization, 156 and IANA considerations. The remaining sections provide supporting 157 information. 159 3 Terminology 161 The terminology used here follows that in [RFC2518]and [RFC3253]. 162 Definitions of the terms resource, Uniform Resource Identifier (URI), 163 and Uniform Resource Locator (URL) are provided in [RFC2396]. 165 Ordered Collection 167 A collection for which the results from a PROPFIND request are 168 guaranteed to be in the order specified for that collection 170 Unordered Collection 172 A collection for which the client cannot depend on the 173 repeatability of the ordering of results from a PROPFIND request 175 Client-Maintained Ordering 177 An ordering of collection members that is maintained on the server 178 based on client requests specifying the position of each 179 collection member in the ordering 181 Server-Maintained Ordering 183 An ordering of collection members that is maintained automatically 184 by the server, based on a client's choice of ordering semantics 186 This document uses the terms "precondition" as "postcondition" as 187 defined in [RFC3253]. Servers should report pre-/postcondition 188 failures as described in section 1.6 of this document. 190 4 Overview of Ordered Collections 192 If a collection is unordered, the client cannot depend on the 193 repeatability of the ordering of results from a PROPFIND request. By 194 specifying an ordering for a collection, a client requires the server 195 to follow that ordering whenever it responds to a PROPFIND request on 196 that collection. 198 Server-side orderings may be client-maintained or server-maintained. 199 For client-maintained orderings, a client must specify the ordering 200 position of each of the collection's members, either when the member 201 is added to the collection (using the Position header) or later 202 (using the ORDERPATCH method). For server-maintained orderings, the 203 server automatically positions each of the collection's members 204 according to the ordering semantics. This specification supports only 205 client-maintained orderings, but is designed to allow future 206 extension to server-maintained orderings. 208 A collection that supports ordering is not required to be ordered. 210 If a collection is ordered, each of its internal member URIs MUST be 211 in the ordering exactly once, and the ordering MUST NOT include any 212 URI that is not an internal member of the collection. The server is 213 responsible for enforcing these constraints on orderings. The server 214 MUST remove an internal member URI from the ordering when it is 215 removed from the collection. The server MUST add an internal member 216 URI to the ordering when it is added to the collection. 218 Only one ordering can be attached to any collection. Multiple 219 orderings of the same resources can be achieved by creating multiple 220 collections referencing those resources, and attaching a different 221 ordering to each collection. 223 An ordering is considered to be part of the state of a collection 224 resource. Consequently, the ordering is the same no matter which URI 225 is used to access the collection and is protected by locks or access 226 control constraints on the collection. 228 4.1 Additional Collection properties 230 A DAV:allprop PROPFIND request SHOULD NOT return any of the 231 properties defined in this document. 233 4.1.1 DAV:orderingtype (protected) 235 Indicates whether the collection is ordered and, if so, uniquely 236 identifies the semantics of the ordering being used. May also point 237 to an explanation of the semantics in human and / or machine-readable 238 form. At a minimum, this allows human users who add members to the 239 collection to understand where to position them in the ordering. This 240 property cannot be set using PROPPATCH. Its value can only be set by 241 including the Ordered header with a MKCOL request or by submitting an 242 ORDERPATCH request. 244 The value DAV:unordered indicates that the collection is not ordered. 245 That is, the client cannot depend on the repeatability of the 246 ordering of results from a PROPFIND request. 248 The value DAV:custom indicates that the collection is ordered, but 249 the semantics governing the ordering are not being advertised. 251 If the value is a DAV:href element, it contains a URI that uniquely 252 identifies the semantics of the collection's ordering. 254 An ordering-aware client interacting with an ordering-unaware server 255 (e.g., one that is implemented only according to [RFC2518]) SHOULD 256 assume that if a collection does not have the DAV:orderingtype 257 property, the collection is unordered. 259 260 261 263 5 Creating an Ordered Collection 265 5.1 Overview 267 When a collection is created, the client MAY request that it be 268 ordered and specify the semantics of the ordering by using the new 269 Ordered header (defined below) with a MKCOL request. 271 For collections that are ordered, the client SHOULD identify the 272 semantics of the ordering with a URI in the Ordered header, although 273 the client MAY simply set the header value to DAV:custom to indicate 274 that the collection is ordered but the semantics of the ordering are 275 not being advertised. Setting the value to a URI that identifies the 276 ordering semantics provides the information a human user or software 277 package needs to insert new collection members into the ordering 278 intelligently. Although the URI in the Ordered header MAY point to a 279 resource that contains a definition of the semantics of the ordering, 280 clients SHOULD NOT access that resource, in order to avoid 281 overburdening its server. A value of DAV:unordered in the Ordering 282 header indicates that the client wants the collection to be 283 unordered. If the Ordered header is not present, the collection will 284 be unordered. 286 Additional Marshalling: 288 Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) 290 A value of "DAV:unordered" indicates that the collection is not 291 ordered. A value of "DAV:custom" indicates that the collection is 292 to be ordered, but the semantics of the ordering is not being 293 advertised. Any other Coded-url value indicates that the 294 collection is ordered, and identifies the semantics of the 295 ordering. 297 Additional Preconditions: 299 (DAV:ordered-collections-supported): the server must support 300 ordered collections where the new collection is to be created. 302 Additional Postconditions: 304 (DAV:orderdingtype-set): the collection was created with the 305 specified ordering semantics. 307 5.2 Example: Creating an Ordered Collection 309 >> Request: 311 MKCOL /theNorth/ HTTP/1.1 312 Host: example.org 313 Ordered: 315 >> Response: 317 HTTP/1.1 201 Created 319 In this example a new, ordered collection was created. Its 320 DAV:orderingtype property has as its value the URI from the Ordered 321 header, http://example.org/orderings/compass.html. In this case, the 322 URI identifies the semantics governing a client-maintained ordering. 323 As new members are added to the collection, clients or end users can 324 use the semantics to determine where to position the new members in 325 the ordering. 327 6 Setting the Position of a Collection Member 329 6.1 Overview 331 When a new member is added to a collection with a client-maintained 332 ordering (for example, with PUT, COPY, or MKCOL), its position in the 333 ordering can be set with the new Position header. The Position header 334 allows the client to specify that an internal member URI should be 335 first in the collection's ordering, last in the collection's 336 ordering, immediately before some other internal member URI in the 337 collection's ordering, or immediately after some other internal 338 member URI in the collection's ordering. 340 If the Position request header is not used when adding a member to an 341 ordered collection, then: 343 o If the request is replacing an existing resource, the server MUST 344 preserve the present ordering. 346 o If the request is adding a new internal member URI to the 347 collection, the server MUST append the new member to the end of 348 the ordering. 350 Additional Marshalling: 352 Position = "Position" ":" ("first" | "last" | 353 (("before" | "after") segment)) 355 segment is defined in Section 3.3 of [RFC2396]. 357 The segment is interpreted relative to the collection to which the 358 new member is being added. 360 The server MUST insert the new member into the ordering at the 361 location specified in the Position header, if one is present (and 362 if the collection is ordered). 364 The "first" keyword indicates the new member is put in the 365 beginning position in the collection's ordering, while "last" 366 indicates the new member is put in the final position in the 367 collection's ordering. The "before" keyword indicates the new 368 member is added to the collection's ordering immediately prior to 369 the position of the member identified in the segment. Likewise, 370 the "after" keyword indicates the new member is added to the 371 collection's ordering immediately following the position of the 372 member identified in the segment. 374 If the request is replacing an existing resource, and the Position 375 header is present, the server MUST remove the internal member URI 376 from its previous position, and then insert it at the requested 377 position. 379 Additional Preconditions: 381 (DAV:collection-must-be-ordered): the target collection must be 382 ordered. 384 (DAV:segment-must-identify-member): the referenced segment must 385 identify a resource that exists and is different from the affected 386 resource. 388 Additional Postconditions: 390 (DAV:position-set): the newly created collection member was 391 created at the specified position. 393 6.2 Examples: Setting the Position of a Collection Member 395 >> Request: 397 COPY /~user/dav/spec08.html HTTP/1.1 398 Host: example.org 399 Destination: http://example.org/~slein/dav/spec08.html 400 Position: after requirements.html 402 >> Response: 404 HTTP/1.1 201 Created 405 This request resulted in the creation of a new resource at 406 example.org/~slein/dav/spec08.html. The Position header in this 407 example caused the server to set its position in the ordering of the 408 /~slein/dav/ collection immediately after requirements.html. 410 >> Request: 412 MOVE /i-d/draft-webdav-prot-08.txt HTTP/1.1 413 Host: example.org 414 Destination: http://example.org/~user/dav/draft-webdav-prot-08.txt 415 Position: first 417 >> Response: 419 HTTP/1.1 409 Conflict 420 Content-Type: text/xml; charset="utf-8" 421 Content-Length: xxxx 423 424 425 426 428 In this case, the server returned a 409 (Conflict) status code 429 because the /~user/dav/ collection is an unordered collection. 430 Consequently, the server was unable to satisfy the Position header. 432 7 Changing a Collection Ordering: ORDERPATCH method 434 The ORDERPATCH method is used to change the ordering semantics of a 435 collection or to change the order of the collection's members in the 436 ordering or both. 438 The server MUST apply the changes in the order they appear in the 439 order XML element. The server MUST either apply all the changes or 440 apply none of them. If any error occurs during processing, all 441 executed changes MUST be undone and a proper error result returned. 443 If an ORDERPATCH request changes the ordering semantics, but does not 444 completely specify the order of the collection members, the server 445 MUST assign a position in the ordering to each collection member for 446 which a position was not specified. These server-assigned positions 447 MUST all follow the last one specified by the client. The result is 448 that all members for which the client specified a position are at the 449 beginning of the ordering, followed by any members for which the 450 server assigned positions. 452 If an ORDERPATCH request does not change the ordering semantics, any 453 member positions not specified in the request MUST remain unchanged. 455 A request to reposition a collection member at the same place in the 456 ordering is not an error. 458 Additional Marshalling: 460 The request body MUST be DAV:order element. 462 464 465 466 467 468 469 470 472 PCDATA value: segment, as defined in section 3.3 of [RFC2396]. 474 DAV:href value: segment part of collection member. 476 The DAV:orderingtype property is modified according to the 477 DAV:orderingtype element. 479 The ordering of internal member URIs in the collection identified 480 by the Request-URI is changed based on instructions in the 481 ordermember XML elements. The ordermember XML elements identify 482 the internal member URIs whose positions are to be changed, and 483 describe their new positions in the ordering. Each new position 484 can be specified as first in the ordering, last in the ordering, 485 immediately before some other internal member URI, or immediately 486 after some other internal member URI. 488 If a response body for a successful request is included, it MUST 489 be a DAV:orderpatch-response XML element. Note that this document 490 does not define any elements for the ORDERPATCH response body, but 491 the DAV:orderpatch-response element is defined to ensure 492 interoperability between future extensions that do define elements 493 for the ORDERPATCH response body. 495 497 Since multiple changes can be requested in a single ORDERPATCH 498 request, if any problems are encountered, the server MUST return a 499 207 (Multi-Status) response (defined in [RFC2518]), containing 500 DAV:response elements for either the request-URI (when the 501 DAV:orderingtype could not be modified) or URIs of collection 502 members to be repositioned (when an invidual positioning request 503 expressed as DAV:ordermember could not be fulfilled). 505 Preconditions: 507 (DAV:collection-must-be-ordered): see section 6.1. 509 (DAV:segment-must-identify-member): see section 6.1. 511 Postconditions: 513 (DAV:orderdingtype-set): if the request body contained a 514 DAV:orderingtype element, the DAV:orderingtype property (see 515 section 4.1.1) of the collection identified by the request-URI was 516 set accordingly. 518 (DAV:orderding-modified): if the request body contained 519 DAV:ordermember elements, the ordering of internal member URIs in 520 the collection identified by the request-URI has been changed 521 based on instructions in the DAV:ordermember elements. 523 7.1 Example: Changing a Collection Ordering 525 Consider a collection /coll-1/ whose DAV:orderingtype is DAV:whim, 526 with bindings ordered as follows: 528 three.html 529 four.html 530 one.html 531 two.html 533 >> Request: 535 ORDERPATCH /coll-1/ HTTP/1.1 536 Host: example.org 537 Content-Type: text/xml; charset="utf-8" 538 Content-Length: xxx 540 541 542 543 http://example.org/inorder.ord 544 545 546 two.html 547 548 549 550 551 552 one.html 553 554 556 557 558 559 three.html 560 561 562 563 564 565 four.html 566 567 568 569 570 572 >> Response: 574 HTTP/1.1 200 OK 576 In this example, after the request has been processed, the 577 collection's ordering semantics are identified by the URI 578 http://example.org/inorder.ord. The value of the collection's 579 DAV:orderingtype property has been set to this URI. The request also 580 contains instructions for changing the positions of the collection's 581 internal member URIs in the ordering to comply with the new ordering 582 semantics. If href elements are relative URIs, as in this example, 583 they are interpreted relative to the collection whose ordering is 584 being modified. The DAV:ordermember elements are required to be 585 processed in the order they appear in the request. Consequently, 586 two.html is moved to the beginning of the ordering, and then one.html 587 is moved to the beginning of the ordering. Then three.html is moved 588 to the end of the ordering, and finally four.html is moved to the end 589 of the ordering. After the request has been processed, the 590 collection's ordering is as follows: 592 one.html 593 two.html 594 three.html 595 four.html 597 7.2 Example: Failure of an ORDERPATCH Request 599 Consider a collection /coll-1/ with members ordered as follows: 601 nunavut.map 602 nunavut.img 603 baffin.map 604 baffin.desc 605 baffin.img 606 iqaluit.map 607 nunavut.desc 608 iqaluit.img 609 iqaluit.desc 611 >> Request: 613 ORDERPATCH /coll-1/ HTTP/1.1 614 Host: www.nunanet.com 615 Content-Type: text/xml; charset="utf-8" 616 Content-Length: xxx 618 619 620 621 nunavut.desc 622 623 624 nunavut.map 625 626 627 628 629 iqaluit.map 630 631 632 pangnirtung.img 633 634 635 636 637 >> Response: 639 HTTP/1.1 207 Multi-Status 640 Content-Type: text/xml; charset="utf-8" 641 Content-Length: xxx 643 644 645 646 http://www.nunanet.com/coll-1/iqaluit.map 647 HTTP/1.1 403 Forbidden 648 649 650 pangnirtung.img is not a collection member. 651 652 653 655 In this example, the client attempted to position iqaluit.map after a 656 URI that is not an internal member of the collection /coll-1/. The 657 server responded to this client error with a 403 (Forbidden) status 658 code, indicating the failed precondition DAV:segment-must-identify- 659 member. Because ORDERPATCH is an atomic method, the request to 660 reposition nunavut.desc (which would otherwise have succeeded) failed 661 as well, but doesn't need to be expressed in the multistatus response 662 body. 664 8 Listing the Members of an Ordered Collection 666 A PROPFIND request is used to retrieve a listing of the members of an 667 ordered collection, just as it is used to retrieve a listing of the 668 members of an unordered collection. 670 However, when responding to a PROPFIND on an ordered collection, the 671 server MUST order the response elements according to the ordering 672 defined on the collection. If a collection is unordered, the client 673 cannot depend on the repeatability of the ordering of results from a 674 PROPFIND request. 676 In a response to a PROPFIND with Depth: infinity, members of 677 different collections may be interleaved. That is, the server is not 678 required to do a breadth-first traversal. The only requirement is 679 that the members of any ordered collection appear in the order 680 defined for the collection. Thus for the hierarchy illustrated in the 681 following figure, where collection A is an ordered collection with 682 the ordering B C D, 684 A 685 /|\ 686 / | \ 687 B C D 688 / /|\ 689 E F G H 691 it would be acceptable for the server to return response elements in 692 the order A B E C F G H D. In this response, B, C, and D appear in 693 the correct order, separated by members of other collections. Clients 694 can use a series of Depth: 1 PROPFIND requests to avoid the 695 complexity of processing Depth: infinity responses based on depth- 696 first traversals. 698 8.1 Example: PROPFIND on an Ordered Collection 700 Suppose a PROPFIND request is submitted to /MyColl/, which has its 701 members ordered as follows. 703 /MyColl/ 704 lakehazen.html 705 siorapaluk.html 706 iqaluit.html 707 newyork.html 709 >> Request: 711 PROPFIND /MyColl/ HTTP/1.1 712 Host: example.org 713 Depth: 1 714 Content-Type: text/xml; charset="utf-8" 715 Content-Length: xxxx 717 718 719 720 721 722 723 724 726 >> Response: 728 HTTP/1.1 207 Multi-Status 729 Content-Type: text/xml; charset="utf-8" 730 Content-Length: xxxx 732 733 735 736 http://example.org/MyColl/ 737 738 739 740 741 742 HTTP/1.1 200 OK 743 744 745 746 747 748 HTTP/1.1 404 Not Found 749 750 751 752 http://example.org/MyColl/lakehazen.html 753 754 755 756 82N 757 758 HTTP/1.1 200 OK 759 760 761 762 763 764 HTTP/1.1 404 Not Found 765 766 767 768 http://example.org/MyColl/siorapaluk.html 770 771 772 773 78N 774 775 HTTP/1.1 200 OK 776 777 778 779 780 781 HTTP/1.1 404 Not Found 782 783 784 785 http://example.org/MyColl/iqaluit.html 786 787 788 789 62N 790 791 HTTP/1.1 200 OK 792 793 794 795 796 797 HTTP/1.1 404 Not Found 798 799 800 801 http://example.org/MyColl/newyork.html 802 803 804 805 45N 806 807 HTTP/1.1 200 OK 808 809 810 811 812 HTTP/1.1 404 Not Found 813 814 815 816 818 In this example, the server responded with a list of the collection 819 members in the order defined for the collection. 821 9 Relationship to versioned collections 823 The Versioning Extensions to WebDAV [RFC3253] introduce the concept 824 of versioned collections, recording both the dead properties and the 825 set of internal version-controlled bindings. This section defines how 826 this feature interacts with ordered collections. 828 This specification considers both the ordering type (DAV:orderingtype 829 property) and the ordering of collection members to be part of the 830 state of a collection. Therefore both MUST be recorded upon CHECKIN 831 or VERSION-CONTROL, and both MUST be restored upon CHECKOUT, 832 UNCHECKOUT or UPDATE (where for compatibility with RFC3253, only the 833 ordering of version-controlled members needs to be maintained). 835 9.1 Additional semantics for collection version properties 837 Although this specification defines the property DAV:orderingtype to 838 be protected, it MUST be recorded in a collection version. 840 The property DAV:version-controlled-binding-set ([RFC3253], section 841 14.2.1) records the set of version-controlled bindings in the 842 collection. For ordered collections, the DAV:version-controlled- 843 binding elements MUST appear in the ordering defined for the checked- 844 in ordered collection. 846 10 Capability Discovery 848 Sections 9.1 and 15 of [RFC2518] describe the use of compliance 849 classes with the DAV header in responses to OPTIONS, to indicate 850 which parts of the Web Distributed Authoring protocols the resource 851 supports. This specification defines an OPTIONAL extension to 852 [RFC2518]. It defines a new compliance class, called orderedcoll, for 853 use with the DAV header in responses to OPTIONS requests. If a 854 collection resource does support ordering, its response to an OPTIONS 855 request may indicate that it does, by listing the new ORDERPATCH 856 method as one it supports, and by listing the new orderedcoll 857 compliance class in the DAV header. 859 When responding to an OPTIONS request, only a collection or a null 860 resource can include orderedcoll in the value of the DAV header. By 861 including orderedcoll, the resource indicates that its internal 862 member URIs can be ordered. It implies nothing about whether any 863 collections identified by its internal member URIs can be ordered. 865 Furthermore, RFC 3253 [RFC3253] introduces the live properties 866 DAV:supported-method-set (section 3.1.3) and DAV:supported-live- 867 property-set (section 3.1.4). Servers MUST support these properties 868 as defined in RFC 3253. 870 10.1 Example: Using OPTIONS for the Discovery of Support for Ordering 872 >> Request: 874 OPTIONS /somecollection/ HTTP/1.1 875 Host: example.org 877 >> Response: 879 HTTP/1.1 200 OK 880 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE 881 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 882 DAV: 1, 2, orderedcoll 884 The DAV header in the response indicates that the resource 885 /somecollection/ is level 1 and level 2 compliant, as defined in 886 [RFC2518]. In addition, /somecollection/ supports ordering. The Allow 887 header indicates that ORDERPATCH requests can be submitted to 888 /somecollection/. 890 10.2 Example: Using Live Properties for the Discovery of Ordering 892 >> Request: 894 PROPFIND /somecollection HTTP/1.1 895 Depth: 0 896 Content-Type: text/xml; charset="utf-8" 897 Content-Length: xxx 899 900 901 902 903 904 905 907 >> Response: 909 HTTP/1.1 207 Multi-Status 910 Content-Type: text/xml; charset="utf-8" 911 Content-Length: xxx 913 914 915 916 http://example.org/somecollection 917 918 919 920 921 922 923 ... other live properties omitted for brevity ... 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 HTTP/1.1 200 OK 944 945 946 948 Note that actual responses MUST contain a complete list of supported 949 live properties. 951 11 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 958 protocol specification. In addition, ordered collections introduce a 959 new security concern. This issue is detailed here. 961 11.1 Denial of Service and DAV:orderingtype 963 There may be some risk of denial of service at sites that are 964 advertised in the DAV:orderingtype property of collections. However, 965 it is anticipated that widely-deployed applications will use hard- 966 coded values for frequently-used ordering semantics rather than 967 looking up the semantics at the location specified by 968 DAV:orderingtype. This risk will be further reduced if clients 969 observe the recommendation of section 5.1 that they not send requests 970 to the URI in DAV:orderingtype. 972 12 Internationalization Considerations 974 This specification follows the practices of [RFC2518] in encoding all 975 human-readable content using [XML] and in the treatment of names. 976 Consequently, this specification complies with the IETF Character Set 977 Policy [RFC2277]. 979 WebDAV applications MUST support the character set tagging, character 980 set encoding, and the language tagging functionality of the XML 981 specification. This constraint ensures that the human-readable 982 content of this specification complies with [RFC2277]. 984 As in [RFC2518], names in this specification fall into three 985 categories: names of protocol elements such as methods and headers, 986 names of XML elements, and names of properties. Naming of protocol 987 elements follows the precedent of HTTP, using English names encoded 988 in USASCII for methods and headers. The names of XML elements used in 989 this specification are English names encoded in UTF-8. 991 For error reporting, [RFC2518] follows the convention of HTTP/1.1 992 status codes, including with each status code a short, English 993 description of the code (e.g., 423 Locked). Internationalized 994 applications will ignore this message, and display an appropriate 995 message in the user's language and character set. 997 This specification introduces no new strings that are displayed to 998 users as part of normal, error-free operation of the protocol. 1000 For rationales for these decisions and advice for application 1001 implementors, see [RFC2518]. 1003 13 IANA Considerations 1005 This document uses the namespaces defined by [RFC2518] for properties 1006 and XML elements. All other IANA considerations mentioned in 1007 [RFC2518] also apply to this document. 1009 14 Copyright 1011 To be supplied by the RFC Editor. 1013 15 Intellectual Property 1015 To be supplied by the RFC Editor. 1017 16 Acknowledgements 1019 This draft has benefited from thoughtful discussion by Jim Amsden, 1020 Steve Carter, Tyson Chihaya, Geoff Clemm, Ken Coar, Ellis Cohen, 1021 Bruce Cragun, Jim Davis, Spencer Dawkins, Mark Day, Rajiv Dulepet, 1022 David Durand, Chuck Fay, Roy Fielding, Yaron Goland, Fred Hitt, Alex 1023 Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, 1024 Daniel LaLiberte, Lisa Lippert, Steve Martin, Larry Masinter, Jeff 1025 McAffer, Surendra Koduru Reddy, Max Rible, Sam Ruby, Bradley 1026 Sergeant, Nick Shelness, John Stracke, John Tigue, John Turner, Kevin 1027 Wiggen, and others. 1029 Normative References 1031 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1032 Requirement Levels", BCP 14, RFC 2119, March 1997. 1034 [RFC2277] Alvestrand, H.T., "IETF Policy on Character Sets and 1035 Languages", BCP 18, RFC 2277, January 1998. 1037 [RFC2396] Berners-Lee, T., Fielding, R.T. and Masinter, L., "Uniform 1038 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1039 August 1998. 1041 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S.R. and 1042 Jensen, D., "HTTP Extensions for Distributed Authoring -- 1043 WEBDAV", RFC 2518, February 1999. 1045 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1046 Masinter, L., Leach, P. and Berners-Lee, T., "Hypertext 1047 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1049 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and 1050 Whitehead, J., "Versioning Extensions to WebDAV", RFC 1051 3253, March 2002. 1053 [XML] World Wide Web Consortium, "Extensible Markup Language 1054 (XML) 1.0", W3C XML, February 1998. 1056 Author's Addresses 1058 Judith Slein 1059 Xerox Corporation 1060 800 Phillips Road, 105-50C 1061 Webster, NY 14580 1063 EMail: jslein@crt.xerox.com 1065 Jim Whitehead 1066 UC Santa Cruz, Dept. of Computer Science 1067 1156 High Street 1068 Santa Cruz, CA 95064 1069 US 1071 EMail: ejw@cse.ucsc.edu 1072 Jason Crawford 1073 IBM Research 1074 P.O. Box 704 1075 Yorktown Heights, NY 10598 1077 EMail: ccjason@us.ibm.com 1079 Julian F. Reschke 1080 greenbytes GmbH 1081 Salzmannstrasse 152 1082 Muenster, NW 48159 1083 Germany 1085 Phone: +49 251 2807760 1086 Fax: +49 251 2807761 1087 EMail: julian.reschke@greenbytes.de 1088 URI: http://greenbytes.de/tech/webdav/ 1090 A Extensions to the WebDAV Document Type Definition 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1106 B Change Log 1108 B.1 Since draft-ietf-webdav-ordering-protocol dated December 1999 1110 Updated contact information for all previous authors. 1111 Specify charset when using text/xml media type. 1112 Made sure artwork fits into 72 columns. 1113 Removed "Public" header from OPTIONS example. 1114 Added Julian Reschke to list of authors. 1115 Fixed broken XML in PROPFIND example and added DAV:orderingtype to 1116 list of requested properties. 1117 Added support for DAV:supported-live-property-set and DAV:supported- 1118 method-set as mandatory features. 1120 B.2 Since draft-ietf-webdav-ordering-protocol-02 1122 Updated change log to refer to expired draft version as "December 1123 1999" version. 1124 Started rewrite marshalling in RFC3253-style and added precondition 1125 and postcondition definitions. 1126 On his request, removed Geoff Clemm's name from the author list 1127 (moved to Acknowledgments). 1128 Renamed "References" to "Normative References". 1129 Removed reference to "MKREF" method. 1131 B.3 Since draft-ietf-webdav-ordering-protocol-03 1133 Added a set of issues regarding marshalling. 1134 Changed host names to use proper "example" domain names (no change 1135 tracking). Fixed host/destination header conflicts. Fixed "allow" 1136 header (multiline). Removed irrelevant response headers. Abbreviated 1137 some URIs (no change tracking). 1138 Removed Jim Davis and Chuck Fay from the author list (and added them 1139 to the Acknowledgements section). 1140 Updated section on setting the position when adding new members, 1141 removed old section on Position header. 1142 Started work on Index section. 1143 Changed structure for section 7 (no change tracking). 1144 Removed header and XML elements section (contents moved to other 1145 sections). 1146 Started new section on relation to versioned collections as per 1147 RFC3253. 1148 Do not return 424's for in ODERPATCH multistatus (it's atomic 1149 anyway). 1151 Index 1153 C O 1155 Client-Maintained Ordering Ordered Collection 1156 3 3 1157 Ordered header 1158 5.1 1159 ORDERPATCH method 1160 D 7 1162 DAV:collection-must-be-ordered 1163 precondition P 1164 6.1 1165 DAV:custom ordering type 1166 4.1.1 Postconditions 1167 DAV:ordered-collections- DAV:orderingtype-set 5.1,7 1168 supported precondition DAV:position-set 6.1 1169 5.1 DAV:orderingtype-set 5.1,7 1170 DAV:ordering-modified DAV:ordering-modified 7 1171 postcondition 1172 7 Preconditions 1173 DAV:orderingtype property DAV:ordered-collections- 1174 4.1.1 supported 5.1 1175 DAV:orderingtype-set DAV:collection-must-be- 1176 postcondition ordered 6.1 1177 5.1,7 DAV:segment-must-identify- 1178 DAV:position-set postcondition member 6.1 1179 6.1 1180 DAV:segment-must-identify- Protected properties 1181 member precondition DAV:orderingtype 4.1.1 1182 6.1 1183 DAV:unordered ordering type 1184 4.1.1 1186 S 1188 H 1189 Server-Maintained Ordering 1190 3 1191 Headers 1192 Ordered 5.1 1194 U 1196 Unordered Collection 1197 3 1199 Full Copyright Statement 1201 Copyright (C) The Internet Society (2003). All Rights Reserved. 1203 This document and translations of it may be copied and furnished 1204 to others, and derivative works that comment on or otherwise 1205 explain it or assist in its implementation may be prepared, 1206 copied, published and distributed, in whole or in part, without 1207 restriction of any kind, provided that the above copyright notice 1208 and this paragraph are included on all such copies and derivative 1209 works. However, this document itself may not be modified in any 1210 way, such as by removing the copyright notice or references to the 1211 Internet Society or other Internet organizations, except as needed 1212 for the purpose of developing Internet standards in which case the 1213 procedures for copyrights defined in the Internet Standards 1214 process must be followed, or as required to translate it into 1215 languages other than English. 1217 The limited permissions granted above are perpetual and will not 1218 be revoked by the Internet Society or its successors or assigns. 1220 This document and the information contained herein is provided on 1221 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET 1222 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 1223 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1224 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1225 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1227 Acknowledgement 1229 Funding for the RFC editor function is currently provided by the 1230 Internet Society.