idnits 2.17.1
draft-ietf-webdav-ordering-protocol-07.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 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 (March 2003) is 7706 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: 5 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: September 2003 J. Whitehead
5 U.C. Santa Cruz
6 J. Crawford
7 IBM
8 J. F. Reschke
9 greenbytes
10 March 2003
12 WebDAV Ordered Collections Protocol
13 draft-ietf-webdav-ordering-protocol-07
15 Status of this Memo
17 This document is an Internet-Draft and is in full conformance with
18 all provisions of Section 10 of RFC2026. Internet-Drafts are working
19 documents of the Internet Engineering Task Force (IETF), its areas,
20 and its working groups. Note that other groups may also distribute
21 working documents as Internet-Drafts.
23 Internet-Drafts are draft documents valid for a maximum of six months
24 and may be updated, replaced, or obsoleted by other documents at any
25 time. It is inappropriate to use Internet-Drafts as reference
26 material or to cite them other than as "work in progress".
28 The list of current Internet-Drafts can be accessed at
29 http://www.ietf.org/ietf/1id-abstracts.txt.
31 The list of Internet-Draft Shadow Directories can be accessed at
32 http://www.ietf.org/shadow.html.
34 This Internet-Draft will expire in September 2003.
36 Copyright Notice
38 Copyright (C) The Internet Society (2003). All Rights Reserved.
40 Abstract
42 This specification extends the WebDAV Distributed Authoring Protocol
43 to support server-side ordering of collection members. Of particular
44 interest are orderings that are not based on property values, and so
45 cannot be achieved using a search protocol's ordering option and
46 cannot be maintained automatically by the server. Protocol elements
47 are defined to let clients specify the position in the ordering of
48 each collection member, as well as the semantics governing the
49 ordering.
51 Distribution of this document is unlimited. Please send comments to
52 the Distributed Authoring and Versioning (WebDAV) working group at
53 w3c-dist-auth@w3.org, which may be joined by sending a message with
54 subject "subscribe" to w3c-dist-auth-request@w3.org.
56 Discussions of the WEBDAV working group are archived at URL:
57 http://lists.w3.org/Archives/Public/w3c-dist-auth/.
59 Table of Contents
61 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
62 Table of Contents . . . . . . . . . . . . . . . . . . . . . . 3
63 1 Notational Conventions . . . . . . . . . . . . . . . . . . . 5
64 2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
65 3 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 7
66 4 Overview of Ordered Collections . . . . . . . . . . . . . . 8
67 4.1 Additional Collection properties . . . . . . . . . . . . 8
68 4.1.1 DAV:ordering-type (protected) . . . . . . . . . . . 9
69 5 Creating an Ordered Collection . . . . . . . . . . . . . . . 10
70 5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 10
71 5.2 Example: Creating an Ordered Collection . . . . . . . . 11
72 6 Setting the Position of a Collection Member . . . . . . . . 12
73 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 12
74 6.2 Examples: Setting the Position of a Collection Member . 13
75 7 Changing a Collection Ordering: ORDERPATCH method . . . . . 15
76 7.1 Example: Changing a Collection Ordering . . . . . . . . 17
77 7.2 Example: Failure of an ORDERPATCH Request . . . . . . . 18
78 8 Listing the Members of an Ordered Collection . . . . . . . . 21
79 8.1 Example: PROPFIND on an Ordered Collection . . . . . . . 21
80 9 Relationship to versioned collections . . . . . . . . . . . 25
81 9.1 Collection Version Properties . . . . . . . . . . . . . 25
82 9.1.1 Additional semantics for DAV:version-controlled-
83 binding-set (protected) . . . . . . . . . . . . . . . . . . . 25
84 9.1.2 DAV:ordering-type (protected) . . . . . . . . . . . 25
85 9.2 Additional CHECKIN semantics . . . . . . . . . . . . . . 25
86 9.3 Additional CHECKOUT Semantics . . . . . . . . . . . . . 26
87 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics . . 26
88 10 Capability Discovery . . . . . . . . . . . . . . . . . . . 27
89 10.1 Example: Using OPTIONS for the Discovery of Support for
90 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
91 10.2 Example: Using Live Properties for the Discovery of
92 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
93 11 Security Considerations . . . . . . . . . . . . . . . . . . 30
94 11.1 Denial of Service and DAV:ordering-type . . . . . . . . 30
95 12 Internationalization Considerations . . . . . . . . . . . . 31
96 13 IANA Considerations . . . . . . . . . . . . . . . . . . . . 32
97 14 Copyright . . . . . . . . . . . . . . . . . . . . . . . . . 33
98 15 Intellectual Property . . . . . . . . . . . . . . . . . . . 34
99 16 Acknowledgements . . . . . . . . . . . . . . . . . . . . . 35
100 Normative References . . . . . . . . . . . . . . . . . . . . . 36
101 Author's Addresses . . . . . . . . . . . . . . . . . . . . . . 36
102 A Extensions to the WebDAV Document Type Definition . . . . . 38
103 B Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 39
104 B.1 Since draft-ietf-webdav-ordering-protocol dated December
105 1999 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
106 B.2 Since draft-ietf-webdav-ordering-protocol-02 . . . . . . 39
107 B.3 Since draft-ietf-webdav-ordering-protocol-03 . . . . . . 39
108 B.4 Since draft-ietf-webdav-ordering-protocol-04 . . . . . . 40
109 B.5 Since draft-ietf-webdav-ordering-protocol-05 . . . . . . 40
110 B.6 Since draft-ietf-webdav-ordering-protocol-06 . . . . . . 40
111 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
113 1 Notational Conventions
115 Since this document describes a set of extensions to the WebDAV
116 Distributed Authoring Protocol [RFC2518], itself an extension to the
117 HTTP/1.1 protocol, the augmented BNF used here to describe protocol
118 elements is exactly the same as described in Section 2.1 of HTTP
119 [RFC2616]. Since this augmented BNF uses the basic production rules
120 provided in Section 2.2 of HTTP, these rules apply to this document
121 as well.
123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
125 document are to be interpreted as described in [RFC2119].
127 This document uses XML DTD fragments as a purely notational
128 convention. WebDAV request and response bodies can not be validated
129 due to the specific extensibility rules defined in section 23 of
130 [RFC2518] and due to the fact that all XML elements defined by this
131 specification use the XML namespace name "DAV:". In particular:
133 1. element names use the "DAV:" namespace,
135 2. element ordering is irrelevant,
137 3. extension elements (elements not already defined as valid child
138 elements) may be added anywhere, except when explicitly stated
139 otherwise,
141 4. extension attributes (attributes not already defined as valid for
142 this element) may be added anywhere, except when explicitly stated
143 otherwise.
145 2 Introduction
147 This specification builds on the collection infrastructure provided
148 by the WebDAV Distributed Authoring Protocol, adding support for the
149 server-side ordering of collection members.
151 There are many scenarios where it is useful to impose an ordering on
152 a collection at the server, such as expressing a recommended access
153 order, or a revision history order. The members of a collection might
154 represent the pages of a book, which need to be presented in order if
155 they are to make sense. Or an instructor might create a collection of
156 course readings, which she wants to be displayed in the order they
157 are to be read.
159 Orderings may be based on property values, but this is not always the
160 case. The resources in the collection may not have properties that
161 can be used to support the desired ordering. Orderings based on
162 properties can be obtained using a search protocol's ordering option,
163 but orderings not based on properties cannot. These orderings
164 generally need to be maintained by a human user.
166 The ordering protocol defined here focuses on support for such human-
167 maintained orderings. Its protocol elements allow clients to specify
168 the position of each collection member in the collection's ordering,
169 as well as the semantics governing the ordering. The protocol is
170 designed to allow support to be added in the future for orderings
171 that are maintained automatically by the server.
173 The remainder of this document is structured as follows: section 3
174 defines terminology that will be used throughout the specification.
175 Section 4 provides an overview of ordered collections. Section 5
176 describes how to create an ordered collection, and section 6
177 discusses how to set a member's position in the ordering of a
178 collection. Section 7 explains how to change a collection ordering.
179 Section 8 discusses listing the members of an ordered collection.
180 Section 9 discusses the impact on version-controlled collections (as
181 defined in [RFC3253]. Section 10 describes capability discovery.
182 Section 11 through section 13 discuss security, internationalization,
183 and IANA considerations. The remaining sections provide supporting
184 information.
186 3 Terminology
188 The terminology used here follows that in [RFC2518] and [RFC3253].
189 Definitions of the terms resource, Uniform Resource Identifier (URI),
190 and Uniform Resource Locator (URL) are provided in [RFC2396].
192 Ordered Collection
194 A collection for which the results from a PROPFIND request are
195 guaranteed to be in the order specified for that collection
197 Unordered Collection
199 A collection for which the client cannot depend on the
200 repeatability of the ordering of results from a PROPFIND request
202 Client-Maintained Ordering
204 An ordering of collection members that is maintained on the server
205 based on client requests specifying the position of each
206 collection member in the ordering
208 Server-Maintained Ordering
210 An ordering of collection members that is maintained automatically
211 by the server, based on a client's choice of ordering semantics
213 This document uses the terms "precondition", "postcondition" and
214 "protected property" as defined in [RFC3253]. Servers MUST report
215 pre-/postcondition failures as described in section 1.6 of this
216 document.
218 4 Overview of Ordered Collections
220 If a collection is unordered, the client cannot depend on the
221 repeatability of the ordering of results from a PROPFIND request. By
222 specifying an ordering for a collection, a client requires the server
223 to follow that ordering whenever it responds to a PROPFIND request on
224 that collection.
226 Server-side orderings may be client-maintained or server-maintained.
227 For client-maintained orderings, a client must specify the ordering
228 position of each of the collection's members, either when the member
229 is added to the collection (using the Position header) or later
230 (using the ORDERPATCH method). For server-maintained orderings, the
231 server automatically positions each of the collection's members
232 according to the ordering semantics. This specification supports only
233 client-maintained orderings, but is designed to allow future
234 extension to server-maintained orderings.
236 A collection that supports ordering is not required to be ordered.
238 If a collection is ordered, each of its internal member URIs MUST be
239 in the ordering exactly once, and the ordering MUST NOT include any
240 URI that is not an internal member of the collection. The server is
241 responsible for enforcing these constraints on orderings. The server
242 MUST remove an internal member URI from the ordering when it is
243 removed from the collection. The server MUST add an internal member
244 URI to the ordering when it is added to the collection.
246 Only one ordering can be attached to any collection. Multiple
247 orderings of the same resources can be achieved by creating multiple
248 collections referencing those resources, and attaching a different
249 ordering to each collection.
251 An ordering is considered to be part of the state of a collection
252 resource. Consequently, the ordering is the same no matter which URI
253 is used to access the collection and is protected by locks or access
254 control constraints on the collection.
256 4.1 Additional Collection properties
258 A DAV:allprop PROPFIND request SHOULD NOT return any of the
259 properties defined in this document.
261 4.1.1 DAV:ordering-type (protected)
263 Indicates whether the collection is ordered and, if so, uniquely
264 identifies the semantics of the ordering being used. May also point
265 to an explanation of the semantics in human and / or machine-readable
266 form. At a minimum, this allows human users who add members to the
267 collection to understand where to position them in the ordering. This
268 property cannot be set using PROPPATCH. Its value can only be set by
269 including the Ordering-Type header with a MKCOL request or by
270 submitting an ORDERPATCH request.
272 Ordering types are identified by URIs that uniquely identify the
273 semantics of the collection's ordering. The following two URIs are
274 predefined:
276 DAV:custom The value DAV:custom indicates that the collection is
277 ordered, but the semantics governing the ordering are
278 not being advertised.
279 DAV:unordered The value DAV:unordered indicates that the collection
280 is not ordered. That is, the client cannot depend on
281 the repeatability of the ordering of results from a
282 PROPFIND request.
284 An ordering-aware client interacting with an ordering-unaware server
285 (e.g., one that is implemented only according to [RFC2518]) SHOULD
286 assume that if a collection does not have the DAV:ordering-type
287 property, the collection is unordered.
289
291 5 Creating an Ordered Collection
293 5.1 Overview
295 When a collection is created, the client MAY request that it be
296 ordered and specify the semantics of the ordering by using the new
297 Ordering-Type header (defined below) with a MKCOL request.
299 For collections that are ordered, the client SHOULD identify the
300 semantics of the ordering with a URI in the Ordering-Type header,
301 although the client MAY simply set the header value to DAV:custom to
302 indicate that the collection is ordered but the semantics of the
303 ordering are not being advertised. Setting the value to a URI that
304 identifies the ordering semantics provides the information a human
305 user or software package needs to insert new collection members into
306 the ordering intelligently. Although the URI in the Ordering-Type
307 header MAY point to a resource that contains a definition of the
308 semantics of the ordering, clients SHOULD NOT access that resource,
309 in order to avoid overburdening its server. A value of DAV:unordered
310 in the Ordering-Type header indicates that the client wants the
311 collection to be unordered. If the Ordering-Type header is not
312 present, the collection will be unordered.
314 Additional Marshalling:
316 Ordering-Type = "Ordering-Type" ":" absoluteURI
317 ; absoluteURI: see RFC2396, section 3
319 The URI "DAV:unordered" indicates that the collection is not
320 ordered, while "DAV:custom" indicates that the collection is to be
321 ordered, but the semantics of the ordering is not being
322 advertised. Any other URI value indicates that the collection is
323 ordered, and identifies the semantics of the ordering.
325 Additional Preconditions:
327 (DAV:ordered-collections-supported): the server MUST support
328 ordered collections in the part of the URL namespace identified by
329 the request URL.
331 Additional Postconditions:
333 (DAV:ordering-type-set): if the Ordering-Type header was present,
334 the request MUST have created a new collection resource with the
335 DAV:ordering-type being set according to the Ordering-Type request
336 header. The collection MUST be ordered unless the ordering type
337 was "DAV:unordered".
339 5.2 Example: Creating an Ordered Collection
341 >> Request:
343 MKCOL /theNorth/ HTTP/1.1
344 Host: example.org
345 Ordering-Type: http://example.org/orderings/compass.html
347 >> Response:
349 HTTP/1.1 201 Created
351 In this example a new, ordered collection was created. Its
352 DAV:ordering-type property has as its value the URI from the
353 Ordering-Type header, http://example.org/orderings/compass.html. In
354 this case, the URI identifies the semantics governing a client-
355 maintained ordering. As new members are added to the collection,
356 clients or end users can use the semantics to determine where to
357 position the new members in the ordering.
359 6 Setting the Position of a Collection Member
361 6.1 Overview
363 When a new member is added to a collection with a client-maintained
364 ordering (for example, with PUT, COPY, or MKCOL), its position in the
365 ordering can be set with the new Position header. The Position header
366 allows the client to specify that an internal member URI should be
367 first in the collection's ordering, last in the collection's
368 ordering, immediately before some other internal member URI in the
369 collection's ordering, or immediately after some other internal
370 member URI in the collection's ordering.
372 If the Position request header is not used when adding a member to an
373 ordered collection, then:
375 o If the request is replacing an existing resource, the server MUST
376 preserve the present ordering.
378 o If the request is adding a new internal member URI to the
379 collection, the server MUST append the new member to the end of
380 the ordering.
382 Additional Marshalling:
384 Position = "Position" ":" ("first" | "last" |
385 (("before" | "after") segment))
387 segment is defined in Section 3.3 of [RFC2396].
389 The segment is interpreted relative to the collection to which the
390 new member is being added.
392 When the Position header is present, the server MUST insert the
393 new member into the ordering at the specified location.
395 The "first" keyword indicates the new member is put in the
396 beginning position in the collection's ordering, while "last"
397 indicates the new member is put in the final position in the
398 collection's ordering. The "before" keyword indicates the new
399 member is added to the collection's ordering immediately prior to
400 the position of the member identified in the segment. Likewise,
401 the "after" keyword indicates the new member is added to the
402 collection's ordering immediately following the position of the
403 member identified in the segment.
405 If the request is replacing an existing resource, and the Position
406 header is present, the server MUST remove the internal member URI
407 from its previous position, and then insert it at the requested
408 position.
410 Additional Preconditions:
412 (DAV:collection-must-be-ordered): the target collection MUST be
413 ordered.
415 (DAV:segment-must-identify-member): the referenced segment MUST
416 identify a resource that exists and is different from the affected
417 resource.
419 Additional Postconditions:
421 (DAV:position-set): if a Position header was present, the request
422 MUST have created the new collection member at the specified
423 position.
425 6.2 Examples: Setting the Position of a Collection Member
427 >> Request:
429 COPY /~user/dav/spec08.html HTTP/1.1
430 Host: example.org
431 Destination: http://example.org/~slein/dav/spec08.html
432 Position: after requirements.html
434 >> Response:
436 HTTP/1.1 201 Created
437 This request resulted in the creation of a new resource at
438 example.org/~slein/dav/spec08.html. The Position header in this
439 example caused the server to set its position in the ordering of the
440 /~slein/dav/ collection immediately after requirements.html.
442 >> Request:
444 MOVE /i-d/draft-webdav-prot-08.txt HTTP/1.1
445 Host: example.org
446 Destination: http://example.org/~user/dav/draft-webdav-prot-08.txt
447 Position: first
449 >> Response:
451 HTTP/1.1 409 Conflict
452 Content-Type: text/xml; charset="utf-8"
453 Content-Length: xxxx
455
456
457
458
460 In this case, the server returned a 409 (Conflict) status code
461 because the /~user/dav/ collection is an unordered collection.
462 Consequently, the server was unable to satisfy the Position header.
464 7 Changing a Collection Ordering: ORDERPATCH method
466 The ORDERPATCH method is used to change the ordering semantics of a
467 collection or to change the order of the collection's members in the
468 ordering or both.
470 The server MUST apply the changes in the order they appear in the
471 order XML element. The server MUST either apply all the changes or
472 apply none of them. If any error occurs during processing, all
473 executed changes MUST be undone and a proper error result returned.
475 If an ORDERPATCH request changes the ordering semantics, but does not
476 completely specify the order of the collection members, the server
477 MUST assign a position in the ordering to each collection member for
478 which a position was not specified. These server-assigned positions
479 MUST all follow the last one specified by the client. The result is
480 that all members for which the client specified a position are at the
481 beginning of the ordering, followed by any members for which the
482 server assigned positions.
484 If an ORDERPATCH request does not change the ordering semantics, any
485 member positions not specified in the request MUST remain unchanged.
487 A request to reposition a collection member at the same place in the
488 ordering is not an error.
490 If an ORDERPATCH request fails, the server state preceding the
491 request MUST be restored.
493 Additional Marshalling:
495 The request body MUST be DAV:orderpatch element.
497
499
500
501
502
503
504
505
507 PCDATA value: segment, as defined in section 3.3 of [RFC2396].
509 The DAV:ordering-type property is modified according to the
510 DAV:ordering-type element.
512 The ordering of internal member URIs in the collection identified
513 by the Request-URI is changed based on instructions in the order-
514 member XML elements in the order they appear in the request. The
515 order-member XML elements identify the internal member URIs whose
516 positions are to be changed, and describe their new positions in
517 the ordering. Each new position can be specified as first in the
518 ordering, last in the ordering, immediately before some other
519 internal member URI, or immediately after some other internal
520 member URI.
522 If a response body for a successful request is included, it MUST
523 be a DAV:orderpatch-response XML element. Note that this document
524 does not define any elements for the ORDERPATCH response body, but
525 the DAV:orderpatch-response element is defined to ensure
526 interoperability between future extensions that do define elements
527 for the ORDERPATCH response body.
529
531 Since multiple changes can be requested in a single ORDERPATCH
532 request, if any problems are encountered, the server MUST return a
533 207 (Multi-Status) response (defined in [RFC2518]), containing
534 DAV:response elements for either the request-URI (when the
535 DAV:ordering-type could not be modified) or URIs of collection
536 members to be repositioned (when an individual positioning request
537 expressed as DAV:order-member could not be fulfilled).
539 Preconditions:
541 (DAV:collection-must-be-ordered): see section 6.1.
543 (DAV:segment-must-identify-member): see section 6.1.
545 Postconditions:
547 (DAV:ordering-type-set): if the request body contained a
548 DAV:ordering-type element, the request MUST have set the
549 DAV:ordering-type property of the collection to the value
550 specified in the request.
552 (DAV:ordering-modified): if the request body contained DAV:order-
553 member elements, the request MUST have set the ordering of
554 internal member URIs in the collection identified by the request-
555 URI based on the instructions in the DAV:order-member elements.
557 7.1 Example: Changing a Collection Ordering
559 Consider a collection /coll-1/ whose DAV:ordering-type is DAV:whim,
560 with bindings ordered as follows:
562 three.html
563 four.html
564 one.html
565 two.html
567 >> Request:
569 ORDERPATCH /coll-1/ HTTP/1.1
570 Host: example.org
571 Content-Type: text/xml; charset="utf-8"
572 Content-Length: xxx
574
575
576
577 http://example.org/inorder.ord
578
579
580 two.html
581
582
583
584 one.html
585
586
587
588 three.html
589
590
591
592 four.html
593
594
595
597 >> Response:
599 HTTP/1.1 200 OK
601 In this example, after the request has been processed, the
602 collection's ordering semantics are identified by the URI
603 http://example.org/inorder.ord. The value of the collection's
604 DAV:ordering-type property has been set to this URI. The request also
605 contains instructions for changing the positions of the collection's
606 internal member URIs in the ordering to comply with the new ordering
607 semantics. As the DAV:order-member elements are required to be
608 processed in the order they appear in the request, two.html is moved
609 to the beginning of the ordering, and then one.html is moved to the
610 beginning of the ordering. Then three.html is moved to the end of the
611 ordering, and finally four.html is moved to the end of the ordering.
612 After the request has been processed, the collection's ordering is as
613 follows:
615 one.html
616 two.html
617 three.html
618 four.html
620 7.2 Example: Failure of an ORDERPATCH Request
622 Consider a collection /coll-1/ with members ordered as follows:
624 nunavut.map
625 nunavut.img
626 baffin.map
627 baffin.desc
628 baffin.img
629 iqaluit.map
630 nunavut.desc
631 iqaluit.img
632 iqaluit.desc
634 >> Request:
636 ORDERPATCH /coll-1/ HTTP/1.1
637 Host: www.nunanet.com
638 Content-Type: text/xml; charset="utf-8"
639 Content-Length: xxx
641
642
643
644 nunavut.desc
645
646
647 nunavut.map
648
649
650
651
652 iqaluit.map
653
654
655 pangnirtung.img
656
657
658
659
661 >> Response:
663 HTTP/1.1 207 Multi-Status
664 Content-Type: text/xml; charset="utf-8"
665 Content-Length: xxx
666
667
668
669 http://www.nunanet.com/coll-1/iqaluit.map
670 HTTP/1.1 403 Forbidden
671
672
673 pangnirtung.img is not a collection member.
674
675
676
678 In this example, the client attempted to position iqaluit.map after a
679 URI that is not an internal member of the collection /coll-1/. The
680 server responded to this client error with a 403 (Forbidden) status
681 code, indicating the failed precondition DAV:segment-must-identify-
682 member. Because ORDERPATCH is an atomic method, the request to
683 reposition nunavut.desc (which would otherwise have succeeded) failed
684 as well, but doesn't need to be expressed in the multistatus response
685 body.
687 8 Listing the Members of an Ordered Collection
689 A PROPFIND request is used to retrieve a listing of the members of an
690 ordered collection, just as it is used to retrieve a listing of the
691 members of an unordered collection.
693 However, when responding to a PROPFIND on an ordered collection, the
694 server MUST order the response elements according to the ordering
695 defined on the collection. If a collection is unordered, the client
696 cannot depend on the repeatability of the ordering of results from a
697 PROPFIND request.
699 In a response to a PROPFIND with Depth: infinity, members of
700 different collections may be interleaved. That is, the server is not
701 required to do a breadth-first traversal. The only requirement is
702 that the members of any ordered collection appear in the order
703 defined for the collection. Thus for the hierarchy illustrated in the
704 following figure, where collection A is an ordered collection with
705 the ordering B C D,
707 A
708 /|\
709 / | \
710 B C D
711 / /|\
712 E F G H
714 it would be acceptable for the server to return response elements in
715 the order A B E C F G H D. In this response, B, C, and D appear in
716 the correct order, separated by members of other collections. Clients
717 can use a series of Depth: 1 PROPFIND requests to avoid the
718 complexity of processing Depth: infinity responses based on depth-
719 first traversals.
721 8.1 Example: PROPFIND on an Ordered Collection
723 Suppose a PROPFIND request is submitted to /MyColl/, which has its
724 members ordered as follows.
726 /MyColl/
727 lakehazen.html
728 siorapaluk.html
729 iqaluit.html
730 newyork.html
732 >> Request:
734 PROPFIND /MyColl/ HTTP/1.1
735 Host: example.org
736 Depth: 1
737 Content-Type: text/xml; charset="utf-8"
738 Content-Length: xxxx
740
741
742
743
744
745
746
747
749 >> Response:
751 HTTP/1.1 207 Multi-Status
752 Content-Type: text/xml; charset="utf-8"
753 Content-Length: xxxx
755
756
758
759 http://example.org/MyColl/
760
761
762
763 DAV:custom
764
765
766
767 HTTP/1.1 200 OK
769
770
771
772
773
774 HTTP/1.1 404 Not Found
775
776
777
778 http://example.org/MyColl/lakehazen.html
779
780
781
782 82N
783
784 HTTP/1.1 200 OK
785
786
787
788
789
790 HTTP/1.1 404 Not Found
791
792
793
794 http://example.org/MyColl/siorapaluk.html
796
797
798
799 78N
800
801 HTTP/1.1 200 OK
802
803
804
805
806
807 HTTP/1.1 404 Not Found
808
809
810
811 http://example.org/MyColl/iqaluit.html
812
813
814
815 62N
816
817 HTTP/1.1 200 OK
818
819
820
821
822
823 HTTP/1.1 404 Not Found
824
825
826
827 http://example.org/MyColl/newyork.html
828
829
830
831 45N
832
833 HTTP/1.1 200 OK
834
835
836
837
838 HTTP/1.1 404 Not Found
839
840
841
842
844 In this example, the server responded with a list of the collection
845 members in the order defined for the collection.
847 9 Relationship to versioned collections
849 The Versioning Extensions to WebDAV [RFC3253] introduce the concept
850 of versioned collections, recording both the dead properties and the
851 set of internal version-controlled bindings. This section defines how
852 this feature interacts with ordered collections.
854 This specification considers both the ordering type (DAV:ordering-
855 type property) and the ordering of collection members to be part of
856 the state of a collection. Therefore both MUST be recorded upon
857 CHECKIN or VERSION-CONTROL, and both MUST be restored upon CHECKOUT,
858 UNCHECKOUT or UPDATE (where for compatibility with RFC3253, only the
859 ordering of version-controlled members needs to be maintained).
861 9.1 Collection Version Properties
863 9.1.1 Additional semantics for DAV:version-controlled-binding-set
864 (protected)
866 For ordered collections, the DAV:version-controlled-binding elements
867 MUST appear in the ordering defined for the checked-in ordered
868 collection.
870 9.1.2 DAV:ordering-type (protected)
872 The DAV:ordering-type property records the DAV:ordering-type property
873 of the checked-in ordered collection.
875 9.2 Additional CHECKIN semantics
877 Additional Postconditions:
879 (DAV:initialize-version-controlled-bindings-ordered): If the
880 request-URL identified a both ordered and version-controlled
881 collection, then the child elements of DAV:version-controlled-
882 binding-set of the new collection version MUST appear in the
883 ordering defined for that collection.
885 (DAV:initialize-collection-version-ordering-type): If the request-
886 URL identified a both ordered and version-controlled collection,
887 then the DAV:ordering-type property of the new collection version
888 MUST be a copy of the collection's DAV:ordering-type property.
890 9.3 Additional CHECKOUT Semantics
892 Additional Postconditions:
894 (DAV:initialize-version-history-bindings-ordered): If the request
895 has been applied to a collection version with a DAV:ordering-type
896 other than "DAV:unordered", the bindings in the new working
897 collection MUST be ordered according to the collection version's
898 DAV:version-controlled-binding-set property.
900 (DAV:initialize-ordering-type): If the request has been applied to
901 a collection version, the DAV:ordering-type property of the new
902 working collection MUST be initialized from the collection
903 version's DAV:ordering-type property.
905 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics
907 Additional Postconditions:
909 (DAV:update-version-controlled-collection-members-ordered): If the
910 request modified the DAV:checked-in version of a version-
911 controlled collection and the DAV:ordering-type for the checked-in
912 version is not unordered ("DAV:unordered"), the version-controlled
913 members MUST be ordered according to the checked-in version's
914 DAV:version-controlled-binding-set property.
916 (DAV:update-version-ordering-type): If the request modified the
917 DAV:checked-in version of a version-controlled collection, the
918 DAV:ordering-type property MUST be updated from the checked-in
919 version's property.
921 10 Capability Discovery
923 Sections 9.1 and 15 of [RFC2518] describe the use of compliance
924 classes with the DAV header in responses to OPTIONS, to indicate
925 which parts of the Web Distributed Authoring protocols the resource
926 supports. This specification defines an OPTIONAL extension to
927 [RFC2518]. It defines a new compliance class, called ordered-
928 collections, for use with the DAV header in responses to OPTIONS
929 requests. If a collection resource does support ordering, its
930 response to an OPTIONS request may indicate that it does, by listing
931 the new ORDERPATCH method as one it supports, and by listing the new
932 ordered-collections compliance class in the DAV header.
934 When responding to an OPTIONS request, only a collection or a null
935 resource can include ordered-collections in the value of the DAV
936 header. By including ordered-collections, the resource indicates that
937 its internal member URIs can be ordered. It implies nothing about
938 whether any collections identified by its internal member URIs can be
939 ordered.
941 Furthermore, RFC 3253 [RFC3253] introduces the live properties
942 DAV:supported-method-set (section 3.1.3) and DAV:supported-live-
943 property-set (section 3.1.4). Servers MUST support these properties
944 as defined in RFC 3253.
946 10.1 Example: Using OPTIONS for the Discovery of Support for Ordering
948 >> Request:
950 OPTIONS /somecollection/ HTTP/1.1
951 Host: example.org
953 >> Response:
955 HTTP/1.1 200 OK
956 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
957 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH
958 DAV: 1, 2, ordered-collections
960 The DAV header in the response indicates that the resource
961 /somecollection/ is level 1 and level 2 compliant, as defined in
963 [RFC2518]. In addition, /somecollection/ supports ordering. The Allow
964 header indicates that ORDERPATCH requests can be submitted to
965 /somecollection/.
967 10.2 Example: Using Live Properties for the Discovery of Ordering
969 >> Request:
971 PROPFIND /somecollection HTTP/1.1
972 Depth: 0
973 Content-Type: text/xml; charset="utf-8"
974 Content-Length: xxx
976
977
978
979
980
981
982
984 >> Response:
986 HTTP/1.1 207 Multi-Status
987 Content-Type: text/xml; charset="utf-8"
988 Content-Length: xxx
990
991
992
993 http://example.org/somecollection
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020 HTTP/1.1 200 OK
1021
1022
1023
1025 Note that actual responses MUST contain a complete list of supported
1026 live properties.
1028 11 Security Considerations
1030 This section is provided to make WebDAV applications aware of the
1031 security implications of this protocol.
1033 All of the security considerations of HTTP/1.1 and the WebDAV
1034 Distributed Authoring Protocol specification also apply to this
1035 protocol specification. In addition, ordered collections introduce a
1036 new security concern. This issue is detailed here.
1038 11.1 Denial of Service and DAV:ordering-type
1040 There may be some risk of denial of service at sites that are
1041 advertised in the DAV:ordering-type property of collections. However,
1042 it is anticipated that widely-deployed applications will use hard-
1043 coded values for frequently-used ordering semantics rather than
1044 looking up the semantics at the location specified by DAV:ordering-
1045 type. This risk will be further reduced if clients observe the
1046 recommendation of section 5.1 that they not send requests to the URI
1047 in DAV:ordering-type.
1049 12 Internationalization Considerations
1051 This specification follows the practices of [RFC2518] in encoding all
1052 human-readable content using [XML] and in the treatment of names.
1053 Consequently, this specification complies with the IETF Character Set
1054 Policy [RFC2277].
1056 WebDAV applications MUST support the character set tagging, character
1057 set encoding, and the language tagging functionality of the XML
1058 specification. This constraint ensures that the human-readable
1059 content of this specification complies with [RFC2277].
1061 As in [RFC2518], names in this specification fall into three
1062 categories: names of protocol elements such as methods and headers,
1063 names of XML elements, and names of properties. Naming of protocol
1064 elements follows the precedent of HTTP, using English names encoded
1065 in USASCII for methods and headers. The names of XML elements used in
1066 this specification are English names encoded in UTF-8.
1068 For error reporting, [RFC2518] follows the convention of HTTP/1.1
1069 status codes, including with each status code a short, English
1070 description of the code (e.g., 423 Locked). Internationalized
1071 applications will ignore this message, and display an appropriate
1072 message in the user's language and character set.
1074 This specification introduces no new strings that are displayed to
1075 users as part of normal, error-free operation of the protocol.
1077 For rationales for these decisions and advice for application
1078 implementors, see [RFC2518].
1080 13 IANA Considerations
1082 This document uses the namespaces defined by [RFC2518] for properties
1083 and XML elements. All other IANA considerations mentioned in
1084 [RFC2518] also apply to this document.
1086 14 Copyright
1088 To be supplied by the RFC Editor.
1090 15 Intellectual Property
1092 To be supplied by the RFC Editor.
1094 16 Acknowledgements
1096 This draft has benefited from thoughtful discussion by Jim Amsden,
1097 Steve Carter, Tyson Chihaya, Geoff Clemm, Ken Coar, Ellis Cohen,
1098 Bruce Cragun, Jim Davis, Spencer Dawkins, Mark Day, Rajiv Dulepet,
1099 David Durand, Lisa Dusseault, Chuck Fay, Roy Fielding, Yaron Goland,
1100 Fred Hitt, Alex Hopmann, Marcus Jager, Chris Kaler, Manoj
1101 Kasichainula, Rohit Khare, Daniel LaLiberte, Steve Martin, Larry
1102 Masinter, Jeff McAffer, Surendra Koduru Reddy, Max Rible, Sam Ruby,
1103 Bradley Sergeant, Nick Shelness, John Stracke, John Tigue, John
1104 Turner, Kevin Wiggen, and others.
1106 Normative References
1108 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1109 Requirement Levels", BCP 14, RFC 2119, March 1997.
1111 [RFC2277] Alvestrand, H.T., "IETF Policy on Character Sets and
1112 Languages", BCP 18, RFC 2277, January 1998.
1114 [RFC2396] Berners-Lee, T., Fielding, R.T. and Masinter, L., "Uniform
1115 Resource Identifiers (URI): Generic Syntax", RFC 2396,
1116 August 1998.
1118 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S.R. and
1119 Jensen, D., "HTTP Extensions for Distributed Authoring --
1120 WEBDAV", RFC 2518, February 1999.
1122 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1123 Masinter, L., Leach, P. and Berners-Lee, T., "Hypertext
1124 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1126 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and
1127 Whitehead, J., "Versioning Extensions to WebDAV", RFC
1128 3253, March 2002.
1130 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C.M. and Maler, E.,
1131 "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C REC-
1132 xml, October 2000.
1134 Author's Addresses
1136 Judith Slein
1137 Xerox Corporation
1138 800 Phillips Road, 105-50C
1139 Webster, NY 14580
1141 EMail: jslein@crt.xerox.com
1143 Jim Whitehead
1144 UC Santa Cruz, Dept. of Computer Science
1145 1156 High Street
1146 Santa Cruz, CA 95064
1147 US
1149 EMail: ejw@cse.ucsc.edu
1150 Jason Crawford
1151 IBM Research
1152 P.O. Box 704
1153 Yorktown Heights, NY 10598
1155 EMail: ccjason@us.ibm.com
1157 Julian F. Reschke
1158 greenbytes GmbH
1159 Salzmannstrasse 152
1160 Muenster, NW 48159
1161 Germany
1163 Phone: +49 251 2807760
1164 Fax: +49 251 2807761
1165 EMail: julian.reschke@greenbytes.de
1166 URI: http://greenbytes.de/tech/webdav/
1168 A Extensions to the WebDAV Document Type Definition
1170
1171
1172
1173
1174
1175
1176
1177
1178
1180 B Change Log
1182 B.1 Since draft-ietf-webdav-ordering-protocol dated December 1999
1184 Updated contact information for all previous authors.
1185 Specify charset when using text/xml media type.
1186 Made sure artwork fits into 72 columns.
1187 Removed "Public" header from OPTIONS example.
1188 Added Julian Reschke to list of authors.
1189 Fixed broken XML in PROPFIND example and added DAV:orderingtype to
1190 list of requested properties.
1191 Added support for DAV:supported-live-property-set and DAV:supported-
1192 method-set as mandatory features.
1194 B.2 Since draft-ietf-webdav-ordering-protocol-02
1196 Updated change log to refer to expired draft version as "December
1197 1999" version.
1198 Started rewrite marshalling in RFC3253-style and added precondition
1199 and postcondition definitions.
1200 On his request, removed Geoff Clemm's name from the author list
1201 (moved to Acknowledgments).
1202 Renamed "References" to "Normative References".
1203 Removed reference to "MKREF" method.
1205 B.3 Since draft-ietf-webdav-ordering-protocol-03
1207 Added a set of issues regarding marshalling.
1208 Changed host names to use proper "example" domain names (no change
1209 tracking). Fixed host/destination header conflicts. Fixed "allow"
1210 header (multiline). Removed irrelevant response headers. Abbreviated
1211 some URIs (no change tracking).
1212 Removed Jim Davis and Chuck Fay from the author list (and added them
1213 to the Acknowledgements section).
1214 Updated section on setting the position when adding new members,
1215 removed old section on Position header.
1216 Started work on Index section.
1217 Changed structure for section 7 (no change tracking).
1218 Removed header and XML elements section (contents moved to other
1219 sections).
1220 Started new section on relation to versioned collections as per
1221 RFC3253.
1222 Do not return 424's for in ORDERPATCH multistatus (it's atomic
1223 anyway).
1225 B.4 Since draft-ietf-webdav-ordering-protocol-04
1227 Added proper reference to definition of "Coded-URL".
1228 Closed issue ordering-type-values (content model simplified and XML
1229 element / DAV property renamed) and updated examples.
1230 Renamed precondition DAV:orderingtype-set to DAV:ordering-type-set
1231 (no change tracking).
1232 Closed issue ordered-header-name (header name changed to "ordering-
1233 type", contents matches live property).
1234 Closed issue ordermember-format (now takes segment instead of href).
1235 Renamed compliance class to "ordered-collections" for consistency
1236 with newer specs, and to allow detection of compliance to final
1237 version of spec.
1238 Updated reference to XML spec to 1.0, 2nd edition.
1240 B.5 Since draft-ietf-webdav-ordering-protocol-05
1242 Typos fixed.
1243 Renamed DAV:ordermember to DAV:order-member.
1244 Made RFC3253-compatible pre/postcondition handling a MUST
1245 requirement.
1246 Reference definition of "protected property" from RFC3253.
1247 Added explanation of role of DTD fragments to Notation section.
1248 Clarified semantics for operations on versioned collections and
1249 collection versions.
1251 B.6 Since draft-ietf-webdav-ordering-protocol-06
1253 Added atomicity statement for ORDERPATCH method.
1255 Index
1257 C
1259 Client-Maintained Ordering
1260 3
1262 D
1264 DAV:collection-must-be-ordered precondition
1265 6.1
1266 DAV:custom ordering type
1267 4.1.1
1268 DAV:initialize-collection-version-ordering-type
1269 9.2
1270 DAV:initialize-ordering-type
1271 9.3
1272 DAV:initialize-version-controlled-bindings-ordered postcondition
1273 9.2
1274 DAV:initialize-version-history-bindings-ordered
1275 9.3
1276 DAV:ordered-collections-supported precondition
1277 5.1
1278 DAV:ordering-modified postcondition
1279 7
1280 DAV:ordering-type property
1281 4.1.1
1282 DAV:ordering-type-set postcondition
1283 5.1, 7
1284 DAV:position-set postcondition
1285 6.1
1286 DAV:segment-must-identify-member precondition
1287 6.1
1288 DAV:unordered ordering type
1289 4.1.1
1290 DAV:update-version-controlled-collection-members-ordered
1291 9.4
1292 DAV:update-version-ordering-type
1293 9.4
1295 H
1297 Headers
1298 Ordering-Type 5.1
1300 O
1302 Ordered Collection
1303 3
1304 Ordering-Type header
1305 5.1
1306 ORDERPATCH method
1307 7
1309 P
1311 Postconditions
1312 DAV:ordering-type-set 5.1, 7
1313 DAV:position-set 6.1
1314 DAV:ordering-type-set 5.1, 7
1315 DAV:ordering-modified 7
1316 DAV:initialize-version-controlled-bindings-ordered 9.2
1317 DAV:initialize-collection-version-ordering-type 9.2
1318 DAV:initialize-version-history-bindings-ordered 9.3
1319 DAV:initialize-ordering-type 9.3
1320 DAV:update-version-controlled-collection-members-ordered 9.4
1321 DAV:update-version-ordering-type 9.4
1323 Preconditions
1324 DAV:ordered-collections-supported 5.1
1325 DAV:collection-must-be-ordered 6.1
1326 DAV:segment-must-identify-member 6.1
1328 Protected properties
1329 DAV:ordering-type 4.1.1
1331 S
1333 Server-Maintained Ordering
1334 3
1336 U
1338 Unordered Collection
1339 3
1341 Full Copyright Statement
1343 Copyright (C) The Internet Society (2003). All Rights Reserved.
1345 This document and translations of it may be copied and furnished
1346 to others, and derivative works that comment on or otherwise
1347 explain it or assist in its implementation may be prepared,
1348 copied, published and distributed, in whole or in part, without
1349 restriction of any kind, provided that the above copyright notice
1350 and this paragraph are included on all such copies and derivative
1351 works. However, this document itself may not be modified in any
1352 way, such as by removing the copyright notice or references to the
1353 Internet Society or other Internet organizations, except as needed
1354 for the purpose of developing Internet standards in which case the
1355 procedures for copyrights defined in the Internet Standards
1356 process must be followed, or as required to translate it into
1357 languages other than English.
1359 The limited permissions granted above are perpetual and will not
1360 be revoked by the Internet Society or its successors or assigns.
1362 This document and the information contained herein is provided on
1363 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
1364 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
1365 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
1366 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1367 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1369 Acknowledgement
1371 Funding for the RFC editor function is currently provided by the
1372 Internet Society.