idnits 2.17.1 draft-ietf-webdav-ordering-protocol-10.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: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == 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 (August 8, 2003) is 7566 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' -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 WEBDAV Working Group J. Whitehead 3 Internet-Draft U.C. Santa Cruz 4 Expires: February 6, 2004 J. Reschke, Ed. 5 greenbytes 6 August 8, 2003 8 WebDAV Ordered Collections Protocol 9 draft-ietf-webdav-ordering-protocol-10 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that other 18 groups may also distribute working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at http:// 26 www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on February 6, 2004. 33 Copyright Notice 35 Copyright (C) The Internet Society (2003). All Rights Reserved. 37 Abstract 39 This specification extends the WebDAV Distributed Authoring Protocol 40 to support server-side ordering of collection members. Of particular 41 interest are orderings that are not based on property values, and so 42 cannot be achieved using a search protocol's ordering option and 43 cannot be maintained automatically by the server. Protocol elements 44 are defined to let clients specify the position in the ordering of 45 each collection member, as well as the semantics governing the 46 ordering. 48 Distribution of this document is unlimited. Please send comments to 49 the Distributed Authoring and Versioning (WebDAV) working group at 50 w3c-dist-auth@w3.org [1], which may be joined by sending a message 51 with subject "subscribe" to w3c-dist-auth-request@w3.org [2]. 53 Discussions of the WEBDAV working group are archived at URL: http:// 54 lists.w3.org/Archives/Public/w3c-dist-auth/. 56 Table of Contents 58 1. Notational Conventions . . . . . . . . . . . . . . . . . . . 4 59 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6 61 4. Overview of Ordered Collections . . . . . . . . . . . . . . 7 62 4.1 Additional Collection properties . . . . . . . . . . . . . . 7 63 4.1.1 DAV:ordering-type (protected) . . . . . . . . . . . . . . . 7 64 5. Creating an Ordered Collection . . . . . . . . . . . . . . . 9 65 5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 5.2 Example: Creating an Ordered Collection . . . . . . . . . . 10 67 6. Setting the Position of a Collection Member . . . . . . . . 11 68 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 6.2 Examples: Setting the Position of a Collection Member . . . 12 70 6.3 Examples: Renaming a member of an ordered collection . . . . 13 71 7. Changing a Collection Ordering: ORDERPATCH method . . . . . 14 72 7.1 Example: Changing a Collection Ordering . . . . . . . . . . 16 73 7.2 Example: Failure of an ORDERPATCH Request . . . . . . . . . 17 74 8. Listing the Members of an Ordered Collection . . . . . . . . 19 75 8.1 Example: PROPFIND on an Ordered Collection . . . . . . . . . 19 76 9. Relationship to versioned collections . . . . . . . . . . . 23 77 9.1 Collection Version Properties . . . . . . . . . . . . . . . 23 78 9.1.1 Additional semantics for 79 DAV:version-controlled-binding-set (protected) . . . . . . . 23 80 9.1.2 DAV:ordering-type (protected) . . . . . . . . . . . . . . . 23 81 9.2 Additional CHECKIN semantics . . . . . . . . . . . . . . . . 23 82 9.3 Additional CHECKOUT Semantics . . . . . . . . . . . . . . . 24 83 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics . . . . . 24 84 10. Capability Discovery . . . . . . . . . . . . . . . . . . . . 25 85 10.1 Example: Using OPTIONS for the Discovery of Support for 86 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . 25 87 10.2 Example: Using Live Properties for the Discovery of 88 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . 26 89 11. Security Considerations . . . . . . . . . . . . . . . . . . 28 90 11.1 Denial of Service and DAV:ordering-type . . . . . . . . . . 28 91 12. Internationalization Considerations . . . . . . . . . . . . 29 92 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . 30 93 14. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 31 94 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 32 95 Normative References . . . . . . . . . . . . . . . . . . . . 33 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 33 97 A. Extensions to the WebDAV Document Type Definition . . . . . 35 98 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 99 Intellectual Property and Copyright Statements . . . . . . . 38 101 1. Notational Conventions 103 Since this document describes a set of extensions to the WebDAV 104 Distributed Authoring Protocol [RFC2518], itself an extension to the 105 HTTP/1.1 protocol, the augmented BNF used here to describe protocol 106 elements is exactly the same as described in Section 2.1 of HTTP 107 [RFC2616]. Since this augmented BNF uses the basic production rules 108 provided in Section 2.2 of HTTP, these rules apply to this document 109 as well. 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in [RFC2119]. 115 This document uses XML DTD fragments as a purely notational 116 convention. WebDAV request and response bodies can not be validated 117 due to the specific extensibility rules defined in section 23 of 118 [RFC2518] and due to the fact that all XML elements defined by this 119 specification use the XML namespace name "DAV:". In particular: 121 1. element names use the "DAV:" namespace, 123 2. element ordering is irrelevant, 125 3. extension elements (elements not already defined as valid child 126 elements) may be added anywhere, except when explicitly stated 127 otherwise, 129 4. extension attributes (attributes not already defined as valid for 130 this element) may be added anywhere, except when explicitly 131 stated otherwise. 133 2. Introduction 135 This specification builds on the collection infrastructure provided 136 by the WebDAV Distributed Authoring Protocol, adding support for the 137 server-side ordering of collection members. 139 There are many scenarios where it is useful to impose an ordering on 140 a collection at the server, such as expressing a recommended access 141 order, or a revision history order. The members of a collection 142 might represent the pages of a book, which need to be presented in 143 order if they are to make sense. Or an instructor might create a 144 collection of course readings, which she wants to be displayed in the 145 order they are to be read. 147 Orderings may be based on property values, but this is not always the 148 case. The resources in the collection may not have properties that 149 can be used to support the desired ordering. Orderings based on 150 properties can be obtained using a search protocol's ordering option, 151 but orderings not based on properties cannot. These orderings 152 generally need to be maintained by a human user. 154 The ordering protocol defined here focuses on support for such 155 human-maintained orderings. Its protocol elements allow clients to 156 specify the position of each collection member in the collection's 157 ordering, as well as the semantics governing the ordering. The 158 protocol is designed to allow support to be added in the future for 159 orderings that are maintained automatically by the server. 161 The remainder of this document is structured as follows: Section 3 162 defines terminology that will be used throughout the specification. 163 Section 4 provides an overview of ordered collections. Section 5 164 describes how to create an ordered collection, and Section 6 165 discusses how to set a member's position in the ordering of a 166 collection. Section 7 explains how to change a collection ordering. 167 Section 8 discusses listing the members of an ordered collection. 168 Section 9 discusses the impact on version-controlled collections (as 169 defined in [RFC3253]. Section 10 describes capability discovery. 170 Section 11 through Section 13 discuss security, internationalization, 171 and IANA considerations. The remaining sections provide supporting 172 information. 174 3. Terminology 176 The terminology used here follows that in [RFC2518] and [RFC3253]. 177 Definitions of the terms resource, Uniform Resource Identifier (URI), 178 and Uniform Resource Locator (URL) are provided in [RFC2396]. 180 Ordered Collection 182 A collection for which the results from a PROPFIND request are 183 guaranteed to be in the order specified for that collection 185 Unordered Collection 187 A collection for which the client cannot depend on the 188 repeatability of the ordering of results from a PROPFIND request 190 Client-Maintained Ordering 192 An ordering of collection members that is maintained on the server 193 based on client requests specifying the position of each 194 collection member in the ordering 196 Server-Maintained Ordering 198 An ordering of collection members that is maintained automatically 199 by the server, based on a client's choice of ordering semantics 201 Ordering Semantics 203 In general, ordering semantics are the set of structures or 204 meanings applied to the ordering of the member of a specific 205 collection. Within this document, "ordering semantics" refers 206 specifically to the structure specified in the DAV:ordering-type 207 property. See Section 4.1.1 for more information on 208 DAV:ordering-type. 210 This document uses the terms "precondition", "postcondition" and 211 "protected property" as defined in [RFC3253]. Servers MUST report 212 pre-/postcondition failures as described in section 1.6 of this 213 document. 215 4. Overview of Ordered Collections 217 If a collection is unordered, the client cannot depend on the 218 repeatability of the ordering of results from a PROPFIND request. By 219 specifying an ordering for a collection, a client requires the server 220 to follow that ordering whenever it responds to a PROPFIND request on 221 that collection. 223 Server-side orderings may be client-maintained or server-maintained. 224 For client-maintained orderings, a client must specify the ordering 225 position of each of the collection's members, either when the member 226 is added to the collection (using the Position header (Section 6)) or 227 later (using the ORDERPATCH (Section 7) method). For 228 server-maintained orderings, the server automatically positions each 229 of the collection's members according to the ordering semantics. 230 This specification supports only client-maintained orderings, but is 231 designed to allow future extension to server-maintained orderings. 233 A collection that supports ordering is not required to be ordered. 235 If a collection is ordered, each of its internal member URIs MUST be 236 in the ordering exactly once, and the ordering MUST NOT include any 237 URI that is not an internal member of the collection. The server is 238 responsible for enforcing these constraints on orderings. The server 239 MUST remove an internal member URI from the ordering when it is 240 removed from the collection. Removing an internal member MUST NOT 241 affect the ordering of the remaining internal members. The server 242 MUST add an internal member URI to the ordering when it is added to 243 the collection. 245 Only one ordering can be attached to any collection. Multiple 246 orderings of the same resources can be achieved by creating multiple 247 collections referencing those resources, and attaching a different 248 ordering to each collection. 250 An ordering is considered to be part of the state of a collection 251 resource. Consequently, the ordering is the same no matter which URI 252 is used to access the collection and is protected by locks or access 253 control constraints on the collection. 255 4.1 Additional Collection properties 257 A DAV:allprop PROPFIND request SHOULD NOT return any of the 258 properties defined in this document. 260 4.1.1 DAV:ordering-type (protected) 262 Indicates whether the collection is ordered and, if so, uniquely 263 identifies the semantics of the ordering being used. May also point 264 to an explanation of the semantics in human and / or machine-readable 265 form. At a minimum, this allows human users who add members to the 266 collection to understand where to position them in the ordering. 267 This property cannot be set using PROPPATCH. Its value can only be 268 set by including the Ordering-Type header with a MKCOL request or by 269 submitting an ORDERPATCH request. 271 Ordering types are identified by URIs that uniquely identify the 272 semantics of the collection's ordering. The following two URIs are 273 predefined: 275 DAV:custom The value DAV:custom indicates that the collection is 276 ordered, but the semantics governing the ordering are not being 277 advertised. 279 DAV:unordered The value DAV:unordered indicates that the collection 280 is not ordered. That is, the client cannot depend on the 281 repeatability of the ordering of results from a PROPFIND request. 283 An ordering-aware client interacting with an ordering-unaware server 284 (e.g., one that is implemented only according to [RFC2518]) SHOULD 285 assume that if a collection does not have the DAV:ordering-type 286 property, the collection is unordered. 288 290 5. Creating an Ordered Collection 292 5.1 Overview 294 When a collection is created, the client MAY request that it be 295 ordered and specify the semantics of the ordering by using the new 296 Ordering-Type header (defined below) with a MKCOL request. 298 For collections that are ordered, the client SHOULD identify the 299 semantics of the ordering with a URI in the Ordering-Type header, 300 although the client MAY simply set the header value to DAV:custom to 301 indicate that the collection is ordered but the semantics of the 302 ordering are not being advertised. Setting the value to a URI that 303 identifies the ordering semantics provides the information a human 304 user or software package needs to insert new collection members into 305 the ordering intelligently. Although the URI in the Ordering-Type 306 header MAY point to a resource that contains a definition of the 307 semantics of the ordering, clients SHOULD NOT access that resource, 308 in order to avoid overburdening its server. A value of DAV:unordered 309 in the Ordering-Type header indicates that the client wants the 310 collection to be unordered. If the Ordering-Type header is not 311 present, the collection will be unordered. 313 Additional Marshalling: 315 Ordering-Type = "Ordering-Type" ":" absoluteURI 316 ; absoluteURI: see RFC2396, section 3 318 The URI "DAV:unordered" indicates that the collection is not 319 ordered, while "DAV:custom" indicates that the collection is to be 320 ordered, but the semantics of the ordering is not being 321 advertised. Any other URI value indicates that the collection is 322 ordered, and identifies the semantics of the ordering. 324 Additional Preconditions: 326 (DAV:ordered-collections-supported): the server MUST support 327 ordered collections in the part of the URL namespace identified by 328 the request URL. 330 Additional Postconditions: 332 (DAV:ordering-type-set): if the Ordering-Type header was present, 333 the request MUST have created a new collection resource with the 334 DAV:ordering-type being set according to the Ordering-Type request 335 header. The collection MUST be ordered unless the ordering type 336 was "DAV:unordered". 338 5.2 Example: Creating an Ordered Collection 340 >> Request: 342 MKCOL /theNorth/ HTTP/1.1 343 Host: example.org 344 Ordering-Type: http://example.org/orderings/compass.html 346 >> Response: 348 HTTP/1.1 201 Created 350 In this example a new, ordered collection was created. Its 351 DAV:ordering-type property has as its value the URI from the 352 Ordering-Type header, http://example.org/orderings/compass.html. In 353 this case, the URI identifies the semantics governing a 354 client-maintained ordering. As new members are added to the 355 collection, clients or end users can use the semantics to determine 356 where to position the new members in the ordering. 358 6. Setting the Position of a Collection Member 360 6.1 Overview 362 When a new member is added to a collection with a client-maintained 363 ordering (for example, with PUT, COPY, or MKCOL), its position in the 364 ordering can be set with the new Position header. The Position header 365 allows the client to specify that an internal member URI should be 366 first in the collection's ordering, last in the collection's 367 ordering, immediately before some other internal member URI in the 368 collection's ordering, or immediately after some other internal 369 member URI in the collection's ordering. 371 If the Position request header is not used when adding a member to an 372 ordered collection, then: 374 o If the request is replacing an existing resource, the server MUST 375 preserve the present ordering. 377 o If the request is adding a new internal member URI to the 378 collection, the server MUST append the new member to the end of 379 the ordering. 381 Note to implementors: this specification does not mandate a 382 specific implementation of MOVE operations within the same parent 383 collection. Therefore, servers may either implement this as a 384 simple rename operation (preserving the collection member's 385 position), or as a sequence of "remove" and "add" (causing the 386 semantics of "adding a new member" to apply). Future revisions of 387 this specification may specify this behaviour more precisely based 388 on future implementation experience. 390 Additional Marshalling: 392 Position = "Position" ":" ("first" | "last" | 393 (("before" | "after") segment)) 395 segment is defined in Section 3.3 of [RFC2396]. 397 The segment is interpreted relative to the collection to which the 398 new member is being added. 400 When the Position header is present, the server MUST insert the 401 new member into the ordering at the specified location. 403 The "first" keyword indicates the new member is put in the 404 beginning position in the collection's ordering, while "last" 405 indicates the new member is put in the final position in the 406 collection's ordering. The "before" keyword indicates the new 407 member is added to the collection's ordering immediately prior to 408 the position of the member identified in the segment. Likewise, 409 the "after" keyword indicates the new member is added to the 410 collection's ordering immediately following the position of the 411 member identified in the segment. 413 If the request is replacing an existing resource, and the Position 414 header is present, the server MUST remove the internal member URI 415 from its previous position, and then insert it at the requested 416 position. 418 Additional Preconditions: 420 (DAV:collection-must-be-ordered): the target collection MUST be 421 ordered. 423 (DAV:segment-must-identify-member): the referenced segment MUST 424 identify a resource that exists and is different from the affected 425 resource. 427 Additional Postconditions: 429 (DAV:position-set): if a Position header was present, the request 430 MUST have created the new collection member at the specified 431 position. 433 6.2 Examples: Setting the Position of a Collection Member 435 >> Request: 437 COPY /~user/dav/spec08.html HTTP/1.1 438 Host: example.org 439 Destination: http://example.org/~slein/dav/spec08.html 440 Position: after requirements.html 442 >> Response: 444 HTTP/1.1 201 Created 446 This request resulted in the creation of a new resource at 447 example.org/~slein/dav/spec08.html. The Position header in this 448 example caused the server to set its position in the ordering of the 449 /~slein/dav/ collection immediately after requirements.html. 451 >> Request: 453 MOVE /i-d/draft-webdav-prot-08.txt HTTP/1.1 454 Host: example.org 455 Destination: http://example.org/~user/dav/draft-webdav-prot-08.txt 456 Position: first 458 >> Response: 460 HTTP/1.1 409 Conflict 461 Content-Type: text/xml; charset="utf-8" 462 Content-Length: xxxx 464 465 466 467 469 In this case, the server returned a 409 (Conflict) status code 470 because the /~user/dav/ collection is an unordered collection. 471 Consequently, the server was unable to satisfy the Position header. 473 6.3 Examples: Renaming a member of an ordered collection 475 The following sequence of requests will rename a collection member 476 while preserving it's position, independantly of how the server 477 implements the MOVE operation: 479 1. PROPFIND collection with depth 1, retrieving the 480 DAV:ordering-type property (an interactive client likely already 481 has done this in order to display the collection's content) 483 2. If the DAV:ordering-type property is present and doesn't equal 484 "dav:unordered" (thus if the collection is ordered), determine 485 current position (such as "first" or "after x") and setup 486 Position header accordingly. 488 3. Perform the MOVE operation, optionally supplying the Position 489 header computed in the previous step. 491 7. Changing a Collection Ordering: ORDERPATCH method 493 The ORDERPATCH method is used to change the ordering semantics of a 494 collection or to change the order of the collection's members in the 495 ordering or both. 497 The server MUST apply the changes in the order they appear in the 498 order XML element. The server MUST either apply all the changes or 499 apply none of them. If any error occurs during processing, all 500 executed changes MUST be undone and a proper error result returned. 502 If an ORDERPATCH request changes the ordering semantics, but does not 503 completely specify the order of the collection members, the server 504 MUST assign a position in the ordering to each collection member for 505 which a position was not specified. These server-assigned positions 506 MUST all follow the last one specified by the client. The result is 507 that all members for which the client specified a position are at the 508 beginning of the ordering, followed by any members for which the 509 server assigned positions. Note that the ordering of the 510 server-assigned positions is not defined by this document, therefore 511 servers can use whatever rule seems reasonable (for instance, 512 alphabetically or by creation date). 514 If an ORDERPATCH request does not change the ordering semantics, any 515 member positions not specified in the request MUST remain unchanged. 517 A request to reposition a collection member at the same place in the 518 ordering is not an error. 520 If an ORDERPATCH request fails, the server state preceding the 521 request MUST be restored. 523 Additional Marshalling: 525 The request body MUST be DAV:orderpatch element. 527 529 530 531 532 533 534 535 536 PCDATA value: segment, as defined in section 3.3 of [RFC2396]. 538 The DAV:ordering-type property is modified according to the 539 DAV:ordering-type element. 541 The ordering of internal member URIs in the collection identified 542 by the Request-URI is changed based on instructions in the 543 order-member XML elements in the order they appear in the request. 544 The order-member XML elements identify the internal member URIs 545 whose positions are to be changed, and describe their new 546 positions in the ordering. Each new position can be specified as 547 first in the ordering, last in the ordering, immediately before 548 some other internal member URI, or immediately after some other 549 internal member URI. 551 If a response body for a successful request is included, it MUST 552 be a DAV:orderpatch-response XML element. Note that this document 553 does not define any elements for the ORDERPATCH response body, but 554 the DAV:orderpatch-response element is defined to ensure 555 interoperability between future extensions that do define elements 556 for the ORDERPATCH response body. 558 560 Since multiple changes can be requested in a single ORDERPATCH 561 request, if any problems are encountered, the server MUST return a 562 207 (Multi-Status) response (defined in [RFC2518]), containing 563 DAV:response elements for either the request-URI (when the 564 DAV:ordering-type could not be modified) or URIs of collection 565 members to be repositioned (when an individual positioning request 566 expressed as DAV:order-member could not be fulfilled). 568 Preconditions: 570 (DAV:collection-must-be-ordered): see Section 6.1. 572 (DAV:segment-must-identify-member): see Section 6.1. 574 Postconditions: 576 (DAV:ordering-type-set): if the request body contained a 577 DAV:ordering-type element, the request MUST have set the 578 DAV:ordering-type property of the collection to the value 579 specified in the request. 581 (DAV:ordering-modified): if the request body contained 582 DAV:order-member elements, the request MUST have set the ordering 583 of internal member URIs in the collection identified by the 584 request-URI based on the instructions in the DAV:order-member 585 elements. 587 7.1 Example: Changing a Collection Ordering 589 Consider an ordered collection /coll-1, with bindings ordered as 590 follows: 592 three.html 593 four.html 594 one.html 595 two.html 597 >> Request: 599 ORDERPATCH /coll-1/ HTTP/1.1 600 Host: example.org 601 Content-Type: text/xml; charset="utf-8" 602 Content-Length: xxx 604 605 606 607 http://example.org/inorder.ord 608 609 610 two.html 611 612 613 614 one.html 615 616 617 618 three.html 619 620 621 622 four.html 623 624 625 627 >> Response: 629 HTTP/1.1 200 OK 630 In this example, after the request has been processed, the 631 collection's ordering semantics are identified by the URI http:// 632 example.org/inorder.ord. The value of the collection's 633 DAV:ordering-type property has been set to this URI. The request also 634 contains instructions for changing the positions of the collection's 635 internal member URIs in the ordering to comply with the new ordering 636 semantics. As the DAV:order-member elements are required to be 637 processed in the order they appear in the request, two.html is moved 638 to the beginning of the ordering, and then one.html is moved to the 639 beginning of the ordering. Then three.html is moved to the end of 640 the ordering, and finally four.html is moved to the end of the 641 ordering. After the request has been processed, the collection's 642 ordering is as follows: 644 one.html 645 two.html 646 three.html 647 four.html 649 7.2 Example: Failure of an ORDERPATCH Request 651 Consider a collection /coll-1/ with members ordered as follows: 653 nunavut.map 654 nunavut.img 655 baffin.map 656 baffin.desc 657 baffin.img 658 iqaluit.map 659 nunavut.desc 660 iqaluit.img 661 iqaluit.desc 663 >> Request: 665 ORDERPATCH /coll-1/ HTTP/1.1 666 Host: www.nunanet.com 667 Content-Type: text/xml; charset="utf-8" 668 Content-Length: xxx 670 671 672 673 nunavut.desc 674 675 676 nunavut.map 678 679 680 681 682 iqaluit.map 683 684 685 pangnirtung.img 686 687 688 689 691 >> Response: 693 HTTP/1.1 207 Multi-Status 694 Content-Type: text/xml; charset="utf-8" 695 Content-Length: xxx 697 698 699 700 http://www.nunanet.com/coll-1/iqaluit.map 701 HTTP/1.1 403 Forbidden 702 703 704 pangnirtung.img is not a collection member. 705 706 707 709 In this example, the client attempted to position iqaluit.map after a 710 URI that is not an internal member of the collection /coll-1/. The 711 server responded to this client error with a 403 (Forbidden) status 712 code, indicating the failed precondition 713 DAV:segment-must-identify-member. Because ORDERPATCH is an atomic 714 method, the request to reposition nunavut.desc (which would otherwise 715 have succeeded) failed as well, but doesn't need to be expressed in 716 the multistatus response body. 718 8. Listing the Members of an Ordered Collection 720 A PROPFIND request is used to retrieve a listing of the members of an 721 ordered collection, just as it is used to retrieve a listing of the 722 members of an unordered collection. 724 However, when responding to a PROPFIND on an ordered collection, the 725 server MUST order the response elements according to the ordering 726 defined on the collection. If a collection is unordered, the client 727 cannot depend on the repeatability of the ordering of results from a 728 PROPFIND request. 730 In a response to a PROPFIND with Depth: infinity, members of 731 different collections may be interleaved. That is, the server is not 732 required to do a breadth-first traversal. The only requirement is 733 that the members of any ordered collection appear in the order 734 defined for the collection. Thus for the hierarchy illustrated in 735 the following figure, where collection A is an ordered collection 736 with the ordering B C D, 738 A 739 /|\ 740 / | \ 741 B C D 742 / /|\ 743 E F G H 745 it would be acceptable for the server to return response elements in 746 the order A B E C F G H D or "A B E C H G F D" as well (if C is 747 unordered).. In this response, B, C, and D appear in the correct 748 order, separated by members of other collections. Clients can use a 749 series of Depth: 1 PROPFIND requests to avoid the complexity of 750 processing Depth: infinity responses based on depth-first traversals. 752 8.1 Example: PROPFIND on an Ordered Collection 754 Suppose a PROPFIND request is submitted to /MyColl/, which has its 755 members ordered as follows. 757 /MyColl/ 758 lakehazen.html 759 siorapaluk.html 760 iqaluit.html 761 newyork.html 763 >> Request: 765 PROPFIND /MyColl/ HTTP/1.1 766 Host: example.org 767 Depth: 1 768 Content-Type: text/xml; charset="utf-8" 769 Content-Length: xxxx 771 772 773 774 775 776 777 778 780 >> Response: 782 HTTP/1.1 207 Multi-Status 783 Content-Type: text/xml; charset="utf-8" 784 Content-Length: xxxx 786 787 789 790 http://example.org/MyColl/ 791 792 793 794 DAV:custom 795 796 797 798 HTTP/1.1 200 OK 799 800 801 802 803 804 HTTP/1.1 404 Not Found 805 806 807 808 http://example.org/MyColl/lakehazen.html 809 810 811 812 82N 813 814 HTTP/1.1 200 OK 815 816 817 818 819 820 HTTP/1.1 404 Not Found 821 822 823 824 http://example.org/MyColl/siorapaluk.html 826 827 828 829 78N 830 831 HTTP/1.1 200 OK 832 833 834 835 836 837 HTTP/1.1 404 Not Found 838 839 840 841 http://example.org/MyColl/iqaluit.html 842 843 844 845 62N 846 847 HTTP/1.1 200 OK 848 849 850 851 852 853 HTTP/1.1 404 Not Found 854 855 856 857 http://example.org/MyColl/newyork.html 858 859 860 861 45N 863 864 HTTP/1.1 200 OK 865 866 867 868 869 HTTP/1.1 404 Not Found 870 871 872 873 875 In this example, the server responded with a list of the collection 876 members in the order defined for the collection. 878 9. Relationship to versioned collections 880 The Versioning Extensions to WebDAV [RFC3253] introduce the concept 881 of versioned collections, recording both the dead properties and the 882 set of internal version-controlled bindings. This section defines how 883 this feature interacts with ordered collections. 885 This specification considers both the ordering type 886 (DAV:ordering-type property) and the ordering of collection members 887 to be part of the state of a collection. Therefore both MUST be 888 recorded upon CHECKIN or VERSION-CONTROL, and both MUST be restored 889 upon CHECKOUT, UNCHECKOUT or UPDATE (where for compatibility with 890 RFC3253, only the ordering of version-controlled members needs to be 891 maintained). 893 9.1 Collection Version Properties 895 9.1.1 Additional semantics for DAV:version-controlled-binding-set 896 (protected) 898 For ordered collections, the DAV:version-controlled-binding elements 899 MUST appear in the ordering defined for the checked-in ordered 900 collection. 902 9.1.2 DAV:ordering-type (protected) 904 The DAV:ordering-type property records the DAV:ordering-type property 905 of the checked-in ordered collection. 907 9.2 Additional CHECKIN semantics 909 Additional Postconditions: 911 (DAV:initialize-version-controlled-bindings-ordered): If the 912 request-URL identified a both ordered and version-controlled 913 collection, then the child elements of 914 DAV:version-controlled-binding-set of the new collection version 915 MUST appear in the ordering defined for that collection. 917 (DAV:initialize-collection-version-ordering-type): If the 918 request-URL identified a both ordered and version-controlled 919 collection, then the DAV:ordering-type property of the new 920 collection version MUST be a copy of the collection's 921 DAV:ordering-type property. 923 9.3 Additional CHECKOUT Semantics 925 Additional Postconditions: 927 (DAV:initialize-version-history-bindings-ordered): If the request 928 has been applied to a collection version with a DAV:ordering-type 929 other than "DAV:unordered", the bindings in the new working 930 collection MUST be ordered according to the collection version's 931 DAV:version-controlled-binding-set property. 933 (DAV:initialize-ordering-type): If the request has been applied to 934 a collection version, the DAV:ordering-type property of the new 935 working collection MUST be initialized from the collection 936 version's DAV:ordering-type property. 938 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics 940 Additional Postconditions: 942 (DAV:update-version-controlled-collection-members-ordered): If the 943 request modified the DAV:checked-in version of a 944 version-controlled collection and the DAV:ordering-type for the 945 checked-in version is not unordered ("DAV:unordered"), the 946 version-controlled members MUST be ordered according to the 947 checked-in version's DAV:version-controlled-binding-set property. 948 The ordering of non-version-controlled members is server-defined. 950 (DAV:update-version-ordering-type): If the request modified the 951 DAV:checked-in version of a version-controlled collection, the 952 DAV:ordering-type property MUST be updated from the checked-in 953 version's property. 955 10. Capability Discovery 957 Sections 9.1 and 15 of [RFC2518] describe the use of compliance 958 classes with the DAV header in responses to OPTIONS, to indicate 959 which parts of the Web Distributed Authoring protocols the resource 960 supports. This specification defines an OPTIONAL extension to 961 [RFC2518]. It defines a new compliance class, called 962 ordered-collections, for use with the DAV header in responses to 963 OPTIONS requests. If a collection resource does support ordering, 964 its response to an OPTIONS request may indicate that it does, by 965 listing the new ORDERPATCH method as one it supports, and by listing 966 the new ordered-collections compliance class in the DAV header. 968 When responding to an OPTIONS request, only a collection or a null 969 resource can include ordered-collections in the value of the DAV 970 header. By including ordered-collections, the resource indicates 971 that its internal member URIs can be ordered. It implies nothing 972 about whether any collections identified by its internal member URIs 973 can be ordered. 975 Furthermore, RFC 3253 [RFC3253] introduces the live properties 976 DAV:supported-method-set (section 3.1.3) and 977 DAV:supported-live-property-set (section 3.1.4). Servers MUST support 978 these properties as defined in RFC 3253. 980 10.1 Example: Using OPTIONS for the Discovery of Support for Ordering 982 >> Request: 984 OPTIONS /somecollection/ HTTP/1.1 985 Host: example.org 987 >> Response: 989 HTTP/1.1 200 OK 990 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE 991 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 992 DAV: 1, 2, ordered-collections 994 The DAV header in the response indicates that the resource / 995 somecollection/ is level 1 and level 2 compliant, as defined in 996 [RFC2518]. In addition, /somecollection/ supports ordering. The 997 Allow header indicates that ORDERPATCH requests can be submitted to / 998 somecollection/. 1000 10.2 Example: Using Live Properties for the Discovery of Ordering 1002 >> Request: 1003 PROPFIND /somecollection HTTP/1.1 1004 Depth: 0 1005 Content-Type: text/xml; charset="utf-8" 1006 Content-Length: xxx 1008 1009 1010 1011 1012 1013 1014 1016 >> Response: 1017 HTTP/1.1 207 Multi-Status 1018 Content-Type: text/xml; charset="utf-8" 1019 Content-Length: xxx 1021 1022 1023 1024 http://example.org/somecollection 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 HTTP/1.1 200 OK 1052 1053 1054 1056 Note that actual responses MUST contain a complete list of supported 1057 live properties. 1059 11. Security Considerations 1061 This section is provided to make WebDAV applications aware of the 1062 security implications of this protocol. 1064 All of the security considerations of HTTP/1.1 and the WebDAV 1065 Distributed Authoring Protocol specification also apply to this 1066 protocol specification. In addition, ordered collections introduce a 1067 new security concern. This issue is detailed here. 1069 11.1 Denial of Service and DAV:ordering-type 1071 There may be some risk of denial of service at sites that are 1072 advertised in the DAV:ordering-type property of collections. 1073 However, it is anticipated that widely-deployed applications will use 1074 hard-coded values for frequently-used ordering semantics rather than 1075 looking up the semantics at the location specified by 1076 DAV:ordering-type. This risk will be further reduced if clients 1077 observe the recommendation of Section 5.1 that they not send requests 1078 to the URI in DAV:ordering-type. 1080 12. Internationalization Considerations 1082 This specification follows the practices of [RFC2518] in encoding all 1083 human-readable content using [XML] and in the treatment of names. 1084 Consequently, this specification complies with the IETF Character Set 1085 Policy [RFC2277]. 1087 WebDAV applications MUST support the character set tagging, character 1088 set encoding, and the language tagging functionality of the XML 1089 specification. This constraint ensures that the human-readable 1090 content of this specification complies with [RFC2277]. 1092 As in [RFC2518], names in this specification fall into three 1093 categories: names of protocol elements such as methods and headers, 1094 names of XML elements, and names of properties. Naming of protocol 1095 elements follows the precedent of HTTP, using English names encoded 1096 in USASCII for methods and headers. The names of XML elements used 1097 in this specification are English names encoded in UTF-8. 1099 For error reporting, [RFC2518] follows the convention of HTTP/1.1 1100 status codes, including with each status code a short, English 1101 description of the code (e.g., 423 Locked). Internationalized 1102 applications will ignore this message, and display an appropriate 1103 message in the user's language and character set. 1105 This specification introduces no new strings that are displayed to 1106 users as part of normal, error-free operation of the protocol. 1108 For rationales for these decisions and advice for application 1109 implementors, see [RFC2518]. 1111 13. IANA Considerations 1113 This document uses the namespaces defined by [RFC2518] for properties 1114 and XML elements. All other IANA considerations mentioned in 1115 [RFC2518] also apply to this document. 1117 14. Contributors 1119 This document has benefited from significant contributions from Geoff 1120 Clemm, Jason Crawford, Jim Davis, Chuck Fay and Judith Slein. 1122 15. Acknowledgements 1124 This document has benefited from thoughtful discussion by Jim Amsden, 1125 Steve Carter, Tyson Chihaya, Ken Coar, Ellis Cohen, Bruce Cragun, 1126 Spencer Dawkins, Mark Day, Rajiv Dulepet, David Durand, Lisa 1127 Dusseault, Roy Fielding, Yaron Goland, Fred Hitt, Alex Hopmann, 1128 Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, Daniel 1129 LaLiberte, Steve Martin, Larry Masinter, Jeff McAffer, Surendra 1130 Koduru Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness, 1131 John Stracke, John Tigue, John Turner, Kevin Wiggen, and others. 1133 Normative References 1135 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1136 Requirement Levels", BCP 14, RFC 2119, March 1997. 1138 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 1139 Languages", BCP 18, RFC 2277, January 1998. 1141 [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 1142 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1143 August 1998. 1145 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. 1146 Jensen, "HTTP Extensions for Distributed Authoring -- 1147 WEBDAV", RFC 2518, February 1999. 1149 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1150 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext 1151 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1153 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and J. 1154 Whitehead, "Versioning Extensions to WebDAV", RFC 3253, 1155 March 2002. 1157 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, 1158 "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C 1159 REC-xml, October 2000, . 1162 [1] 1164 [2] 1166 Authors' Addresses 1168 Jim Whitehead 1169 UC Santa Cruz, Dept. of Computer Science 1170 1156 High Street 1171 Santa Cruz, CA 95064 1172 US 1174 EMail: ejw@cse.ucsc.edu 1175 Julian F. Reschke (editor) 1176 greenbytes GmbH 1177 Salzmannstrasse 152 1178 Muenster, NW 48159 1179 Germany 1181 Phone: +49 251 2807760 1182 Fax: +49 251 2807761 1183 EMail: julian.reschke@greenbytes.de 1184 URI: http://greenbytes.de/tech/webdav/ 1186 Appendix A. Extensions to the WebDAV Document Type Definition 1188 1189 1190 1191 1192 1193 1194 1195 1196 1198 Index 1200 C 1201 Client-Maintained Ordering 6 1203 D 1204 DAV:collection-must-be-ordered precondition 12 1205 DAV:custom ordering type 8 1206 DAV:initialize-collection-version-ordering-type 23 1207 DAV:initialize-ordering-type 24 1208 DAV:initialize-version-controlled-bindings-ordered postcondition 23 1209 DAV:initialize-version-history-bindings-ordered 24 1210 DAV:ordered-collections-supported precondition 9 1211 DAV:ordering-modified postcondition 15 1212 DAV:ordering-type property 7 1213 DAV:ordering-type-set postcondition 9, 15 1214 DAV:position-set postcondition 12 1215 DAV:segment-must-identify-member precondition 12 1216 DAV:unordered ordering type 8 1217 DAV:update-version-controlled-collection-members-ordered 24 1218 DAV:update-version-ordering-type 24 1220 H 1221 Headers 1222 Ordering-Type 9 1224 O 1225 Ordered Collection 6 1226 Ordering Semantics 6 1227 Ordering-Type header 9 1228 ORDERPATCH method 14 1230 P 1231 Postconditions 1232 DAV:initialize-collection-version-ordering-type 23 1233 DAV:initialize-ordering-type 24 1234 DAV:initialize-version-controlled-bindings-ordered 23 1235 DAV:initialize-version-history-bindings-ordered 24 1236 DAV:ordering-modified 15 1237 DAV:ordering-type-set 9, 15 1238 DAV:position-set 12 1239 DAV:update-version-controlled-collection-members-ordered 24 1240 DAV:update-version-ordering-type 24 1241 Preconditions 1242 DAV:collection-must-be-ordered 12 1243 DAV:ordered-collections-supported 9 1244 DAV:segment-must-identify-member 12 1245 Protected properties 1246 DAV:ordering-type 7 1248 S 1249 Server-Maintained Ordering 6 1251 U 1252 Unordered Collection 6 1254 Intellectual Property Statement 1256 The IETF takes no position regarding the validity or scope of any 1257 intellectual property or other rights that might be claimed to 1258 pertain to the implementation or use of the technology described in 1259 this document or the extent to which any license under such rights 1260 might or might not be available; neither does it represent that it 1261 has made any effort to identify any such rights. Information on the 1262 IETF's procedures with respect to rights in standards-track and 1263 standards-related documentation can be found in BCP-11. Copies of 1264 claims of rights made available for publication and any assurances of 1265 licenses to be made available, or the result of an attempt made to 1266 obtain a general license or permission for the use of such 1267 proprietary rights by implementors or users of this specification can 1268 be obtained from the IETF Secretariat. 1270 The IETF invites any interested party to bring to its attention any 1271 copyrights, patents or patent applications, or other proprietary 1272 rights which may cover technology that may be required to practice 1273 this standard. Please address the information to the IETF Executive 1274 Director. 1276 Full Copyright Statement 1278 Copyright (C) The Internet Society (2003). All Rights Reserved. 1280 This document and translations of it may be copied and furnished to 1281 others, and derivative works that comment on or otherwise explain it 1282 or assist in its implementation may be prepared, copied, published 1283 and distributed, in whole or in part, without restriction of any 1284 kind, provided that the above copyright notice and this paragraph are 1285 included on all such copies and derivative works. However, this 1286 document itself may not be modified in any way, such as by removing 1287 the copyright notice or references to the Internet Society or other 1288 Internet organizations, except as needed for the purpose of 1289 developing Internet standards in which case the procedures for 1290 copyrights defined in the Internet Standards process must be 1291 followed, or as required to translate it into languages other than 1292 English. 1294 The limited permissions granted above are perpetual and will not be 1295 revoked by the Internet Society or its successors or assignees. 1297 This document and the information contained herein is provided on an 1298 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1299 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1300 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1301 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1302 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1304 Acknowledgment 1306 Funding for the RFC Editor function is currently provided by the 1307 Internet Society.