idnits 2.17.1 draft-ietf-webdav-ordering-protocol-08.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 (May 12, 2003) is 7649 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: November 10, 2003 J. Reschke, Ed. 5 greenbytes 6 May 12, 2003 8 WebDAV Ordered Collections Protocol 9 draft-ietf-webdav-ordering-protocol-08 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 November 10, 2003. 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 7. Changing a Collection Ordering: ORDERPATCH method . . . . . 14 71 7.1 Example: Changing a Collection Ordering . . . . . . . . . . 16 72 7.2 Example: Failure of an ORDERPATCH Request . . . . . . . . . 17 73 8. Listing the Members of an Ordered Collection . . . . . . . . 19 74 8.1 Example: PROPFIND on an Ordered Collection . . . . . . . . . 19 75 9. Relationship to versioned collections . . . . . . . . . . . 23 76 9.1 Collection Version Properties . . . . . . . . . . . . . . . 23 77 9.1.1 Additional semantics for 78 DAV:version-controlled-binding-set (protected) . . . . . . . 23 79 9.1.2 DAV:ordering-type (protected) . . . . . . . . . . . . . . . 23 80 9.2 Additional CHECKIN semantics . . . . . . . . . . . . . . . . 23 81 9.3 Additional CHECKOUT Semantics . . . . . . . . . . . . . . . 24 82 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics . . . . . 24 83 10. Capability Discovery . . . . . . . . . . . . . . . . . . . . 25 84 10.1 Example: Using OPTIONS for the Discovery of Support for 85 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . 25 86 10.2 Example: Using Live Properties for the Discovery of 87 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . 26 88 11. Security Considerations . . . . . . . . . . . . . . . . . . 28 89 11.1 Denial of Service and DAV:ordering-type . . . . . . . . . . 28 90 12. Internationalization Considerations . . . . . . . . . . . . 29 91 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . 30 92 14. Copyright . . . . . . . . . . . . . . . . . . . . . . . . . 31 93 15. Intellectual Property . . . . . . . . . . . . . . . . . . . 32 94 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 33 95 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 34 96 Normative References . . . . . . . . . . . . . . . . . . . . 35 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 35 99 A. Extensions to the WebDAV Document Type Definition . . . . . 37 100 B. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 38 101 B.1 Since draft-ietf-webdav-ordering-protocol dated December 102 1999 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 103 B.2 Since draft-ietf-webdav-ordering-protocol-02 . . . . . . . . 38 104 B.3 Since draft-ietf-webdav-ordering-protocol-03 . . . . . . . . 38 105 B.4 Since draft-ietf-webdav-ordering-protocol-04 . . . . . . . . 38 106 B.5 Since draft-ietf-webdav-ordering-protocol-05 . . . . . . . . 39 107 B.6 Since draft-ietf-webdav-ordering-protocol-06 . . . . . . . . 39 108 B.7 Since draft-ietf-webdav-ordering-protocol-07 . . . . . . . . 39 109 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 110 Intellectual Property and Copyright Statements . . . . . . . 42 112 1. Notational Conventions 114 Since this document describes a set of extensions to the WebDAV 115 Distributed Authoring Protocol [RFC2518], itself an extension to the 116 HTTP/1.1 protocol, the augmented BNF used here to describe protocol 117 elements is exactly the same as described in Section 2.1 of HTTP 118 [RFC2616]. Since this augmented BNF uses the basic production rules 119 provided in Section 2.2 of HTTP, these rules apply to this document 120 as well. 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 This document uses XML DTD fragments as a purely notational 127 convention. WebDAV request and response bodies can not be validated 128 due to the specific extensibility rules defined in section 23 of 129 [RFC2518] and due to the fact that all XML elements defined by this 130 specification use the XML namespace name "DAV:". In particular: 132 1. element names use the "DAV:" namespace, 134 2. element ordering is irrelevant, 136 3. extension elements (elements not already defined as valid child 137 elements) may be added anywhere, except when explicitly stated 138 otherwise, 140 4. extension attributes (attributes not already defined as valid for 141 this element) may be added anywhere, except when explicitly 142 stated otherwise. 144 2. Introduction 146 This specification builds on the collection infrastructure provided 147 by the WebDAV Distributed Authoring Protocol, adding support for the 148 server-side ordering of collection members. 150 There are many scenarios where it is useful to impose an ordering on 151 a collection at the server, such as expressing a recommended access 152 order, or a revision history order. The members of a collection 153 might represent the pages of a book, which need to be presented in 154 order if they are to make sense. Or an instructor might create a 155 collection of course readings, which she wants to be displayed in the 156 order they are to be read. 158 Orderings may be based on property values, but this is not always the 159 case. The resources in the collection may not have properties that 160 can be used to support the desired ordering. Orderings based on 161 properties can be obtained using a search protocol's ordering option, 162 but orderings not based on properties cannot. These orderings 163 generally need to be maintained by a human user. 165 The ordering protocol defined here focuses on support for such 166 human-maintained orderings. Its protocol elements allow clients to 167 specify the position of each collection member in the collection's 168 ordering, as well as the semantics governing the ordering. The 169 protocol is designed to allow support to be added in the future for 170 orderings that are maintained automatically by the server. 172 The remainder of this document is structured as follows: Section 3 173 defines terminology that will be used throughout the specification. 174 Section 4 provides an overview of ordered collections. Section 5 175 describes how to create an ordered collection, and Section 6 176 discusses how to set a member's position in the ordering of a 177 collection. Section 7 explains how to change a collection ordering. 178 Section 8 discusses listing the members of an ordered collection. 179 Section 9 discusses the impact on version-controlled collections (as 180 defined in [RFC3253]. Section 10 describes capability discovery. 181 Section 11 through Section 13 discuss security, internationalization, 182 and IANA considerations. The remaining sections provide supporting 183 information. 185 3. Terminology 187 The terminology used here follows that in [RFC2518] and [RFC3253]. 188 Definitions of the terms resource, Uniform Resource Identifier (URI), 189 and Uniform Resource Locator (URL) are provided in [RFC2396]. 191 Ordered Collection 193 A collection for which the results from a PROPFIND request are 194 guaranteed to be in the order specified for that collection 196 Unordered Collection 198 A collection for which the client cannot depend on the 199 repeatability of the ordering of results from a PROPFIND request 201 Client-Maintained Ordering 203 An ordering of collection members that is maintained on the server 204 based on client requests specifying the position of each 205 collection member in the ordering 207 Server-Maintained Ordering 209 An ordering of collection members that is maintained automatically 210 by the server, based on a client's choice of ordering semantics 212 This document uses the terms "precondition", "postcondition" and 213 "protected property" as defined in [RFC3253]. Servers MUST report 214 pre-/postcondition failures as described in section 1.6 of this 215 document. 217 4. Overview of Ordered Collections 219 If a collection is unordered, the client cannot depend on the 220 repeatability of the ordering of results from a PROPFIND request. By 221 specifying an ordering for a collection, a client requires the server 222 to follow that ordering whenever it responds to a PROPFIND request on 223 that collection. 225 Server-side orderings may be client-maintained or server-maintained. 226 For client-maintained orderings, a client must specify the ordering 227 position of each of the collection's members, either when the member 228 is added to the collection (using the Position header (Section 6)) or 229 later (using the ORDERPATCH (Section 7) method). For 230 server-maintained orderings, the server automatically positions each 231 of the collection's members according to the ordering semantics. 232 This specification supports only client-maintained orderings, but is 233 designed to allow future extension to server-maintained orderings. 235 A collection that supports ordering is not required to be ordered. 237 If a collection is ordered, each of its internal member URIs MUST be 238 in the ordering exactly once, and the ordering MUST NOT include any 239 URI that is not an internal member of the collection. The server is 240 responsible for enforcing these constraints on orderings. The server 241 MUST remove an internal member URI from the ordering when it is 242 removed from the collection. Removing an internal member MUST NOT 243 affect the ordering of the remaining internal members. The server 244 MUST add an internal member URI to the ordering when it is added to 245 the collection. 247 Only one ordering can be attached to any collection. Multiple 248 orderings of the same resources can be achieved by creating multiple 249 collections referencing those resources, and attaching a different 250 ordering to each collection. 252 An ordering is considered to be part of the state of a collection 253 resource. Consequently, the ordering is the same no matter which URI 254 is used to access the collection and is protected by locks or access 255 control constraints on the collection. 257 4.1 Additional Collection properties 259 A DAV:allprop PROPFIND request SHOULD NOT return any of the 260 properties defined in this document. 262 4.1.1 DAV:ordering-type (protected) 264 Indicates whether the collection is ordered and, if so, uniquely 265 identifies the semantics of the ordering being used. May also point 266 to an explanation of the semantics in human and / or machine-readable 267 form. At a minimum, this allows human users who add members to the 268 collection to understand where to position them in the ordering. 269 This property cannot be set using PROPPATCH. Its value can only be 270 set by including the Ordering-Type header with a MKCOL request or by 271 submitting an ORDERPATCH request. 273 Ordering types are identified by URIs that uniquely identify the 274 semantics of the collection's ordering. The following two URIs are 275 predefined: 277 DAV:custom The value DAV:custom indicates that the collection is 278 ordered, but the semantics governing the ordering are not being 279 advertised. 281 DAV:unordered The value DAV:unordered indicates that the collection 282 is not ordered. That is, the client cannot depend on the 283 repeatability of the ordering of results from a PROPFIND request. 285 An ordering-aware client interacting with an ordering-unaware server 286 (e.g., one that is implemented only according to [RFC2518]) SHOULD 287 assume that if a collection does not have the DAV:ordering-type 288 property, the collection is unordered. 290 292 5. Creating an Ordered Collection 294 5.1 Overview 296 When a collection is created, the client MAY request that it be 297 ordered and specify the semantics of the ordering by using the new 298 Ordering-Type header (defined below) with a MKCOL request. 300 For collections that are ordered, the client SHOULD identify the 301 semantics of the ordering with a URI in the Ordering-Type header, 302 although the client MAY simply set the header value to DAV:custom to 303 indicate that the collection is ordered but the semantics of the 304 ordering are not being advertised. Setting the value to a URI that 305 identifies the ordering semantics provides the information a human 306 user or software package needs to insert new collection members into 307 the ordering intelligently. Although the URI in the Ordering-Type 308 header MAY point to a resource that contains a definition of the 309 semantics of the ordering, clients SHOULD NOT access that resource, 310 in order to avoid overburdening its server. A value of DAV:unordered 311 in the Ordering-Type header indicates that the client wants the 312 collection to be unordered. If the Ordering-Type header is not 313 present, the collection will be unordered. 315 Additional Marshalling: 317 Ordering-Type = "Ordering-Type" ":" absoluteURI 318 ; absoluteURI: see RFC2396, section 3 320 The URI "DAV:unordered" indicates that the collection is not 321 ordered, while "DAV:custom" indicates that the collection is to be 322 ordered, but the semantics of the ordering is not being 323 advertised. Any other URI value indicates that the collection is 324 ordered, and identifies the semantics of the ordering. 326 Additional Preconditions: 328 (DAV:ordered-collections-supported): the server MUST support 329 ordered collections in the part of the URL namespace identified by 330 the request URL. 332 Additional Postconditions: 334 (DAV:ordering-type-set): if the Ordering-Type header was present, 335 the request MUST have created a new collection resource with the 336 DAV:ordering-type being set according to the Ordering-Type request 337 header. The collection MUST be ordered unless the ordering type 338 was "DAV:unordered". 340 5.2 Example: Creating an Ordered Collection 342 >> Request: 344 MKCOL /theNorth/ HTTP/1.1 345 Host: example.org 346 Ordering-Type: http://example.org/orderings/compass.html 348 >> Response: 350 HTTP/1.1 201 Created 352 In this example a new, ordered collection was created. Its 353 DAV:ordering-type property has as its value the URI from the 354 Ordering-Type header, http://example.org/orderings/compass.html. In 355 this case, the URI identifies the semantics governing a 356 client-maintained ordering. As new members are added to the 357 collection, clients or end users can use the semantics to determine 358 where to position the new members in the ordering. 360 6. Setting the Position of a Collection Member 362 6.1 Overview 364 When a new member is added to a collection with a client-maintained 365 ordering (for example, with PUT, COPY, or MKCOL), its position in the 366 ordering can be set with the new Position header. The Position header 367 allows the client to specify that an internal member URI should be 368 first in the collection's ordering, last in the collection's 369 ordering, immediately before some other internal member URI in the 370 collection's ordering, or immediately after some other internal 371 member URI in the collection's ordering. 373 If the Position request header is not used when adding a member to an 374 ordered collection, then: 376 o If the request is replacing an existing resource, the server MUST 377 preserve the present ordering. 379 o If the request is adding a new internal member URI to the 380 collection, the server MUST append the new member to the end of 381 the ordering. 383 Note to implementors: this specification does not mandate a 384 specific implementation of MOVE operations within the same parent 385 collection. Therefore, servers may either implement this as a 386 simple rename operation (preserving the collection member's 387 position), or as a sequence of "remove" and "add" (causing the 388 semantics of "adding a new member" to apply). Future revisions of 389 this specification may specify this behaviour more precisely based 390 on future implementation experience. 392 Additional Marshalling: 394 Position = "Position" ":" ("first" | "last" | 395 (("before" | "after") segment)) 397 segment is defined in Section 3.3 of [RFC2396]. 399 The segment is interpreted relative to the collection to which the 400 new member is being added. 402 When the Position header is present, the server MUST insert the 403 new member into the ordering at the specified location. 405 The "first" keyword indicates the new member is put in the 406 beginning position in the collection's ordering, while "last" 407 indicates the new member is put in the final position in the 408 collection's ordering. The "before" keyword indicates the new 409 member is added to the collection's ordering immediately prior to 410 the position of the member identified in the segment. Likewise, 411 the "after" keyword indicates the new member is added to the 412 collection's ordering immediately following the position of the 413 member identified in the segment. 415 If the request is replacing an existing resource, and the Position 416 header is present, the server MUST remove the internal member URI 417 from its previous position, and then insert it at the requested 418 position. 420 Additional Preconditions: 422 (DAV:collection-must-be-ordered): the target collection MUST be 423 ordered. 425 (DAV:segment-must-identify-member): the referenced segment MUST 426 identify a resource that exists and is different from the affected 427 resource. 429 Additional Postconditions: 431 (DAV:position-set): if a Position header was present, the request 432 MUST have created the new collection member at the specified 433 position. 435 6.2 Examples: Setting the Position of a Collection Member 437 >> Request: 439 COPY /~user/dav/spec08.html HTTP/1.1 440 Host: example.org 441 Destination: http://example.org/~slein/dav/spec08.html 442 Position: after requirements.html 444 >> Response: 446 HTTP/1.1 201 Created 448 This request resulted in the creation of a new resource at 449 example.org/~slein/dav/spec08.html. The Position header in this 450 example caused the server to set its position in the ordering of the 451 /~slein/dav/ collection immediately after requirements.html. 453 >> Request: 455 MOVE /i-d/draft-webdav-prot-08.txt HTTP/1.1 456 Host: example.org 457 Destination: http://example.org/~user/dav/draft-webdav-prot-08.txt 458 Position: first 460 >> Response: 462 HTTP/1.1 409 Conflict 463 Content-Type: text/xml; charset="utf-8" 464 Content-Length: xxxx 466 467 468 469 471 In this case, the server returned a 409 (Conflict) status code 472 because the /~user/dav/ collection is an unordered collection. 473 Consequently, the server was unable to satisfy the Position header. 475 7. Changing a Collection Ordering: ORDERPATCH method 477 The ORDERPATCH method is used to change the ordering semantics of a 478 collection or to change the order of the collection's members in the 479 ordering or both. 481 The server MUST apply the changes in the order they appear in the 482 order XML element. The server MUST either apply all the changes or 483 apply none of them. If any error occurs during processing, all 484 executed changes MUST be undone and a proper error result returned. 486 If an ORDERPATCH request changes the ordering semantics, but does not 487 completely specify the order of the collection members, the server 488 MUST assign a position in the ordering to each collection member for 489 which a position was not specified. These server-assigned positions 490 MUST all follow the last one specified by the client. The result is 491 that all members for which the client specified a position are at the 492 beginning of the ordering, followed by any members for which the 493 server assigned positions. 495 If an ORDERPATCH request does not change the ordering semantics, any 496 member positions not specified in the request MUST remain unchanged. 498 A request to reposition a collection member at the same place in the 499 ordering is not an error. 501 If an ORDERPATCH request fails, the server state preceding the 502 request MUST be restored. 504 Additional Marshalling: 506 The request body MUST be DAV:orderpatch element. 508 510 511 512 513 514 515 516 518 PCDATA value: segment, as defined in section 3.3 of [RFC2396]. 520 The DAV:ordering-type property is modified according to the 521 DAV:ordering-type element. 523 The ordering of internal member URIs in the collection identified 524 by the Request-URI is changed based on instructions in the 525 order-member XML elements in the order they appear in the request. 526 The order-member XML elements identify the internal member URIs 527 whose positions are to be changed, and describe their new 528 positions in the ordering. Each new position can be specified as 529 first in the ordering, last in the ordering, immediately before 530 some other internal member URI, or immediately after some other 531 internal member URI. 533 If a response body for a successful request is included, it MUST 534 be a DAV:orderpatch-response XML element. Note that this document 535 does not define any elements for the ORDERPATCH response body, but 536 the DAV:orderpatch-response element is defined to ensure 537 interoperability between future extensions that do define elements 538 for the ORDERPATCH response body. 540 542 Since multiple changes can be requested in a single ORDERPATCH 543 request, if any problems are encountered, the server MUST return a 544 207 (Multi-Status) response (defined in [RFC2518]), containing 545 DAV:response elements for either the request-URI (when the 546 DAV:ordering-type could not be modified) or URIs of collection 547 members to be repositioned (when an individual positioning request 548 expressed as DAV:order-member could not be fulfilled). 550 Preconditions: 552 (DAV:collection-must-be-ordered): see Section 6.1. 554 (DAV:segment-must-identify-member): see Section 6.1. 556 Postconditions: 558 (DAV:ordering-type-set): if the request body contained a 559 DAV:ordering-type element, the request MUST have set the 560 DAV:ordering-type property of the collection to the value 561 specified in the request. 563 (DAV:ordering-modified): if the request body contained 564 DAV:order-member elements, the request MUST have set the ordering 565 of internal member URIs in the collection identified by the 566 request-URI based on the instructions in the DAV:order-member 567 elements. 569 7.1 Example: Changing a Collection Ordering 571 Consider a collection /coll-1/ whose DAV:ordering-type is DAV:whim, 572 with bindings ordered as follows: 574 three.html 575 four.html 576 one.html 577 two.html 579 >> Request: 581 ORDERPATCH /coll-1/ HTTP/1.1 582 Host: example.org 583 Content-Type: text/xml; charset="utf-8" 584 Content-Length: xxx 586 587 588 589 http://example.org/inorder.ord 590 591 592 two.html 593 594 595 596 one.html 597 598 599 600 three.html 601 602 603 604 four.html 605 606 607 609 >> Response: 611 HTTP/1.1 200 OK 613 In this example, after the request has been processed, the 614 collection's ordering semantics are identified by the URI http:// 615 example.org/inorder.ord. The value of the collection's 616 DAV:ordering-type property has been set to this URI. The request also 617 contains instructions for changing the positions of the collection's 618 internal member URIs in the ordering to comply with the new ordering 619 semantics. As the DAV:order-member elements are required to be 620 processed in the order they appear in the request, two.html is moved 621 to the beginning of the ordering, and then one.html is moved to the 622 beginning of the ordering. Then three.html is moved to the end of 623 the ordering, and finally four.html is moved to the end of the 624 ordering. After the request has been processed, the collection's 625 ordering is as follows: 627 one.html 628 two.html 629 three.html 630 four.html 632 7.2 Example: Failure of an ORDERPATCH Request 634 Consider a collection /coll-1/ with members ordered as follows: 636 nunavut.map 637 nunavut.img 638 baffin.map 639 baffin.desc 640 baffin.img 641 iqaluit.map 642 nunavut.desc 643 iqaluit.img 644 iqaluit.desc 646 >> Request: 648 ORDERPATCH /coll-1/ HTTP/1.1 649 Host: www.nunanet.com 650 Content-Type: text/xml; charset="utf-8" 651 Content-Length: xxx 653 654 655 656 nunavut.desc 657 658 659 nunavut.map 660 661 662 663 664 iqaluit.map 665 666 667 pangnirtung.img 668 669 670 671 673 >> Response: 675 HTTP/1.1 207 Multi-Status 676 Content-Type: text/xml; charset="utf-8" 677 Content-Length: xxx 679 680 681 682 http://www.nunanet.com/coll-1/iqaluit.map 683 HTTP/1.1 403 Forbidden 684 685 686 pangnirtung.img is not a collection member. 687 688 689 691 In this example, the client attempted to position iqaluit.map after a 692 URI that is not an internal member of the collection /coll-1/. The 693 server responded to this client error with a 403 (Forbidden) status 694 code, indicating the failed precondition 695 DAV:segment-must-identify-member. Because ORDERPATCH is an atomic 696 method, the request to reposition nunavut.desc (which would otherwise 697 have succeeded) failed as well, but doesn't need to be expressed in 698 the multistatus response body. 700 8. Listing the Members of an Ordered Collection 702 A PROPFIND request is used to retrieve a listing of the members of an 703 ordered collection, just as it is used to retrieve a listing of the 704 members of an unordered collection. 706 However, when responding to a PROPFIND on an ordered collection, the 707 server MUST order the response elements according to the ordering 708 defined on the collection. If a collection is unordered, the client 709 cannot depend on the repeatability of the ordering of results from a 710 PROPFIND request. 712 In a response to a PROPFIND with Depth: infinity, members of 713 different collections may be interleaved. That is, the server is not 714 required to do a breadth-first traversal. The only requirement is 715 that the members of any ordered collection appear in the order 716 defined for the collection. Thus for the hierarchy illustrated in 717 the following figure, where collection A is an ordered collection 718 with the ordering B C D, 720 A 721 /|\ 722 / | \ 723 B C D 724 / /|\ 725 E F G H 727 it would be acceptable for the server to return response elements in 728 the order A B E C F G H D. In this response, B, C, and D appear in 729 the correct order, separated by members of other collections. 730 Clients can use a series of Depth: 1 PROPFIND requests to avoid the 731 complexity of processing Depth: infinity responses based on 732 depth-first traversals. 734 8.1 Example: PROPFIND on an Ordered Collection 736 Suppose a PROPFIND request is submitted to /MyColl/, which has its 737 members ordered as follows. 739 /MyColl/ 740 lakehazen.html 741 siorapaluk.html 742 iqaluit.html 743 newyork.html 745 >> Request: 747 PROPFIND /MyColl/ HTTP/1.1 748 Host: example.org 749 Depth: 1 750 Content-Type: text/xml; charset="utf-8" 751 Content-Length: xxxx 753 754 755 756 757 758 759 760 762 >> Response: 764 HTTP/1.1 207 Multi-Status 765 Content-Type: text/xml; charset="utf-8" 766 Content-Length: xxxx 768 769 771 772 http://example.org/MyColl/ 773 774 775 776 DAV:custom 777 778 779 780 HTTP/1.1 200 OK 781 782 783 784 785 786 HTTP/1.1 404 Not Found 787 788 789 790 http://example.org/MyColl/lakehazen.html 791 792 793 794 82N 795 796 HTTP/1.1 200 OK 797 798 799 800 801 802 HTTP/1.1 404 Not Found 803 804 805 806 http://example.org/MyColl/siorapaluk.html 808 809 810 811 78N 812 813 HTTP/1.1 200 OK 814 815 816 817 818 819 HTTP/1.1 404 Not Found 820 821 822 823 http://example.org/MyColl/iqaluit.html 824 825 826 827 62N 828 829 HTTP/1.1 200 OK 830 831 832 833 834 835 HTTP/1.1 404 Not Found 836 837 838 839 http://example.org/MyColl/newyork.html 840 841 842 843 45N 845 846 HTTP/1.1 200 OK 847 848 849 850 851 HTTP/1.1 404 Not Found 852 853 854 855 857 In this example, the server responded with a list of the collection 858 members in the order defined for the collection. 860 9. Relationship to versioned collections 862 The Versioning Extensions to WebDAV [RFC3253] introduce the concept 863 of versioned collections, recording both the dead properties and the 864 set of internal version-controlled bindings. This section defines how 865 this feature interacts with ordered collections. 867 This specification considers both the ordering type 868 (DAV:ordering-type property) and the ordering of collection members 869 to be part of the state of a collection. Therefore both MUST be 870 recorded upon CHECKIN or VERSION-CONTROL, and both MUST be restored 871 upon CHECKOUT, UNCHECKOUT or UPDATE (where for compatibility with 872 RFC3253, only the ordering of version-controlled members needs to be 873 maintained). 875 9.1 Collection Version Properties 877 9.1.1 Additional semantics for DAV:version-controlled-binding-set 878 (protected) 880 For ordered collections, the DAV:version-controlled-binding elements 881 MUST appear in the ordering defined for the checked-in ordered 882 collection. 884 9.1.2 DAV:ordering-type (protected) 886 The DAV:ordering-type property records the DAV:ordering-type property 887 of the checked-in ordered collection. 889 9.2 Additional CHECKIN semantics 891 Additional Postconditions: 893 (DAV:initialize-version-controlled-bindings-ordered): If the 894 request-URL identified a both ordered and version-controlled 895 collection, then the child elements of 896 DAV:version-controlled-binding-set of the new collection version 897 MUST appear in the ordering defined for that collection. 899 (DAV:initialize-collection-version-ordering-type): If the 900 request-URL identified a both ordered and version-controlled 901 collection, then the DAV:ordering-type property of the new 902 collection version MUST be a copy of the collection's 903 DAV:ordering-type property. 905 9.3 Additional CHECKOUT Semantics 907 Additional Postconditions: 909 (DAV:initialize-version-history-bindings-ordered): If the request 910 has been applied to a collection version with a DAV:ordering-type 911 other than "DAV:unordered", the bindings in the new working 912 collection MUST be ordered according to the collection version's 913 DAV:version-controlled-binding-set property. 915 (DAV:initialize-ordering-type): If the request has been applied to 916 a collection version, the DAV:ordering-type property of the new 917 working collection MUST be initialized from the collection 918 version's DAV:ordering-type property. 920 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics 922 Additional Postconditions: 924 (DAV:update-version-controlled-collection-members-ordered): If the 925 request modified the DAV:checked-in version of a 926 version-controlled collection and the DAV:ordering-type for the 927 checked-in version is not unordered ("DAV:unordered"), the 928 version-controlled members MUST be ordered according to the 929 checked-in version's DAV:version-controlled-binding-set property. 930 The ordering of non-version-controlled members is server-defined." 932 (DAV:update-version-ordering-type): If the request modified the 933 DAV:checked-in version of a version-controlled collection, the 934 DAV:ordering-type property MUST be updated from the checked-in 935 version's property. 937 10. Capability Discovery 939 Sections 9.1 and 15 of [RFC2518] describe the use of compliance 940 classes with the DAV header in responses to OPTIONS, to indicate 941 which parts of the Web Distributed Authoring protocols the resource 942 supports. This specification defines an OPTIONAL extension to 943 [RFC2518]. It defines a new compliance class, called 944 ordered-collections, for use with the DAV header in responses to 945 OPTIONS requests. If a collection resource does support ordering, 946 its response to an OPTIONS request may indicate that it does, by 947 listing the new ORDERPATCH method as one it supports, and by listing 948 the new ordered-collections compliance class in the DAV header. 950 When responding to an OPTIONS request, only a collection or a null 951 resource can include ordered-collections in the value of the DAV 952 header. By including ordered-collections, the resource indicates 953 that its internal member URIs can be ordered. It implies nothing 954 about whether any collections identified by its internal member URIs 955 can be ordered. 957 Furthermore, RFC 3253 [RFC3253] introduces the live properties 958 DAV:supported-method-set (section 3.1.3) and 959 DAV:supported-live-property-set (section 3.1.4). Servers MUST support 960 these properties as defined in RFC 3253. 962 10.1 Example: Using OPTIONS for the Discovery of Support for Ordering 964 >> Request: 966 OPTIONS /somecollection/ HTTP/1.1 967 Host: example.org 969 >> Response: 971 HTTP/1.1 200 OK 972 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE 973 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 974 DAV: 1, 2, ordered-collections 976 The DAV header in the response indicates that the resource / 977 somecollection/ is level 1 and level 2 compliant, as defined in 978 [RFC2518]. In addition, /somecollection/ supports ordering. The 979 Allow header indicates that ORDERPATCH requests can be submitted to / 980 somecollection/. 982 10.2 Example: Using Live Properties for the Discovery of Ordering 984 >> Request: 985 PROPFIND /somecollection HTTP/1.1 986 Depth: 0 987 Content-Type: text/xml; charset="utf-8" 988 Content-Length: xxx 990 991 992 993 994 995 996 998 >> Response: 999 HTTP/1.1 207 Multi-Status 1000 Content-Type: text/xml; charset="utf-8" 1001 Content-Length: xxx 1003 1004 1005 1006 http://example.org/somecollection 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 HTTP/1.1 200 OK 1034 1035 1036 1038 Note that actual responses MUST contain a complete list of supported 1039 live properties. 1041 11. Security Considerations 1043 This section is provided to make WebDAV applications aware of the 1044 security implications of this protocol. 1046 All of the security considerations of HTTP/1.1 and the WebDAV 1047 Distributed Authoring Protocol specification also apply to this 1048 protocol specification. In addition, ordered collections introduce a 1049 new security concern. This issue is detailed here. 1051 11.1 Denial of Service and DAV:ordering-type 1053 There may be some risk of denial of service at sites that are 1054 advertised in the DAV:ordering-type property of collections. 1055 However, it is anticipated that widely-deployed applications will use 1056 hard-coded values for frequently-used ordering semantics rather than 1057 looking up the semantics at the location specified by 1058 DAV:ordering-type. This risk will be further reduced if clients 1059 observe the recommendation of Section 5.1 that they not send requests 1060 to the URI in DAV:ordering-type. 1062 12. Internationalization Considerations 1064 This specification follows the practices of [RFC2518] in encoding all 1065 human-readable content using [XML] and in the treatment of names. 1066 Consequently, this specification complies with the IETF Character Set 1067 Policy [RFC2277]. 1069 WebDAV applications MUST support the character set tagging, character 1070 set encoding, and the language tagging functionality of the XML 1071 specification. This constraint ensures that the human-readable 1072 content of this specification complies with [RFC2277]. 1074 As in [RFC2518], names in this specification fall into three 1075 categories: names of protocol elements such as methods and headers, 1076 names of XML elements, and names of properties. Naming of protocol 1077 elements follows the precedent of HTTP, using English names encoded 1078 in USASCII for methods and headers. The names of XML elements used 1079 in this specification are English names encoded in UTF-8. 1081 For error reporting, [RFC2518] follows the convention of HTTP/1.1 1082 status codes, including with each status code a short, English 1083 description of the code (e.g., 423 Locked). Internationalized 1084 applications will ignore this message, and display an appropriate 1085 message in the user's language and character set. 1087 This specification introduces no new strings that are displayed to 1088 users as part of normal, error-free operation of the protocol. 1090 For rationales for these decisions and advice for application 1091 implementors, see [RFC2518]. 1093 13. IANA Considerations 1095 This document uses the namespaces defined by [RFC2518] for properties 1096 and XML elements. All other IANA considerations mentioned in 1097 [RFC2518] also apply to this document. 1099 14. Copyright 1101 To be supplied by the RFC Editor. 1103 15. Intellectual Property 1105 To be supplied by the RFC Editor. 1107 16. Contributors 1109 This document has benefited from significant contributions from Geoff 1110 Clemm, Jason Crawford, Jim Davis, Chuck Fay and Judith Slein. 1112 17. Acknowledgements 1114 This document has benefited from thoughtful discussion by Jim Amsden, 1115 Steve Carter, Tyson Chihaya, Ken Coar, Ellis Cohen, Bruce Cragun, 1116 Spencer Dawkins, Mark Day, Rajiv Dulepet, David Durand, Lisa 1117 Dusseault, Roy Fielding, Yaron Goland, Fred Hitt, Alex Hopmann, 1118 Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, Daniel 1119 LaLiberte, Steve Martin, Larry Masinter, Jeff McAffer, Surendra 1120 Koduru Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness, 1121 John Stracke, John Tigue, John Turner, Kevin Wiggen, and others. 1123 Normative References 1125 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1126 Requirement Levels", BCP 14, RFC 2119, March 1997. 1128 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 1129 Languages", BCP 18, RFC 2277, January 1998. 1131 [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 1132 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1133 August 1998. 1135 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. 1136 Jensen, "HTTP Extensions for Distributed Authoring -- 1137 WEBDAV", RFC 2518, February 1999. 1139 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1140 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext 1141 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1143 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and J. 1144 Whitehead, "Versioning Extensions to WebDAV", RFC 3253, 1145 March 2002. 1147 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, 1148 "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C 1149 REC-xml, October 2000, . 1152 [1] 1154 [2] 1156 Authors' Addresses 1158 Jim Whitehead 1159 UC Santa Cruz, Dept. of Computer Science 1160 1156 High Street 1161 Santa Cruz, CA 95064 1162 US 1164 EMail: ejw@cse.ucsc.edu 1165 Julian F. Reschke (editor) 1166 greenbytes GmbH 1167 Salzmannstrasse 152 1168 Muenster, NW 48159 1169 Germany 1171 Phone: +49 251 2807760 1172 Fax: +49 251 2807761 1173 EMail: julian.reschke@greenbytes.de 1174 URI: http://greenbytes.de/tech/webdav/ 1176 Appendix A. Extensions to the WebDAV Document Type Definition 1178 1179 1180 1181 1182 1183 1184 1185 1186 1188 Appendix B. Change Log 1190 B.1 Since draft-ietf-webdav-ordering-protocol dated December 1999 1192 Updated contact information for all previous authors. 1193 Specify charset when using text/xml media type. 1194 Made sure artwork fits into 72 columns. 1195 Removed "Public" header from OPTIONS example. 1196 Added Julian Reschke to list of authors. 1197 Fixed broken XML in PROPFIND example and added DAV:orderingtype to 1198 list of requested properties. 1199 Added support for DAV:supported-live-property-set and 1200 DAV:supported-method-set as mandatory features. 1202 B.2 Since draft-ietf-webdav-ordering-protocol-02 1204 Updated change log to refer to expired draft version as "December 1205 1999" version. 1206 Started rewrite marshalling in RFC3253-style and added precondition 1207 and postcondition definitions. 1208 On his request, removed Geoff Clemm's name from the author list 1209 (moved to Acknowledgments). 1210 Renamed "References" to "Normative References". 1211 Removed reference to "MKREF" method. 1213 B.3 Since draft-ietf-webdav-ordering-protocol-03 1215 Added a set of issues regarding marshalling. 1216 Changed host names to use proper "example" domain names (no change 1217 tracking). Fixed host/destination header conflicts. Fixed "allow" 1218 header (multiline). Removed irrelevant response headers. Abbreviated 1219 some URIs (no change tracking). 1220 Removed Jim Davis and Chuck Fay from the author list (and added them 1221 to the Acknowledgements section). 1222 Updated section on setting the position when adding new members, 1223 removed old section on Position header. 1224 Started work on Index section. 1225 Changed structure for section 7 (no change tracking). 1226 Removed header and XML elements section (contents moved to other 1227 sections). 1228 Started new section on relation to versioned collections as per 1229 RFC3253. 1230 Do not return 424's for in ORDERPATCH multistatus (it's atomic 1231 anyway). 1233 B.4 Since draft-ietf-webdav-ordering-protocol-04 1235 Added proper reference to definition of "Coded-URL". 1237 Closed issue ordering-type-values (content model simplified and XML 1238 element / DAV property renamed) and updated examples. 1239 Renamed precondition DAV:orderingtype-set to DAV:ordering-type-set 1240 (no change tracking). 1241 Closed issue ordered-header-name (header name changed to 1242 "ordering-type", contents matches live property). 1243 Closed issue ordermember-format (now takes segment instead of href). 1244 Renamed compliance class to "ordered-collections" for consistency 1245 with newer specs, and to allow detection of compliance to final 1246 version of spec. 1247 Updated reference to XML spec to 1.0, 2nd edition. 1249 B.5 Since draft-ietf-webdav-ordering-protocol-05 1251 Typos fixed. 1252 Renamed DAV:ordermember to DAV:order-member. 1253 Made RFC3253-compatible pre/postcondition handling a MUST 1254 requirement. 1255 Reference definition of "protected property" from RFC3253. 1256 Added explanation of role of DTD fragments to Notation section. 1257 Clarified semantics for operations on versioned collections and 1258 collection versions. 1260 B.6 Since draft-ietf-webdav-ordering-protocol-06 1262 Added atomicity statement for ORDERPATCH method. 1264 B.7 Since draft-ietf-webdav-ordering-protocol-07 1266 Added issues "4.1-DELETE-behaviour", "6.1-safe-update", 1267 "6.1-when-are-members-added" and 1268 "9.4-UPDATE-non-version-controlled-members" and resolved them. Added 1269 new "contributors" section, and mention original authors such as 1270 Judith Slein there. 1272 Index 1274 C 1275 Client-Maintained Ordering 6 1277 D 1278 DAV:collection-must-be-ordered precondition 12 1279 DAV:custom ordering type 8 1280 DAV:initialize-collection-version-ordering-type 23 1281 DAV:initialize-ordering-type 24 1282 DAV:initialize-version-controlled-bindings-ordered postcondition 23 1283 DAV:initialize-version-history-bindings-ordered 24 1284 DAV:ordered-collections-supported precondition 9 1285 DAV:ordering-modified postcondition 15 1286 DAV:ordering-type property 7 1287 DAV:ordering-type-set postcondition 9, 15 1288 DAV:position-set postcondition 12 1289 DAV:segment-must-identify-member precondition 12 1290 DAV:unordered ordering type 8 1291 DAV:update-version-controlled-collection-members-ordered 24 1292 DAV:update-version-ordering-type 24 1294 H 1295 Headers 1296 Ordering-Type 9 1298 O 1299 Ordered Collection 6 1300 Ordering-Type header 9 1301 ORDERPATCH method 14 1303 P 1304 Postconditions 1305 DAV:initialize-collection-version-ordering-type 23 1306 DAV:initialize-ordering-type 24 1307 DAV:initialize-version-controlled-bindings-ordered 23 1308 DAV:initialize-version-history-bindings-ordered 24 1309 DAV:ordering-modified 15 1310 DAV:ordering-type-set 9, 15 1311 DAV:position-set 12 1312 DAV:update-version-controlled-collection-members-ordered 24 1313 DAV:update-version-ordering-type 24 1314 Preconditions 1315 DAV:collection-must-be-ordered 12 1316 DAV:ordered-collections-supported 9 1317 DAV:segment-must-identify-member 12 1318 Protected properties 1319 DAV:ordering-type 7 1321 S 1322 Server-Maintained Ordering 6 1324 U 1325 Unordered Collection 6 1327 Intellectual Property Statement 1329 The IETF takes no position regarding the validity or scope of any 1330 intellectual property or other rights that might be claimed to 1331 pertain to the implementation or use of the technology described in 1332 this document or the extent to which any license under such rights 1333 might or might not be available; neither does it represent that it 1334 has made any effort to identify any such rights. Information on the 1335 IETF's procedures with respect to rights in standards-track and 1336 standards-related documentation can be found in BCP-11. Copies of 1337 claims of rights made available for publication and any assurances of 1338 licenses to be made available, or the result of an attempt made to 1339 obtain a general license or permission for the use of such 1340 proprietary rights by implementors or users of this specification can 1341 be obtained from the IETF Secretariat. 1343 The IETF invites any interested party to bring to its attention any 1344 copyrights, patents or patent applications, or other proprietary 1345 rights which may cover technology that may be required to practice 1346 this standard. Please address the information to the IETF Executive 1347 Director. 1349 Full Copyright Statement 1351 Copyright (C) The Internet Society (2003). All Rights Reserved. 1353 This document and translations of it may be copied and furnished to 1354 others, and derivative works that comment on or otherwise explain it 1355 or assist in its implementation may be prepared, copied, published 1356 and distributed, in whole or in part, without restriction of any 1357 kind, provided that the above copyright notice and this paragraph are 1358 included on all such copies and derivative works. However, this 1359 document itself may not be modified in any way, such as by removing 1360 the copyright notice or references to the Internet Society or other 1361 Internet organizations, except as needed for the purpose of 1362 developing Internet standards in which case the procedures for 1363 copyrights defined in the Internet Standards process must be 1364 followed, or as required to translate it into languages other than 1365 English. 1367 The limited permissions granted above are perpetual and will not be 1368 revoked by the Internet Society or its successors or assignees. 1370 This document and the information contained herein is provided on an 1371 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1372 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1373 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1374 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1375 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1377 Acknowledgement 1379 Funding for the RFC Editor function is currently provided by the 1380 Internet Society.