idnits 2.17.1 draft-ietf-webdav-ordering-protocol-02.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 == The page length should not exceed 58 lines per page, but there was 19 longer pages, the longest (page 1) being 63 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 64 instances of lines with control characters in the document. == There are 6 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 20, 2000) is 8711 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 (ref. 'URI') (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' ** Obsolete normative reference: RFC 2616 (ref. 'HTTP') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2518 (ref. 'WebDAV') (Obsoleted by RFC 4918) Summary: 7 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 WEBDAV Working Group J. Slein, Xerox 2 INTERNET DRAFT E.J. Whitehead Jr., UC Irvine 3 J. Davis, CourseNet 4 G. Clemm, Rational 5 C. Fay, FileNet 6 J. Crawford, IBM 7 December 20, 1999 8 Expires June 20, 2000 10 WebDAV Ordered Collections Protocol 12 Status of this Memo 14 This document is an Internet-Draft and is in full conformance with all 15 provisions of Section 10 of RFC2026. Internet-Drafts are working 16 documents of the Internet Engineering Task Force (IETF), its areas, and 17 its working groups. Note that other groups may also distribute working 18 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 material 23 or to cite them other than as "work in progress". 25 The list of current Internet-Drafts can be accessed at 26 http://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 Distribution of this document is unlimited. Please send comments to the 32 Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject 34 "subscribe" to . 36 Discussions of the WEBDAV working group are archived at URL: 37 . 39 Abstract 41 This specification extends the WebDAV Distributed Authoring Protocol to 42 support server-side ordering of collection members. Of particular 43 interest are orderings that are not based on property values, and so 44 cannot be achieved using a search protocol's ordering option and cannot 45 be maintained automatically by the server. Protocol elements are 46 defined to let clients specify the position in the ordering of each 47 collection member, as well as the semantics governing the ordering. 49 Table of Contents 51 1 Notational Conventions.......................................2 52 2 Introduction.................................................2 53 3 Terminology..................................................3 54 4 Overview of Ordered Collections..............................4 55 5 Creating an Ordered Collection...............................4 56 5.1 Overview.....................................................4 57 5.2 Example: Creating an Ordered Collection......................5 58 6 Setting the Position of a Collection Member..................5 59 6.1 Overview.....................................................5 60 6.2 Status Codes.................................................6 61 6.3 Examples: Setting the Position of a Collection Member........6 62 7 Changing a Collection Ordering...............................6 63 7.1 ORDERPATCH Method............................................6 64 7.1.1 Status Codes.................................................7 65 7.1.2 Example: Changing a Collection Ordering......................7 66 7.1.3 Example: Failure of an ORDERPATCH Request....................9 67 8 Listing the Members of an Ordered Collection................10 68 8.1 Example: PROPFIND on an Ordered Collection..................11 69 9 Headers.....................................................12 70 9.1 Ordered Entity Header.......................................12 71 9.2 Position Request Header.....................................13 72 10 Properties..................................................13 73 10.1 orderingtype Property.......................................13 74 11 XML Elements................................................14 75 11.1 unordered XML Element.......................................14 76 11.2 custom XML Element..........................................14 77 11.3 order XML Element...........................................14 78 11.4 ordermember XML Element.....................................14 79 11.5 position XML Element........................................15 80 11.6 first XML Element...........................................15 81 11.7 last XML Element............................................15 82 11.8 before XML Element..........................................15 83 11.9 after XML Element...........................................15 84 11.10 segment XML Element.........................................16 85 12 Capability Discovery........................................16 86 12.1 Example: Discovery of Support for Ordering..................16 87 13 Security Considerations.....................................17 88 13.1 Denial of Service and DAV:orderingtype......................17 89 14 Internationalization Considerations.........................17 90 15 IANA Considerations.........................................18 91 16 Copyright...................................................18 92 17 Intellectual Property.......................................18 93 18 Acknowledgements............................................18 94 19 References..................................................18 95 20 Authors' Addresses..........................................18 96 21 Appendices..................................................19 97 21.1 Appendix 1: Extensions to the WebDAV Document Type 98 Definition..................................................19 100 1 Notational Conventions 102 Since this document describes a set of extensions to the WebDAV 103 Distributed Authoring Protocol [WebDAV], itself an extension to the 104 HTTP/1.1 protocol, the augmented BNF used here to describe protocol 105 elements is exactly the same as described in Section 2.1 of [HTTP]. 106 Since this augmented BNF uses the basic production rules provided in 107 Section 2.2 of [HTTP], these rules apply to this document as well. 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 111 document are to be interpreted as described in [RFC2119]. 113 2 Introduction 115 This specification builds on the collection infrastructure provided by 116 the WebDAV Distributed Authoring Protocol, adding support for the 117 server-side ordering of collection members. 119 There are many scenarios where it is useful to impose an ordering on a 120 collection at the server, such as expressing a recommended access order, 121 or a revision history order. The members of a collection might 122 represent the pages of a book, which need to be presented in order if 123 they are to make sense. Or an instructor might create a collection of 124 course readings, which she wants to be displayed in the order they are 125 to be read. 127 Orderings may be based on property values, but this is not always the 128 case. The resources in the collection may not have properties that can 129 be used to support the desired ordering. Orderings based on properties 130 can be obtained using a search protocol's ordering option, but orderings 131 not based on properties cannot. These orderings generally need to be 132 maintained by a human user. 134 The ordering protocol defined here focuses on support for such human- 135 maintained orderings. Its protocol elements allow clients to specify 136 the position of each collection member in the collection's ordering, as 137 well as the semantics governing the ordering. The protocol is designed 138 to allow support to be added in the future for orderings that are 139 maintained automatically by the server. 141 The remainder of this document is structured as follows: Section 3 142 defines terminology that will be used throughout the specification. 143 Section 4 provides an overview of ordered collections. Section 5 144 describes how to create an ordered collection, and Section 6 discusses 145 how to set a member's position in the ordering of a collection. Section 146 7 explains how to change a collection ordering. Section 8 discusses 147 listing the members of an ordered collection. Sections 9 through 11 148 define the headers, properties, and XML elements needed to support 149 ordered collections. Section 12 describes capability discovery. 150 Sections 13 through 15 discuss security, internationalization, and IANA 151 considerations. The remaining sections provide supporting information. 153 3 Terminology 155 The terminology used here follows that in the WebDAV Distributed 156 Authoring Protocol specification [WebDAV]. Definitions of the terms 157 resource, Uniform Resource Identifier (URI), and Uniform Resource 158 Locator (URL) are provided in [URI]. 160 Ordered Collection 161 A collection for which the results from a PROPFIND request are 162 guaranteed to be in the order specified for that collection 164 Unordered Collection 165 A collection for which the client cannot depend on the 166 repeatability of the ordering of results from a PROPFIND request 168 Client-Maintained Ordering 169 An ordering of collection members that is maintained on the server 170 based on client requests specifying the position of each 171 collection member in the ordering 173 Server-Maintained Ordering 174 An ordering of collection members that is maintained automatically 175 by the server, based on a client's choice of ordering semantics 177 4 Overview of Ordered Collections 179 If a collection is unordered, the client cannot depend on the 180 repeatability of the ordering of results from a PROPFIND request. By 181 specifying an ordering for a collection, a client requires the server to 182 follow that ordering whenever it responds to a PROPFIND request on that 183 collection. 185 Server-side orderings may be client-maintained or server-maintained. 186 For client-maintained orderings, a client must specify the ordering 187 position of each of the collection's members, either when the member is 188 added to the collection (using the Position header) or later (using the 189 ORDERPATCH method). For server-maintained orderings, the server 190 automatically positions each of the collection's members according to 191 the ordering semantics. This specification supports only client- 192 maintained orderings, but is designed to allow future extension to 193 server-maintained orderings. 195 A collection that supports ordering is not required to be ordered. It 196 is up to the client to decide whether a given collection is ordered and, 197 if so, to specify the semantics to be used for ordering its members. 199 If a collection is ordered, each of its internal member URIs MUST be in 200 the ordering exactly once, and the ordering MUST NOT include any URI 201 that is not an internal member of the collection. The server is 202 responsible for enforcing these constraints on orderings. The server 203 MUST remove an internal member URI from the ordering when it is removed 204 from the collection. The server MUST an internal member URI to the 205 ordering when it is added to the collection. 207 Only one ordering can be attached to any collection. Multiple orderings 208 of the same resources can be achieved by creating multiple collections 209 referencing those resources, and attaching a different ordering to each 210 collection. 212 An ordering is considered to be part of the state of a collection 213 resource. Consequently, the ordering is the same no matter which URI is 214 used to access the collection and is protected by locks or access 215 control constraints on the collection. 217 5 Creating an Ordered Collection 219 5.1 Overview 221 When a collection is created, the client MAY request that it be ordered 222 and specify the semantics of the ordering by using the new Ordered 223 header (defined in Section 9.1) with a MKCOL request. 225 For collections that are ordered, the client SHOULD identify the 226 semantics of the ordering with a URI in the Ordered header, although the 227 client MAY simply set the header value to DAV:custom to indicate that 228 the collection is ordered but the semantics of the ordering are not 229 being advertised. Setting the value to a URI that identifies the 230 ordering semanticsprovides the information a human user or software 231 package needs to insert new collection members into the ordering 232 intelligently. Although the URI in the Ordered header MAY point to a 233 resource that contains a definition of the semantics of the ordering, 234 clients SHOULD NOT access that resource, in order to avoid overburdening 235 its server. A value of DAV:unordered in the Ordering header indicates 236 that the client wants the collection to be unordered. If the Ordered 237 header is not present, the collection will be unordered. 238 Every collection that supports ordering MUST have a DAV:orderingtype 239 property (defined in Section 10.1), which indicates whether the 240 collection is ordered and, if so, identifies the semantics of the 241 ordering. The server sets the initial value of this property based on 242 the value of the Ordering header in the MKCOL request, if any. If the 243 Ordered header is not present, the server sets the value to 244 DAV:unordered. An ordering-aware client interacting with an ordering- 245 unaware server (e.g., one that is implemented only according to 246 [WebDAV]) SHOULD assume that if a collection does not have the 247 DAV:orderingtype property, the collection is unordered. 249 5.2 Example: Creating an Ordered Collection 251 >> Request: 253 MKCOL /theNorth/ HTTP/1.1 254 Host: www.server.org 255 Ordered: 257 >> Response: 259 HTTP/1.1 201 Created 261 In this example a new, ordered collection was created. Its 262 DAV:orderingtype property has as its value the URI from the Ordered 263 header, http://www.server.org/orderings/compass.html. In this case, the 264 URI identifies the semantics governing a client-maintained ordering. As 265 new members are added to the collection, clients or end users can use 266 the semantics to determine where to position the new members in the 267 ordering. 269 6 Setting the Position of a Collection Member 271 6.1 Overview 273 When a new member is added to a collection with a client-maintained 274 ordering (for example, with PUT, MKREF, COPY, or MKCOL), its position in 275 the ordering can be set with the new Position header (defined in Section 276 9.2). The Position header allows the client to specify that an internal 277 member URI should be first in the collection's ordering, last in the 278 collection's ordering, immediately before some other internal member URI 279 in the collection's ordering, or immediately after some other internal 280 member URI in the collection's ordering. 282 If the Position request header is not used when adding a member to an 283 ordered collection, then: 285 o If the request is replacing an existing resource, the server MUST 286 preserve the present ordering. 288 o If the request is adding a new internal member URI to the collection, 289 the server MUST append the new member to the end of the ordering. 291 6.2 Status Codes 293 409 (Conflict): Several conditions may cause this response. The request 294 may specify a position that is before or after a URI that is not an 295 internal member URI of the collection, or before or after itself. The 296 request may attempt to specify the new member's position in an unordered 297 collection. 299 6.3 Examples: Setting the Position of a Collection Member 301 >> Request: 303 COPY /~whitehead/dav/spec08.html HTTP/1.1 304 Host: www.ics.uci.edu 305 Destination: http://www.xerox.com/~slein/dav/spec08.html 306 Position: after requirements.html 308 >> Response: 310 HTTP/1.1 201 Created 312 This request resulted in the creation of a new resource at 313 www.xerox.com/~slein/dav/spec08.html. The Position header in this 314 example caused the server to set its position in the ordering of the 315 /~slein/dav/ collection immediately after requirements.html. 317 >> Request: 319 MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 320 Host: www.ics.uci.edu 321 Destination: http://www.ics.uci.edu/~whitehead/dav/draft-webdav- 322 protocol-08.txt 323 Position: first 325 >> Response: 327 HTTP/1.1 409 Conflict 329 In this case, the server returned a 409 (Conflict) status code because 330 the /~whitehead/dav/ collection is an unordered collection. 331 Consequently, the server was unable to satisfy the Position header. 333 7 Changing a Collection Ordering 335 7.1 ORDERPATCH Method 336 The ORDERPATCH method is used to change the ordering semantics of a 337 collection or to change the order of the collection's members in the 338 ordering or both. 340 The ORDERPATCH method changes the ordering semantics of the collection 341 identified by the Request-URI, based on the value of DAV:orderingtype 342 submitted in the request entity body. 344 The ORDERPATCH method alters the ordering of internal member URIs in the 345 collection identified by the Request-URI, based on instructions in the 346 ordermember XML elements in the request entity body. The ordermember XML 347 elements identify the internal member URIs whose positions are to be 348 changed, and describe their new positions in the ordering. Each new 349 position can be specified as first in the ordering, last in the 350 ordering, immediately before some other internal member URI, or 351 immediately after some other internal member URI. 353 The server MUST apply the changes in the order they appear in the order 354 XML element. The server MUST either apply all the changes or apply none 355 of them. If any error occurs during processing, all executed changes 356 MUST be undone and a proper error result returned. 358 If an ORDERPATCH request changes the ordering semantics, but does not 359 completely specify the order of the collection members, the server MUST 360 assign a position in the ordering to each collection member for which a 361 position was not specified. These server-assigned positions MUST all 362 follow the last one specified by the client. The result is that all 363 members for which the client specified a position are at the beginning 364 of the ordering, followed by any members for which the server assigned 365 positions. 367 If an ORDERPATCH request does not change the ordering semantics, any 368 member positions not specified in the request MUST remain unchanged. 370 7.1.1 Status Codes 372 Since multiple changes can be requested in a single ORDERPATCH request, 373 if any problems are encountered, the server MUST return a 207 (Multi- 374 Status) response, as defined in [WebDAV]. 376 The following are examples of response codes one would expect to be used 377 in a 207 (Multi-Status) response for this method: 379 200 (OK): The change in ordering was successfully made. 381 409 (Conflict): Several conditions may cause this response. The request 382 may specify a position that is before or after a URI that is not an 383 internal member URI of the collection, or before or after itself. The 384 request may attempt to set the positions of members of an unordered 385 collection. 387 A request to reposition a collection member at the same place in the 388 ordering is not an error. 390 7.1.2 Example: Changing a Collection Ordering 391 Consider a collection /coll-1/ whose DAV:orderingtype is DAV:whim, with 392 bindings ordered as follows: 394 three.html 395 four.html 396 one.html 397 two.html 399 >> Request: 401 ORDERPATCH /coll-1/ HTTP/1.1 402 Host: www.myserver.com 403 Content-Type: text/xml 404 Content-Length: xxx 406 407 408 409 http://www.myserver.com/inorder.ord 410 411 412 two.html 413 414 415 416 417 418 one.html 419 420 421 422 423 424 three.html 425 426 427 428 429 430 four.html 431 432 433 434 435 437 >> Response: 439 HTTP/1.1 200 OK 441 In this example, after the request has been processed, the collection's 442 ordering semantics are identified by the URI 443 http://www.myserver.com/inorder.ord. The value of the collection's 444 DAV:orderingtype property has been set to this URI. The request also 445 contains instructions for changing the positions of the collection's 446 internal member URIs in the ordering to comply with the new ordering 447 semantics. If href elements are relative URIs, as in this example, they 448 are interpreted relative to the collection whose ordering is being 449 modified. The DAV:ordermember elements are required to be processed in 450 the order they appear in the request. Consequently, two.html is moved 451 to the beginning of the ordering, and then one.html is moved to the 452 beginning of the ordering. Then three.html is moved to the end of the 453 ordering, and finally four.html is moved to the end of the ordering. 454 After the request has been processed, the collection's ordering is as 455 follows: 457 one.html 458 two.html 459 three.html 460 four.html 462 7.1.3 Example: Failure of an ORDERPATCH Request 464 Consider a collection /coll-1/ with members ordered as follows: 466 nunavut.map 467 nunavut.img 468 baffin.map 469 baffin.desc 470 baffin.img 471 iqaluit.map 472 nunavut.desc 473 iqaluit.img 474 iqaluit.desc 476 >> Request: 478 ORDERPATCH /coll-1/ HTTP/1.1 479 Host: www.nunanet.com 480 Content-Type: text/xml 481 Content-Length: xxx 483 484 485 486 nunavut.desc 487 488 489 nunavut.map 490 491 492 493 494 iqaluit.map 495 496 497 pangnirtung.img 498 499 501 502 504 >> Response: 506 HTTP/1.1 207 Multi-Status 507 Content-Type: text/xml 508 Content-Length: xxx 510 511 512 513 http://www.nunanet.com/coll-1/nunavut.desc 514 HTTP/1.1 424 Failed Dependency 515 516 517 http://www.nunanet.com/coll-1/iqaluit.map 518 HTTP/1.1 409 Conflict 519 pangnirtung.img is not a collection 520 member. 521 522 524 In this example, the client attempted to position iqaluit.map after a 525 URI that is not an internal member of the collection /coll-1/. The 526 server responded to this client error with a 409 (Conflict) status code. 527 Because ORDERPATCH is an atomic method, the request to reposition 528 nunavut.desc (which would otherwise have succeeded) failed with a 424 529 (Failed Dependency) status code. 531 8 Listing the Members of an Ordered Collection 533 A PROPFIND request is used to retrieve a listing of the members of an 534 ordered collection, just as it is used to retrieve a listing of the 535 members of an unordered collection. 537 However, when responding to a PROPFIND on an ordered collection, the 538 server MUST order the response elements according to the ordering 539 defined on the collection. If a collection is unordered, the client 540 cannot depend on the repeatability of the ordering of results from a 541 PROPFIND request. 543 In a response to a PROPFIND with Depth: infinity, members of different 544 collections may be interleaved. That is, the server is not required to 545 do a breadth-first traversal. The only requirement is that the members 546 of any ordered collection appear in the order defined for the 547 collection. Thus for the hierarchy illustrated in the following figure, 548 where collection A is an ordered collection with the ordering B C D, 550 A 551 /|\ 552 / | \ 553 B C D 554 / /|\ 555 E F G H 557 it would be acceptable for the server to return response elements in the 558 order A B E C F G H D. In this response, B, C, and D appear in the 559 correct order, separated by members of other collections. Clients can 560 use a series of Depth: 1 PROPFIND requests to avoid the complexity of 561 processing Depth: infinity responses based on depth-first traversals. 563 8.1 Example: PROPFIND on an Ordered Collection 565 Suppose a PROPFIND request is submitted to /MyCollection/, which has its 566 members ordered as follows. 568 /MyCollection/ 569 lakehazen.html 570 siorapaluk.html 571 iqaluit.html 572 newyork.html 574 >> Request: 576 PROPFIND /MyCollection/ HTTP/1.1 577 Host: www.svr.com 578 Depth: 1 579 Content-Type: text/xml 580 Content-Length: xxxx 582 583 584 585 586 587 588 590 >> Response: 592 HTTP/1.1 207 Multi-Status 593 Content-Type: text/xml 594 Content-Length: xxxx 596 597 599 600 http://www.svr.com/MyCollection/ 601 602 603 604 605 HTTP/1.1 200 OK 606 607 608 609 611 612 HTTP/1.1 404 Not Found 613 614 615 616 http://www.svr.com/MyCollection/lakehazen.html 617 618 619 620 82N 621 622 HTTP/1.1 200 OK 623 624 625 626 http://www.svr.com/MyCollection/siorapaluk.html 627 628 629 630 78N 631 632 HTTP/1.1 200 OK 633 634 635 636 http://www.svr.com/MyCollection/iqaluit.html 637 638 639 640 62N 641 642 HTTP/1.1 200 OK 643 644 645 646 http://www.svr.com/MyCollection/newyork.html 647 648 649 650 45N 651 652 HTTP/1.1 200 OK 653 654 655 657 In this example, the server responded with a list of the collection 658 members in the order defined for the collection. 660 9 Headers 662 9.1 Ordered Entity Header 664 Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) 665 The Ordered header may be used with MKCOL to request that the new 666 collection be ordered and to specify its ordering semantics. A value of 667 "DAV:unordered" indicates that the collection is not ordered. A value of 668 "DAV:custom" indicates that the collection is to be ordered, but the 669 semantics of the ordering is not being advertised. Any other Coded-url 670 value indicates that the collection is ordered, and identifies the 671 semantics of the ordering. 673 9.2 Position Request Header 675 Position = "Position" ":" ("first" | "last" | 676 (("before" | "after") segment)) 677 segment is defined in Section 3.3 of [URI]. 679 The Position header may be used with any method that adds a member to an 680 ordered collection, to tell the server where in the collection ordering 681 to position the new member being added to the collection. Examples of 682 methods that add members to collections are BIND, PUT, COPY, MOVE, etc. 684 The segment is interpreted relative to the collection to which the new 685 member is being added. 687 The server MUST insert the new member into the ordering at the location 688 specified in the Position header, if one is present (and if the 689 collection is ordered). 691 The "first" keyword indicates the new member is put in the beginning 692 position in the collection's ordering, while "last" indicates the new 693 member is put in the final position in the collection's ordering. The 694 "before" keyword indicates the new member is added to the collection's 695 ordering immediately prior to the position of the member identified in 696 the segment. Likewise, the "after" keyword indicates the new member is 697 added to the collection's ordering immediately following the position of 698 the member identified in the segment. 700 If the request is replacing an existing resource, and the Position 701 header is present, the server MUST remove the internal member URI from 702 its previous position, and then insert it at the requested position. 704 If an attempt is made to use the Position header on a collection that is 705 unordered, the server MUST fail the request with a 409 (Conflict) status 706 code. 708 10 Properties 710 10.1 orderingtype Property 712 Name: orderingtype 713 Namespace: DAV: 714 Purpose: Indicates whether the collection is ordered and, if so, 715 uniquely identifies the semantics of the ordering being 716 used. May also point to an explanation of the semantics in 717 human and / or machine-readable form. At a minimum, this 718 allows human users who add members to the collection to 719 understand where to position them in the ordering. This 720 property cannot be set using PROPPATCH. Its value can only 721 be set by including the Ordered header with a MKCOL request 722 or by submitting an ORDERPATCH request. 723 Value: The value unordered indicates that the collection is not 724 ordered. The value custom indicates that the collection is 725 ordered, but the semantics governing the ordering are not 726 being advertised. If the value is an href element, it 727 contains a URI that uniquely identifies the semantics of the 728 collection's ordering. 730 732 11 XML Elements 734 11.1 unordered XML Element 736 Name: unordered 737 Namespace: DAV: 738 Purpose: A value of the DAV:orderingtype property that indicates that 739 the collection is not ordered. That is, the client cannot 740 depend on the repeatability of the ordering of results from 741 a PROPFIND request. 743 745 11.2 custom XML Element 747 Name: custom 748 Namespace: DAV: 749 Purpose: A value of the DAV:orderingtype property that indicates that 750 the collection is ordered, but the semantics of the ordering 751 are not being advertised. 753 755 11.3 order XML Element 757 Name: order 758 Namespace: DAV: 759 Purpose: For use with the new ORDERPATCH method. Describes a change 760 to be made in a collection's ordering semantics or in the 761 positions of its members in the ordering or both. 762 Value: An optional identifier of an ordering semantics for the 763 collection, followed by a list of changes to be made in the 764 positions of the members in the collection's ordering. 766 768 11.4 ordermember XML Element 770 Name: ordermember 771 Namespace: DAV: 772 Purpose: Occurs in the order XML element, and describes the new 773 position of a single internal member URI in the collection's 774 ordering. 776 Value: An href containing a member's path segment, and a 777 description of its new position in the ordering. The href 778 XML element is defined in [WebDAV], Section 11.3. 780 782 11.5 position XML Element 784 Name: position 785 Namespace: DAV: 786 Purpose: Occurs in the ordermember XML element. Describes the new 787 position in a collection's ordering of one of the members it 788 contains. 789 Value: The new position can be described as first in the 790 collection's ordering, last in the collection's ordering, 791 immediately before some other collection member, or 792 immediately after some other collection member. 794 796 11.6 first XML Element 798 Name: first 799 Namespace: DAV: 800 Purpose: Occurs in the position XML element. Specifies that the 801 member should be placed first in the collection's ordering. 803 805 11.7 last XML Element 807 Name: last 808 Namespace: DAV: 809 Purpose: Occurs in the position XML element. Specifies that the 810 member should be placed last in the collection's ordering. 812 814 11.8 before XML Element 816 Name: before 817 Namespace: DAV: 818 Purpose: Occurs in the position XML element. Specifies that the 819 member should be placed immediately before the member in the 820 enclosed segment XML element in the collection's ordering. 821 Value: URI (relative to the parent collection) of the member 822 it precedes in the ordering 824 826 11.9 after XML Element 828 Name: after 829 Namespace: DAV: 830 Purpose: Occurs in the position XML element. Specifies that the 831 member should be placed immediately after the member in the 832 enclosed segment XML element in the collection's ordering. 833 Value: URI (relative to the parent collection) of the member 834 it follows in the ordering 836 838 11.10 segment XML Element 840 Name: segment 841 Namespace: DAV: 842 Purpose: Identifies a member of a collection, used in the DAV:before 843 and DAV:after elements, to define one member's position in 844 a collection ordering relative to another member of the 845 collection. 846 Value: segment ; as defined in section 3.3 of [URI]. 848 850 12 Capability Discovery 852 Sections 9.1 and 15 of [WebDAV] describe the use of compliance classes 853 with the DAV header in responses to OPTIONS, to indicate which parts of 854 the Web Distributed Authoring protocols the resource supports. This 855 specification defines an OPTIONAL extension to [WebDAV]. It defines a 856 new compliance class, called orderedcoll, for use with the DAV header in 857 responses to OPTIONS requests. If a collection resource does support 858 ordering, its response to an OPTIONS request may indicate that it does, 859 by listing the new ORDERPATCH method as one it supports, and by listing 860 the new orderedcoll compliance class in the DAV header. 862 When responding to an OPTIONS request, only a collection or a null 863 resource can include orderedcoll in the value of the DAV header. By 864 including orderedcoll, the resource indicates that its internal member 865 URIs can be ordered. It implies nothing about whether any collections 866 identified by its internal member URIs can be ordered. 868 12.1 Example: Discovery of Support for Ordering 870 >> Request: 872 OPTIONS /somecollection/ HTTP/1.1 873 HOST: somehost.org 875 >> Response: 877 HTTP/1.1 200 OK 878 Date: Tue, 20 Jan 1998 20:52:29 GMT 879 Connection: close 880 Accept-Ranges: none 881 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 882 PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH 883 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 884 PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH 885 DAV: 1, 2, orderedcoll 886 The DAV header in the response indicates that the resource 887 /somecollection/ is level 1 and level 2 compliant, as defined in 888 [WebDAV]. In addition, /somecollection/ supports ordering. The Allow 889 header indicates that ORDERPATCH requests can be submitted to 890 /somecollection/. The Public header shows that other Request-URIs on 891 the server support additional methods. 893 13 Security Considerations 895 This section is provided to make WebDAV applications aware of the 896 security implications of this protocol. 898 All of the security considerations of HTTP/1.1 and the WebDAV 899 Distributed Authoring Protocol specification also apply to this protocol 900 specification. In addition, ordered collections introduce a new 901 security concern. This issue is detailed here. 903 13.1 Denial of Service and DAV:orderingtype 905 There may be some risk of denial of service at sites that are advertised 906 in the DAV:orderingtype property of collections. However, it is 907 anticipated that widely-deployed applications will use hard-coded values 908 for frequently-used ordering semantics rather than looking up the 909 semantics at the location specified by DAV:orderingtype. This risk will 910 be further reduced if clients observe the recommendation of Section 5.1 911 that they not send requests to the URI in DAV:orderingtype. 913 14 Internationalization Considerations 915 This specification follows the practices of [WebDAV] in encoding all 916 human-readable content using XML [XML] and in the treatment of names. 917 Consequently, this specification complies with the IETF Character Set 918 Policy [RFC2277]. 920 WebDAV applications MUST support the character set tagging, character 921 set encoding, and the language tagging functionality of the XML 922 specification. This constraint ensures that the human-readable content 923 of this specification complies with [RFC2277]. 925 As in [WebDAV}, names in this specification fall into three categories: 926 names of protocol elements such as methods and headers, names of XML 927 elements, and names of properties. Naming of protocol elements follows 928 the precedent of HTTP, using English names encoded in USASCII for 929 methods and headers. The names of XML elements used in this 930 specification are English names encoded in UTF-8. 932 For error reporting, [WebDAV] follows the convention of HTTP/1.1 status 933 codes, including with each status code a short, English description of 934 the code (e.g., 423 Locked). Internationalized applications will ignore 935 this message, and display an appropriate message in the user's language 936 and character set. 938 This specification introduces no new strings that are displayed to users 939 as part of normal, error-free operation of the protocol. 941 For rationales for these decisions and advice for application 942 implementors, see [WebDAV]. 944 15 IANA Considerations 946 This document uses the namespaces defined by [WebDAV] for properties and 947 XML elements. All other IANA considerations mentioned in [WebDAV] also 948 apply to this document. 950 16 Copyright 952 To be supplied by the RFC Editor. 954 17 Intellectual Property 956 To be supplied by the RFC Editor. 958 18 Acknowledgements 960 This draft has benefited from thoughtful discussion by Jim Amsden, Steve 961 Carter, Tyson Chihaya, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer 962 Dawkins, Mark Day, Rajiv Dulepet, David Durand, Roy Fielding, Yaron 963 Goland, Fred Hitt, Alex Hopmann, Marcus Jager, Chris Kaler, Manoj 964 Kasichainula, Rohit Khare, Daniel LaLiberte, Lisa Lippert, Steve Martin, 965 Larry Masinter, Jeff McAffer, Surendra Koduru Reddy, Max Rible, Sam 966 Ruby, Bradley Sergeant, Nick Shelness, John Stracke, John Tigue, John 967 Turner, Kevin Wiggen, and others. 969 19 References 971 [RFC2277] H.T. Alvestrand, "IETF Policy on Character Sets and 972 Languages." RFC 2277, BCP 18. Uninett. January, 1998. 974 [URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource 975 Identifiers (URI): Generic Syntax." RFC 2396. MIT/LCS, U.C. Irvine, 976 Xerox. August, 1998. 978 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement 979 Levels." RFC 2119, BCP 14. Harvard University. March, 1997. 981 [XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup 982 Language (XML)." World Wide Web Consortium Recommendation REC-xml- 983 19980210. http://www.w3.org/TR/1998/REC-xml-19980210. 985 [HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. 986 Leach, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC 987 2616. UC Irvine, Compaq, W3C, Xerox, Microsoft. June, 1999. 989 [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. 990 Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." RFC 2518. 991 Microsoft, U.C. Irvine, Netscape, Novell. February, 1999. 993 20 Authors' Addresses 994 J. Slein 995 Xerox Corporation 996 800 Phillips Road, 105-50C 997 Webster, NY 14580 998 Email: jslein@crt.xerox.com 1000 E. J. Whitehead, Jr. 1001 Dept. of Information and Computer Science 1002 University of California, Irvine 1003 Irvine, CA 92697-3425 1004 Email: ejw@ics.uci.edu 1006 J. Davis 1007 CourseNet Systems 1008 170 Capp Street 1009 San Francisco, CA 94110 1010 Email: jrd3@alum.mit.edu 1012 G. Clemm 1013 Rational Software Corporation 1014 20 Maguire Road 1015 Lexington, MA 02173-3104 1016 Email: gclemm@rational.com 1018 C. Fay 1019 FileNet Corporation 1020 3565 Harbor Boulevard 1021 Costa Mesa, CA 92626-1420 1022 Email: cfay@filenet.com 1024 J. Crawford 1025 IBM Research 1026 P.O. Box 704 1027 Yorktown Heights, NY 10598 1028 Email: ccjason@us.ibm.com 1030 21 Appendices 1032 21.1 Appendix 1: Extensions to the WebDAV Document Type Definition 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1048 Expires June 20, 2000