idnits 2.17.1 draft-ietf-webdav-ordering-protocol-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 2 characters in excess of 72. == There are 7 instances 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 (September 2002) is 7887 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2518 (Obsoleted by RFC 4918) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Slein 3 Internet Draft Xerox 4 Expires: March 2003 J. Whitehead 5 U.C. Santa Cruz 6 J. Davis 7 Intelligent Markets 8 C. Fay 9 FileNet 10 J. Crawford 11 IBM 12 J. F. Reschke 13 greenbytes 14 September 2002 16 WebDAV Ordered Collections Protocol 17 draft-ietf-webdav-ordering-protocol-03 19 Status of this Memo 21 This document is an Internet-Draft and is in full conformance with 22 all provisions of Section 10 of RFC2026. Internet-Drafts are working 23 documents of the Internet Engineering Task Force (IETF), its areas, 24 and its working groups. Note that other groups may also distribute 25 working documents as Internet-Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress". 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 This Internet-Draft will expire in March 2003. 40 Copyright Notice 42 Copyright (C) The Internet Society (2002). All Rights Reserved. 44 Abstract 46 This specification extends the WebDAV Distributed Authoring Protocol 47 to support server-side ordering of collection members. Of particular 48 interest are orderings that are not based on property values, and so 49 cannot be achieved using a search protocol's ordering option and 50 cannot be maintained automatically by the server. Protocol elements 51 are defined to let clients specify the position in the ordering of 52 each collection member, as well as the semantics governing the 53 ordering. 55 Distribution of this document is unlimited. Please send comments to 56 the Distributed Authoring and Versioning (WebDAV) working group at 57 w3c-dist-auth@w3.org, which may be joined by sending a message with 58 subject "subscribe" to w3c-dist-auth-request@w3.org. 60 Discussions of the WEBDAV working group are archived at URL: 61 http://lists.w3.org/Archives/Public/w3c-dist-auth/. 63 Table of Contents 65 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 66 Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1 Notational Conventions . . . . . . . . . . . . . . . . . . . . 5 68 2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 3 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 4 Overview of Ordered Collections . . . . . . . . . . . . . . . . 8 71 4.1 Additional Collection properties . . . . . . . . . . . . . 8 72 4.1.1 DAV:orderingtype (protected) . . . . . . . . . . . . . 9 73 5 Creating an Ordered Collection . . . . . . . . . . . . . . . . 10 74 5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 5.2 Example: Creating an Ordered Collection . . . . . . . . . . 11 76 6 Setting the Position of a Collection Member . . . . . . . . . . 12 77 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 12 78 6.2 Status Codes . . . . . . . . . . . . . . . . . . . . . . . 12 79 6.3 Examples: Setting the Position of a Collection Member . . . 12 80 7 Changing a Collection Ordering . . . . . . . . . . . . . . . . 14 81 7.1 ORDERPATCH Method . . . . . . . . . . . . . . . . . . . . . 14 82 7.1.1 Status Codes . . . . . . . . . . . . . . . . . . . . . 14 83 7.1.2 Example: Changing a Collection Ordering . . . . . . . . 15 84 7.1.3 Example: Failure of an ORDERPATCH Request . . . . . . . 17 85 8 Listing the Members of an Ordered Collection . . . . . . . . . 19 86 8.1 Example: PROPFIND on an Ordered Collection . . . . . . . . 19 87 9 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 88 9.1 Position Request Header . . . . . . . . . . . . . . . . . . 23 89 10 XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . 24 90 10.1 order XML Element . . . . . . . . . . . . . . . . . . . . 24 91 10.2 ordermember XML Element . . . . . . . . . . . . . . . . . 24 92 10.3 position XML Element . . . . . . . . . . . . . . . . . . . 25 93 10.4 first XML Element . . . . . . . . . . . . . . . . . . . . 25 94 10.5 last XML Element . . . . . . . . . . . . . . . . . . . . . 25 95 10.6 before XML Element . . . . . . . . . . . . . . . . . . . . 26 96 10.7 after XML Element . . . . . . . . . . . . . . . . . . . . 26 97 10.8 segment XML Element . . . . . . . . . . . . . . . . . . . 27 98 11 Capability Discovery . . . . . . . . . . . . . . . . . . . . . 28 99 11.1 Example: Using OPTIONS for the Discovery of Support for 100 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 101 11.2 Example: Using Live Properties for the Discovery of 102 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 103 12 Security Considerations . . . . . . . . . . . . . . . . . . . 31 104 12.1 Denial of Service and DAV:orderingtype . . . . . . . . . . 31 105 13 Internationalization Considerations . . . . . . . . . . . . . 32 106 14 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 107 15 Copyright . . . . . . . . . . . . . . . . . . . . . . . . . . 34 108 16 Intellectual Property . . . . . . . . . . . . . . . . . . . . 35 109 17 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 36 110 Normative References . . . . . . . . . . . . . . . . . . . . . . 37 111 Author's Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 112 A Extensions to the WebDAV Document Type Definition . . . . . . . 39 113 B Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 40 114 B.1 Since draft-ietf-webdav-ordering-protocol dated December 115 1999 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 116 B.2 Since draft-ietf-webdav-ordering-protocol-02 . . . . . . . 40 118 1 Notational Conventions 120 Since this document describes a set of extensions to the WebDAV 121 Distributed Authoring Protocol [RFC2518], itself an extension to the 122 HTTP/1.1 protocol, the augmented BNF used here to describe protocol 123 elements is exactly the same as described in Section 2.1 of HTTP 124 [RFC2616]. Since this augmented BNF uses the basic production rules 125 provided in Section 2.2 of HTTP, these rules apply to this document 126 as well. 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 130 document are to be interpreted as described in [RFC2119]. 132 2 Introduction 134 This specification builds on the collection infrastructure provided 135 by the WebDAV Distributed Authoring Protocol, adding support for the 136 server-side ordering of collection members. 138 There are many scenarios where it is useful to impose an ordering on 139 a collection at the server, such as expressing a recommended access 140 order, or a revision history order. The members of a collection might 141 represent the pages of a book, which need to be presented in order if 142 they are to make sense. Or an instructor might create a collection of 143 course readings, which she wants to be displayed in the order they 144 are to be read. 146 Orderings may be based on property values, but this is not always the 147 case. The resources in the collection may not have properties that 148 can be used to support the desired ordering. Orderings based on 149 properties can be obtained using a search protocol's ordering option, 150 but orderings not based on properties cannot. These orderings 151 generally need to be maintained by a human user. 153 The ordering protocol defined here focuses on support for such human- 154 maintained orderings. Its protocol elements allow clients to specify 155 the position of each collection member in the collection's ordering, 156 as well as the semantics governing the ordering. The protocol is 157 designed to allow support to be added in the future for orderings 158 that are maintained automatically by the server. 160 The remainder of this document is structured as follows: Section 3 161 defines terminology that will be used throughout the specification. 162 Section 4 provides an overview of ordered collections. Section 5 163 describes how to create an ordered collection, and Section 6 164 discusses how to set a member's position in the ordering of a 165 collection. Section 7 explains how to change a collection ordering. 166 Section 8 discusses listing the members of an ordered collection. 167 Section 9 through Section 10 define the headers, properties, and XML 168 elements needed to support ordered collections. Section 11 describes 169 capability discovery. Section 12 through Section 14 discuss security, 170 internationalization, and IANA considerations. The remaining sections 171 provide supporting information. 173 3 Terminology 175 The terminology used here follows that in the [RFC2518]. Definitions 176 of the terms resource, Uniform Resource Identifier (URI), and Uniform 177 Resource Locator (URL) are provided in [RFC2396]. 179 Ordered Collection 181 A collection for which the results from a PROPFIND request are 182 guaranteed to be in the order specified for that collection 184 Unordered Collection 186 A collection for which the client cannot depend on the 187 repeatability of the ordering of results from a PROPFIND request 189 Client-Maintained Ordering 191 An ordering of collection members that is maintained on the server 192 based on client requests specifying the position of each 193 collection member in the ordering 195 Server-Maintained Ordering 197 An ordering of collection members that is maintained automatically 198 by the server, based on a client's choice of ordering semantics 200 This document uses the terms "precondition" as "postcondition" as 201 defined in [RFC3253]. Servers should report pre-/postcondition 202 failures as described in section 1.6 of this document. 204 4 Overview of Ordered Collections 206 If a collection is unordered, the client cannot depend on the 207 repeatability of the ordering of results from a PROPFIND request. By 208 specifying an ordering for a collection, a client requires the server 209 to follow that ordering whenever it responds to a PROPFIND request on 210 that collection. 212 Server-side orderings may be client-maintained or server-maintained. 213 For client-maintained orderings, a client must specify the ordering 214 position of each of the collection's members, either when the member 215 is added to the collection (using the Position header) or later 216 (using the ORDERPATCH method). For server-maintained orderings, the 217 server automatically positions each of the collection's members 218 according to the ordering semantics. This specification supports only 219 client-maintained orderings, but is designed to allow future 220 extension to server-maintained orderings. 222 A collection that supports ordering is not required to be ordered. It 223 is up to the client to decide whether a given collection is ordered 224 and, if so, to specify the semantics to be used for ordering its 225 members. 227 If a collection is ordered, each of its internal member URIs MUST be 228 in the ordering exactly once, and the ordering MUST NOT include any 229 URI that is not an internal member of the collection. The server is 230 responsible for enforcing these constraints on orderings. The server 231 MUST remove an internal member URI from the ordering when it is 232 removed from the collection. The server MUST an internal member URI 233 to the ordering when it is added to the collection. 235 Only one ordering can be attached to any collection. Multiple 236 orderings of the same resources can be achieved by creating multiple 237 collections referencing those resources, and attaching a different 238 ordering to each collection. 240 An ordering is considered to be part of the state of a collection 241 resource. Consequently, the ordering is the same no matter which URI 242 is used to access the collection and is protected by locks or access 243 control constraints on the collection. 245 4.1 Additional Collection properties 246 4.1.1 DAV:orderingtype (protected) 248 Indicates whether the collection is ordered and, if so, uniquely 249 identifies the semantics of the ordering being used. May also point 250 to an explanation of the semantics in human and / or machine-readable 251 form. At a minimum, this allows human users who add members to the 252 collection to understand where to position them in the ordering. This 253 property cannot be set using PROPPATCH. Its value can only be set by 254 including the Ordered header with a MKCOL request or by submitting an 255 ORDERPATCH request. 257 The value DAV:unordered indicates that the collection is not ordered. 258 That is, the client cannot depend on the repeatability of the 259 ordering of results from a PROPFIND request. 261 The value DAV:custom indicates that the collection is ordered, but 262 the semantics governing the ordering are not being advertised. 264 If the value is a DAV:href element, it contains a URI that uniquely 265 identifies the semantics of the collection's ordering. 267 An ordering-aware client interacting with an ordering-unaware server 268 (e.g., one that is implemented only according to [RFC2518]) SHOULD 269 assume that if a collection does not have the DAV:orderingtype 270 property, the collection is unordered. 272 273 274 276 5 Creating an Ordered Collection 278 5.1 Overview 280 When a collection is created, the client MAY request that it be 281 ordered and specify the semantics of the ordering by using the new 282 Ordered header (defined below) with a MKCOL request. 284 For collections that are ordered, the client SHOULD identify the 285 semantics of the ordering with a URI in the Ordered header, although 286 the client MAY simply set the header value to DAV:custom to indicate 287 that the collection is ordered but the semantics of the ordering are 288 not being advertised. Setting the value to a URI that identifies the 289 ordering semantics provides the information a human user or software 290 package needs to insert new collection members into the ordering 291 intelligently. Although the URI in the Ordered header MAY point to a 292 resource that contains a definition of the semantics of the ordering, 293 clients SHOULD NOT access that resource, in order to avoid 294 overburdening its server. A value of DAV:unordered in the Ordering 295 header indicates that the client wants the collection to be 296 unordered. If the Ordered header is not present, the collection will 297 be unordered. 299 Additional Marshalling: 301 Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) 303 A value of "DAV:unordered" indicates that the collection is not 304 ordered. A value of "DAV:custom" indicates that the collection is 305 to be ordered, but the semantics of the ordering is not being 306 advertised. Any other Coded-url value indicates that the 307 collection is ordered, and identifies the semantics of the 308 ordering. 310 Additional Preconditions: 312 (DAV:ordered-collections-supported): the server must support 313 ordered collections where the new collection is to be created. 315 5.2 Example: Creating an Ordered Collection 317 >> Request: 319 MKCOL /theNorth/ HTTP/1.1 320 Host: www.server.org 321 Ordered: 323 >> Response: 325 HTTP/1.1 201 Created 327 In this example a new, ordered collection was created. Its 328 DAV:orderingtype property has as its value the URI from the Ordered 329 header, http://www.server.org/orderings/compass.html. In this case, 330 the URI identifies the semantics governing a client-maintained 331 ordering. As new members are added to the collection, clients or end 332 users can use the semantics to determine where to position the new 333 members in the ordering. 335 6 Setting the Position of a Collection Member 337 6.1 Overview 339 When a new member is added to a collection with a client-maintained 340 ordering (for example, with PUT, COPY, or MKCOL), its position in the 341 ordering can be set with the new Position header (defined in Section 342 9.1). The Position header allows the client to specify that an 343 internal member URI should be first in the collection's ordering, 344 last in the collection's ordering, immediately before some other 345 internal member URI in the collection's ordering, or immediately 346 after some other internal member URI in the collection's ordering. 348 If the Position request header is not used when adding a member to an 349 ordered collection, then: 351 o If the request is replacing an existing resource, the server MUST 352 preserve the present ordering. 354 o If the request is adding a new internal member URI to the 355 collection, the server MUST append the new member to the end of 356 the ordering. 358 6.2 Status Codes 360 409 (Conflict): Several conditions may cause this response. The 361 request may specify a position that is before or after a URI that is 362 not an internal member URI of the collection, or before or after 363 itself. The request may attempt to specify the new member's position 364 in an unordered collection. 366 6.3 Examples: Setting the Position of a Collection Member 368 >> Request: 370 COPY /~whitehead/dav/spec08.html HTTP/1.1 371 Host: www.ics.uci.edu 372 Destination: http://www.xerox.com/~slein/dav/spec08.html 373 Position: after requirements.html 374 >> Response: 376 HTTP/1.1 201 Created 378 This request resulted in the creation of a new resource at 379 www.xerox.com/~slein/dav/spec08.html. The Position header in this 380 example caused the server to set its position in the ordering of the 381 /~slein/dav/ collection immediately after requirements.html. 383 >> Request: 385 MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 386 Host: www.ics.uci.edu 387 Destination: http://www.ics.uci.edu/~whitehead/dav/draft-webdav- 388 protocol-08.txt 389 Position: first 391 >> Response: 393 HTTP/1.1 409 Conflict 395 In this case, the server returned a 409 (Conflict) status code 396 because the /~whitehead/dav/ collection is an unordered collection. 397 Consequently, the server was unable to satisfy the Position header. 399 7 Changing a Collection Ordering 401 7.1 ORDERPATCH Method 403 The ORDERPATCH method is used to change the ordering semantics of a 404 collection or to change the order of the collection's members in the 405 ordering or both. 407 The ORDERPATCH method changes the ordering semantics of the 408 collection identified by the Request-URI, based on the value of 409 DAV:orderingtype submitted in the request entity body. 411 The ORDERPATCH method alters the ordering of internal member URIs in 412 the collection identified by the Request-URI, based on instructions 413 in the ordermember XML elements in the request entity body. The 414 ordermember XML elements identify the internal member URIs whose 415 positions are to be changed, and describe their new positions in the 416 ordering. Each new position can be specified as first in the 417 ordering, last in the ordering, immediately before some other 418 internal member URI, or immediately after some other internal member 419 URI. 421 The server MUST apply the changes in the order they appear in the 422 order XML element. The server MUST either apply all the changes or 423 apply none of them. If any error occurs during processing, all 424 executed changes MUST be undone and a proper error result returned. 426 If an ORDERPATCH request changes the ordering semantics, but does not 427 completely specify the order of the collection members, the server 428 MUST assign a position in the ordering to each collection member for 429 which a position was not specified. These server-assigned positions 430 MUST all follow the last one specified by the client. The result is 431 that all members for which the client specified a position are at the 432 beginning of the ordering, followed by any members for which the 433 server assigned positions. 435 If an ORDERPATCH request does not change the ordering semantics, any 436 member positions not specified in the request MUST remain unchanged. 438 7.1.1 Status Codes 440 Since multiple changes can be requested in a single ORDERPATCH 441 request, if any problems are encountered, the server MUST return a 442 207 (Multi-Status) response, as defined in [RFC2518]. 444 The following are examples of response codes one would expect to be 445 used in a 207 (Multi-Status) response for this method: 447 200 (OK): The change in ordering was successfully made. 449 409 (Conflict): Several conditions may cause this response. The 450 request may specify a position that is before or after a URI that is 451 not an internal member URI of the collection, or before or after 452 itself. The request may attempt to set the positions of members of an 453 unordered collection. 455 A request to reposition a collection member at the same place in the 456 ordering is not an error. 458 7.1.2 Example: Changing a Collection Ordering 460 Consider a collection /coll-1/ whose DAV:orderingtype is DAV:whim, 461 with bindings ordered as follows: 463 three.html 464 four.html 465 one.html 466 two.html 468 >> Request: 470 ORDERPATCH /coll-1/ HTTP/1.1 471 Host: www.myserver.com 472 Content-Type: text/xml; charset="utf-8" 473 Content-Length: xxx 475 476 477 478 http://www.myserver.com/inorder.ord 479 480 481 two.html 482 483 484 486 487 488 one.html 489 490 491 492 493 494 three.html 495 496 497 498 499 500 four.html 501 502 503 504 505 507 >> Response: 509 HTTP/1.1 200 OK 511 In this example, after the request has been processed, the 512 collection's ordering semantics are identified by the URI 513 http://www.myserver.com/inorder.ord. The value of the collection's 514 DAV:orderingtype property has been set to this URI. The request also 515 contains instructions for changing the positions of the collection's 516 internal member URIs in the ordering to comply with the new ordering 517 semantics. If href elements are relative URIs, as in this example, 518 they are interpreted relative to the collection whose ordering is 519 being modified. The DAV:ordermember elements are required to be 520 processed in the order they appear in the request. Consequently, 521 two.html is moved to the beginning of the ordering, and then one.html 522 is moved to the beginning of the ordering. Then three.html is moved 523 to the end of the ordering, and finally four.html is moved to the end 524 of the ordering. After the request has been processed, the 525 collection's ordering is as follows: 527 one.html 528 two.html 529 three.html 530 four.html 532 7.1.3 Example: Failure of an ORDERPATCH Request 534 Consider a collection /coll-1/ with members ordered as follows: 536 nunavut.map 537 nunavut.img 538 baffin.map 539 baffin.desc 540 baffin.img 541 iqaluit.map 542 nunavut.desc 543 iqaluit.img 544 iqaluit.desc 546 >> Request: 548 ORDERPATCH /coll-1/ HTTP/1.1 549 Host: www.nunanet.com 550 Content-Type: text/xml; charset="utf-8" 551 Content-Length: xxx 553 554 555 556 nunavut.desc 557 558 559 nunavut.map 560 561 562 563 564 iqaluit.map 565 566 567 pangnirtung.img 568 569 570 571 573 >> Response: 575 HTTP/1.1 207 Multi-Status 576 Content-Type: text/xml; charset="utf-8" 577 Content-Length: xxx 579 580 581 582 http://www.nunanet.com/coll-1/nunavut.desc 583 HTTP/1.1 424 Failed Dependency 584 585 586 http://www.nunanet.com/coll-1/iqaluit.map 587 HTTP/1.1 409 Conflict 588 pangnirtung.img is not a collection 589 member. 590 591 593 In this example, the client attempted to position iqaluit.map after a 594 URI that is not an internal member of the collection /coll-1/. The 595 server responded to this client error with a 409 (Conflict) status 596 code. Because ORDERPATCH is an atomic method, the request to 597 reposition nunavut.desc (which would otherwise have succeeded) failed 598 with a 424 (Failed Dependency) status code. 600 8 Listing the Members of an Ordered Collection 602 A PROPFIND request is used to retrieve a listing of the members of an 603 ordered collection, just as it is used to retrieve a listing of the 604 members of an unordered collection. 606 However, when responding to a PROPFIND on an ordered collection, the 607 server MUST order the response elements according to the ordering 608 defined on the collection. If a collection is unordered, the client 609 cannot depend on the repeatability of the ordering of results from a 610 PROPFIND request. 612 In a response to a PROPFIND with Depth: infinity, members of 613 different collections may be interleaved. That is, the server is not 614 required to do a breadth-first traversal. The only requirement is 615 that the members of any ordered collection appear in the order 616 defined for the collection. Thus for the hierarchy illustrated in the 617 following figure, where collection A is an ordered collection with 618 the ordering B C D, 620 A 621 /|\ 622 / | \ 623 B C D 624 / /|\ 625 E F G H 627 it would be acceptable for the server to return response elements in 628 the order A B E C F G H D. In this response, B, C, and D appear in 629 the correct order, separated by members of other collections. Clients 630 can use a series of Depth: 1 PROPFIND requests to avoid the 631 complexity of processing Depth: infinity responses based on depth- 632 first traversals. 634 8.1 Example: PROPFIND on an Ordered Collection 636 Suppose a PROPFIND request is submitted to /MyCollection/, which has 637 its members ordered as follows. 639 /MyCollection/ 640 lakehazen.html 641 siorapaluk.html 642 iqaluit.html 643 newyork.html 645 >> Request: 647 PROPFIND /MyCollection/ HTTP/1.1 648 Host: www.svr.com 649 Depth: 1 650 Content-Type: text/xml; charset="utf-8" 651 Content-Length: xxxx 653 654 655 656 657 658 659 660 662 >> Response: 664 HTTP/1.1 207 Multi-Status 665 Content-Type: text/xml; charset="utf-8" 666 Content-Length: xxxx 668 669 671 672 http://www.svr.com/MyCollection/ 673 674 675 676 677 678 HTTP/1.1 200 OK 679 680 681 682 683 684 HTTP/1.1 404 Not Found 685 686 687 688 http://www.svr.com/MyCollection/lakehazen.html 689 690 691 692 82N 693 694 HTTP/1.1 200 OK 695 696 697 698 699 700 HTTP/1.1 404 Not Found 701 702 703 704 http://www.svr.com/MyCollection/siorapaluk.html 706 707 708 709 78N 710 711 HTTP/1.1 200 OK 712 713 714 715 716 717 HTTP/1.1 404 Not Found 718 719 720 721 http://www.svr.com/MyCollection/iqaluit.html 722 723 724 725 62N 726 727 HTTP/1.1 200 OK 728 729 730 731 732 733 HTTP/1.1 404 Not Found 734 735 736 737 http://www.svr.com/MyCollection/newyork.html 738 739 740 741 45N 742 743 HTTP/1.1 200 OK 744 745 746 747 748 HTTP/1.1 404 Not Found 749 750 751 752 754 In this example, the server responded with a list of the collection 755 members in the order defined for the collection. 757 9 Headers 759 9.1 Position Request Header 761 Position = "Position" ":" ("first" | "last" | 762 (("before" | "after") segment)) 764 segment is defined in Section 3.3 of [RFC2396]. 766 The Position header may be used with any method that adds a member to 767 an ordered collection, to tell the server where in the collection 768 ordering to position the new member being added to the collection. 769 Examples of methods that add members to collections are BIND, PUT, 770 COPY, MOVE, etc. 772 The segment is interpreted relative to the collection to which the 773 new member is being added. 775 The server MUST insert the new member into the ordering at the 776 location specified in the Position header, if one is present (and if 777 the collection is ordered). 779 The "first" keyword indicates the new member is put in the beginning 780 position in the collection's ordering, while "last" indicates the new 781 member is put in the final position in the collection's ordering. The 782 "before" keyword indicates the new member is added to the 783 collection's ordering immediately prior to the position of the member 784 identified in the segment. Likewise, the "after" keyword indicates 785 the new member is added to the collection's ordering immediately 786 following the position of the member identified in the segment. 788 If the request is replacing an existing resource, and the Position 789 header is present, the server MUST remove the internal member URI 790 from its previous position, and then insert it at the requested 791 position. 793 If an attempt is made to use the Position header on a collection that 794 is unordered, the server MUST fail the request with a 409 (Conflict) 795 status code. 797 10 XML Elements 799 10.1 order XML Element 801 Name: order 802 Namespace: DAV: 803 Purpose: For use with the new ORDERPATCH method. Describes a change 804 to be made in a collection's ordering semantics or in the 805 positions of its members in the ordering or both. 806 Value: An optional identifier of an ordering semantics for the 807 collection, followed by a list of changes to be made in 808 the positions of the members in the collection's ordering. 810 812 10.2 ordermember XML Element 814 Name: ordermember 815 Namespace: DAV: 816 Purpose: Occurs in the order XML element, and describes the new 817 position of a single internal member URI in the 818 collection's ordering. 819 Value: An href containing a member's path segment, and a 820 description of its new position in the ordering. The href 821 XML element is defined in [RFC2518], Section 11.3. 823 825 10.3 position XML Element 827 Name: position 828 Namespace: DAV: 829 Purpose: Occurs in the ordermember XML element. Describes the new 830 position in a collection's ordering of one of the members 831 it contains. 832 Value: The new position can be described as first in the 833 collection's ordering, last in the collection's ordering, 834 immediately before some other collection member, or 835 immediately after some other collection member. 837 839 10.4 first XML Element 841 Name: first 842 Namespace: DAV: 843 Purpose: Occurs in the position XML element. Specifies that the 844 member should be placed first in the collection's 845 ordering. 847 849 10.5 last XML Element 850 Name: last 851 Namespace: DAV: 852 Purpose: Occurs in the position XML element. Specifies that the 853 member should be placed last in the collection's ordering. 855 857 10.6 before XML Element 859 Name: before 860 Namespace: DAV: 861 Purpose: Occurs in the position XML element. Specifies that the 862 member should be placed immediately before the member in 863 the enclosed segment XML element in the collection's 864 ordering. 865 Value: URI (relative to the parent collection) of the member it 866 precedes in the ordering 868 870 10.7 after XML Element 872 Name: after 873 Namespace: DAV: 874 Purpose: Occurs in the position XML element. Specifies that the 875 member should be placed immediately after the member in 876 the enclosed segment XML element in the collection's 877 ordering. 879 Value: URI (relative to the parent collection) of the member it 880 follows in the ordering 882 884 10.8 segment XML Element 886 Name: segment 887 Namespace: DAV: 888 Purpose: Identifies a member of a collection, used in the 889 DAV:before and DAV:after elements, to define one member's 890 position in a collection ordering relative to another 891 member of the collection. 892 Value: segment ; as defined in section 3.3 of [RFC2396]. 894 896 11 Capability Discovery 898 Sections 9.1 and 15 of [RFC2518] describe the use of compliance 899 classes with the DAV header in responses to OPTIONS, to indicate 900 which parts of the Web Distributed Authoring protocols the resource 901 supports. This specification defines an OPTIONAL extension to 902 [RFC2518]. It defines a new compliance class, called orderedcoll, for 903 use with the DAV header in responses to OPTIONS requests. If a 904 collection resource does support ordering, its response to an OPTIONS 905 request may indicate that it does, by listing the new ORDERPATCH 906 method as one it supports, and by listing the new orderedcoll 907 compliance class in the DAV header. 909 When responding to an OPTIONS request, only a collection or a null 910 resource can include orderedcoll in the value of the DAV header. By 911 including orderedcoll, the resource indicates that its internal 912 member URIs can be ordered. It implies nothing about whether any 913 collections identified by its internal member URIs can be ordered. 915 Furthermore, RFC 3253 [RFC3253] introduces the live properties 916 DAV:supported-method-set (section 3.1.3) and DAV:supported-live- 917 property-set (section 3.1.4). Servers MUST support these properties 918 as defined in RFC 3253. 920 11.1 Example: Using OPTIONS for the Discovery of Support for Ordering 922 >> Request: 924 OPTIONS /somecollection/ HTTP/1.1 925 HOST: somehost.org 927 >> Response: 929 HTTP/1.1 200 OK 930 Date: Tue, 20 Jan 1998 20:52:29 GMT 931 Connection: close 932 Accept-Ranges: none 933 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 934 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 935 DAV: 1, 2, orderedcoll 936 The DAV header in the response indicates that the resource 937 /somecollection/ is level 1 and level 2 compliant, as defined in 938 [RFC2518]. In addition, /somecollection/ supports ordering. The Allow 939 header indicates that ORDERPATCH requests can be submitted to 940 /somecollection/. 942 11.2 Example: Using Live Properties for the Discovery of Ordering 944 >> Request: 946 PROPFIND /somecollection HTTP/1.1 947 Host: somehost.org 948 Depth: 0 949 Content-Type: text/xml; charset="utf-8" 950 Content-Length: xxx 952 953 954 955 956 957 958 960 >> Response: 962 HTTP/1.1 207 Multi-Status 963 Content-Type: text/xml; charset="utf-8" 964 Content-Length: xxx 966 967 968 969 http://somehost.org/somecollection 970 971 972 973 974 975 976 ... other live properties omitted for brevity ... 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 HTTP/1.1 200 OK 997 998 999 1001 Note that actual responses MUST contain a complete list of supported 1002 live properties. 1004 12 Security Considerations 1006 This section is provided to make WebDAV applications aware of the 1007 security implications of this protocol. 1009 All of the security considerations of HTTP/1.1 and the WebDAV 1010 Distributed Authoring Protocol specification also apply to this 1011 protocol specification. In addition, ordered collections introduce a 1012 new security concern. This issue is detailed here. 1014 12.1 Denial of Service and DAV:orderingtype 1016 There may be some risk of denial of service at sites that are 1017 advertised in the DAV:orderingtype property of collections. However, 1018 it is anticipated that widely-deployed applications will use hard- 1019 coded values for frequently-used ordering semantics rather than 1020 looking up the semantics at the location specified by 1021 DAV:orderingtype. This risk will be further reduced if clients 1022 observe the recommendation of Section 5.1 that they not send requests 1023 to the URI in DAV:orderingtype. 1025 13 Internationalization Considerations 1027 This specification follows the practices of [RFC2518] in encoding all 1028 human-readable content using [XML] and in the treatment of names. 1029 Consequently, this specification complies with the IETF Character Set 1030 Policy [RFC2277]. 1032 WebDAV applications MUST support the character set tagging, character 1033 set encoding, and the language tagging functionality of the XML 1034 specification. This constraint ensures that the human-readable 1035 content of this specification complies with [RFC2277]. 1037 As in [RFC2518], names in this specification fall into three 1038 categories: names of protocol elements such as methods and headers, 1039 names of XML elements, and names of properties. Naming of protocol 1040 elements follows the precedent of HTTP, using English names encoded 1041 in USASCII for methods and headers. The names of XML elements used in 1042 this specification are English names encoded in UTF-8. 1044 For error reporting, [RFC2518] follows the convention of HTTP/1.1 1045 status codes, including with each status code a short, English 1046 description of the code (e.g., 423 Locked). Internationalized 1047 applications will ignore this message, and display an appropriate 1048 message in the user's language and character set. 1050 This specification introduces no new strings that are displayed to 1051 users as part of normal, error-free operation of the protocol. 1053 For rationales for these decisions and advice for application 1054 implementors, see [RFC2518]. 1056 14 IANA Considerations 1058 This document uses the namespaces defined by [RFC2518] for properties 1059 and XML elements. All other IANA considerations mentioned in 1060 [RFC2518] also apply to this document. 1062 15 Copyright 1064 To be supplied by the RFC Editor. 1066 16 Intellectual Property 1068 To be supplied by the RFC Editor. 1070 17 Acknowledgements 1072 This draft has benefited from thoughtful discussion by Jim Amsden, 1073 Steve Carter, Tyson Chihaya, Geoff Clemm, Ken Coar, Ellis Cohen, 1074 Bruce Cragun, Spencer Dawkins, Mark Day, Rajiv Dulepet, David Durand, 1075 Roy Fielding, Yaron Goland, Fred Hitt, Alex Hopmann, Marcus Jager, 1076 Chris Kaler, Manoj Kasichainula, Rohit Khare, Daniel LaLiberte, Lisa 1077 Lippert, Steve Martin, Larry Masinter, Jeff McAffer, Surendra Koduru 1078 Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness, John 1079 Stracke, John Tigue, John Turner, Kevin Wiggen, and others. 1081 Normative References 1083 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1084 Requirement Levels", BCP 14, RFC 2119, March 1997. 1086 [RFC2277] Alvestrand, H.T., "IETF Policy on Character Sets and 1087 Languages", BCP 18, RFC 2277, January 1998. 1089 [RFC2396] Berners-Lee, T., Fielding, R.T. and Masinter, L., "Uniform 1090 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1091 August 1998. 1093 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S.R. and 1094 Jensen, D., "HTTP Extensions for Distributed Authoring -- 1095 WEBDAV", RFC 2518, February 1999. 1097 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1098 Masinter, L., Leach, P. and Berners-Lee, T., "Hypertext 1099 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1101 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and 1102 Whitehead, J., "Versioning Extensions to WebDAV", RFC 1103 3253, March 2002. 1105 [XML] World Wide Web Consortium, "Extensible Markup Language 1106 (XML) 1.0", W3C XML, February 1998. 1108 Author's Addresses 1110 Judith Slein 1111 Xerox Corporation 1112 800 Phillips Road, 105-50C 1113 Webster, NY 14580 1115 EMail: jslein@crt.xerox.com 1117 Jim Whitehead 1118 UC Santa Cruz, Dept. of Computer Science 1119 1156 High Street 1120 Santa Cruz, CA 95064 1121 US 1123 EMail: ejw@cse.ucsc.edu 1124 Jim Davis 1125 Intelligent Markets 1126 410 Jessie Street 6th floor 1127 San Francisco, CA 94103 1129 EMail: jrd3@alum.mit.edu 1131 Chuck Fay 1132 FileNet Corporation 1133 3565 Harbor Boulevard 1134 Costa Mesa, CA 92626-1420 1136 EMail: cfay@filenet.com 1138 Jason Crawford 1139 IBM Research 1140 P.O. Box 704 1141 Yorktown Heights, NY 10598 1143 EMail: ccjason@us.ibm.com 1145 Julian F. Reschke 1146 greenbytes GmbH 1147 Salzmannstrasse 152 1148 Muenster, NW 48159 1149 Germany 1151 Phone: +49 251 2807760 1152 Fax: +49 251 2807761 1153 EMail: julian.reschke@greenbytes.de 1154 URI: http://greenbytes.de/tech/webdav/ 1156 A Extensions to the WebDAV Document Type Definition 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1172 B Change Log 1174 B.1 Since draft-ietf-webdav-ordering-protocol dated December 1999 1176 Updated contact information for all previous authors. 1177 Specify charset when using text/xml media type. 1178 Made sure artwork fits into 72 columns. 1179 Removed "Public" header from OPTIONS example. 1180 Added Julian Reschke to list of authors. 1181 Fixed broken XML in PROPFIND example and added DAV:orderingtype to 1182 list of requested properties. 1183 Added support for DAV:supported-live-property-set and DAV:supported- 1184 method-set as mandatory features. 1186 B.2 Since draft-ietf-webdav-ordering-protocol-02 1188 Updated change log to refer to expired draft version as "December 1189 1999" version. 1190 Started rewrite marshalling in RFC3253-style and added precondition 1191 and postcondition definitions. 1192 On his request, removed Geoff Clemm's name from the author list 1193 (moved to Acknowledgments). 1194 Renamed "References" to "Normative References". 1195 Removed reference to "MKREF" method. 1197 Full Copyright Statement 1199 Copyright (C) The Internet Society (2002). All Rights Reserved. 1201 This document and translations of it may be copied and furnished to 1202 others, and derivative works that comment on or otherwise explain it 1203 or assist in its implementation may be prepared, copied, published 1204 and distributed, in whole or in part, without restriction of any 1205 kind, provided that the above copyright notice and this paragraph are 1206 included on all such copies and derivative works. However, this 1207 document itself may not be modified in any way, such as by removing 1208 the copyright notice or references to the Internet Society or other 1209 Internet organizations, except as needed for the purpose of 1210 developing Internet standards in which case the procedures for 1211 copyrights defined in the Internet Standards process must be 1212 followed, or as required to translate it into languages other than 1213 English. 1215 The limited permissions granted above are perpetual and will not be 1216 revoked by the Internet Society or its successors or assigns. 1218 This document and the information contained herein is provided on an 1219 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1220 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1221 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1222 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1223 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1225 Acknowledgement 1227 Funding for the RFC editor function is currently provided by the 1228 Internet Society.