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