idnits 2.17.1
draft-ietf-webdav-ordering-protocol-06.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 (February 2003) is 7741 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: August 2003 J. Whitehead
5 U.C. Santa Cruz
6 J. Crawford
7 IBM
8 J. F. Reschke
9 greenbytes
10 February 2003
12 WebDAV Ordered Collections Protocol
13 draft-ietf-webdav-ordering-protocol-06
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 August 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 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
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 stated
142 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 might
153 represent the pages of a book, which need to be presented in order if
154 they are to make sense. Or an instructor might create a collection of
155 course readings, which she wants to be displayed in the order they
156 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 human-
166 maintained orderings. Its protocol elements allow clients to specify
167 the position of each collection member in the collection's ordering,
168 as well as the semantics governing the ordering. The protocol is
169 designed to allow support to be added in the future for orderings
170 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) or later
229 (using the ORDERPATCH method). For server-maintained orderings, the
230 server automatically positions each of the collection's members
231 according to the ordering semantics. This specification supports only
232 client-maintained orderings, but is designed to allow future
233 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. The server MUST add an internal member
243 URI to the ordering when it is added to the collection.
245 Only one ordering can be attached to any collection. Multiple
246 orderings of the same resources can be achieved by creating multiple
247 collections referencing those resources, and attaching a different
248 ordering to each collection.
250 An ordering is considered to be part of the state of a collection
251 resource. Consequently, the ordering is the same no matter which URI
252 is used to access the collection and is protected by locks or access
253 control constraints on the collection.
255 4.1 Additional Collection properties
257 A DAV:allprop PROPFIND request SHOULD NOT return any of the
258 properties defined in this document.
260 4.1.1 DAV:ordering-type (protected)
262 Indicates whether the collection is ordered and, if so, uniquely
263 identifies the semantics of the ordering being used. May also point
264 to an explanation of the semantics in human and / or machine-readable
265 form. At a minimum, this allows human users who add members to the
266 collection to understand where to position them in the ordering. This
267 property cannot be set using PROPPATCH. Its value can only be set by
268 including the Ordering-Type header with a MKCOL request or by
269 submitting an ORDERPATCH request.
271 Ordering types are identified by URIs that uniquely identify the
272 semantics of the collection's ordering. The following two URIs are
273 predefined:
275 DAV:custom The value DAV:custom indicates that the collection is
276 ordered, but the semantics governing the ordering are
277 not being advertised.
278 DAV:unordered The value DAV:unordered indicates that the collection
279 is not ordered. That is, the client cannot depend on
280 the repeatability of the ordering of results from a
281 PROPFIND request.
283 An ordering-aware client interacting with an ordering-unaware server
284 (e.g., one that is implemented only according to [RFC2518]) SHOULD
285 assume that if a collection does not have the DAV:ordering-type
286 property, the collection is unordered.
288
290 5 Creating an Ordered Collection
292 5.1 Overview
294 When a collection is created, the client MAY request that it be
295 ordered and specify the semantics of the ordering by using the new
296 Ordering-Type header (defined below) with a MKCOL request.
298 For collections that are ordered, the client SHOULD identify the
299 semantics of the ordering with a URI in the Ordering-Type header,
300 although the client MAY simply set the header value to DAV:custom to
301 indicate that the collection is ordered but the semantics of the
302 ordering are not being advertised. Setting the value to a URI that
303 identifies the ordering semantics provides the information a human
304 user or software package needs to insert new collection members into
305 the ordering intelligently. Although the URI in the Ordering-Type
306 header MAY point to a resource that contains a definition of the
307 semantics of the ordering, clients SHOULD NOT access that resource,
308 in order to avoid overburdening its server. A value of DAV:unordered
309 in the Ordering-Type header indicates that the client wants the
310 collection to be unordered. If the Ordering-Type header is not
311 present, the collection will be unordered.
313 Additional Marshalling:
315 Ordering-Type = "Ordering-Type" ":" absoluteURI
316 ; absoluteURI: see RFC2396, section 3
318 The URI "DAV:unordered" indicates that the collection is not
319 ordered, while "DAV:custom" indicates that the collection is to be
320 ordered, but the semantics of the ordering is not being
321 advertised. Any other URI value indicates that the collection is
322 ordered, and identifies the semantics of the ordering.
324 Additional Preconditions:
326 (DAV:ordered-collections-supported): the server MUST support
327 ordered collections in the part of the URL namespace identified by
328 the request URL.
330 Additional Postconditions:
332 (DAV:ordering-type-set): if the Ordering-Type header was present,
333 the request MUST have created a new collection resource with the
334 DAV:ordering-type being set according to the Ordering-Type request
335 header. The collection MUST be ordered unless the ordering type
336 was "DAV:unordered".
338 5.2 Example: Creating an Ordered Collection
340 >> Request:
342 MKCOL /theNorth/ HTTP/1.1
343 Host: example.org
344 Ordering-Type: http://example.org/orderings/compass.html
346 >> Response:
348 HTTP/1.1 201 Created
350 In this example a new, ordered collection was created. Its
351 DAV:ordering-type property has as its value the URI from the
352 Ordering-Type header, http://example.org/orderings/compass.html. In
353 this case, the URI identifies the semantics governing a client-
354 maintained ordering. As new members are added to the collection,
355 clients or end users can use the semantics to determine where to
356 position the new members in the ordering.
358 6 Setting the Position of a Collection Member
360 6.1 Overview
362 When a new member is added to a collection with a client-maintained
363 ordering (for example, with PUT, COPY, or MKCOL), its position in the
364 ordering can be set with the new Position header. The Position header
365 allows the client to specify that an internal member URI should be
366 first in the collection's ordering, last in the collection's
367 ordering, immediately before some other internal member URI in the
368 collection's ordering, or immediately after some other internal
369 member URI in the collection's ordering.
371 If the Position request header is not used when adding a member to an
372 ordered collection, then:
374 o If the request is replacing an existing resource, the server MUST
375 preserve the present ordering.
377 o If the request is adding a new internal member URI to the
378 collection, the server MUST append the new member to the end of
379 the ordering.
381 Additional Marshalling:
383 Position = "Position" ":" ("first" | "last" |
384 (("before" | "after") segment))
386 segment is defined in Section 3.3 of [RFC2396].
388 The segment is interpreted relative to the collection to which the
389 new member is being added.
391 When the Position header is present, the server MUST insert the
392 new member into the ordering at the specified location.
394 The "first" keyword indicates the new member is put in the
395 beginning position in the collection's ordering, while "last"
396 indicates the new member is put in the final position in the
397 collection's ordering. The "before" keyword indicates the new
398 member is added to the collection's ordering immediately prior to
399 the position of the member identified in the segment. Likewise,
400 the "after" keyword indicates the new member is added to the
401 collection's ordering immediately following the position of the
402 member identified in the segment.
404 If the request is replacing an existing resource, and the Position
405 header is present, the server MUST remove the internal member URI
406 from its previous position, and then insert it at the requested
407 position.
409 Additional Preconditions:
411 (DAV:collection-must-be-ordered): the target collection MUST be
412 ordered.
414 (DAV:segment-must-identify-member): the referenced segment MUST
415 identify a resource that exists and is different from the affected
416 resource.
418 Additional Postconditions:
420 (DAV:position-set): if a Position header was present, the request
421 MUST have created the new collection member at the specified
422 position.
424 6.2 Examples: Setting the Position of a Collection Member
426 >> Request:
428 COPY /~user/dav/spec08.html HTTP/1.1
429 Host: example.org
430 Destination: http://example.org/~slein/dav/spec08.html
431 Position: after requirements.html
433 >> Response:
435 HTTP/1.1 201 Created
436 This request resulted in the creation of a new resource at
437 example.org/~slein/dav/spec08.html. The Position header in this
438 example caused the server to set its position in the ordering of the
439 /~slein/dav/ collection immediately after requirements.html.
441 >> Request:
443 MOVE /i-d/draft-webdav-prot-08.txt HTTP/1.1
444 Host: example.org
445 Destination: http://example.org/~user/dav/draft-webdav-prot-08.txt
446 Position: first
448 >> Response:
450 HTTP/1.1 409 Conflict
451 Content-Type: text/xml; charset="utf-8"
452 Content-Length: xxxx
454
455
456
457
459 In this case, the server returned a 409 (Conflict) status code
460 because the /~user/dav/ collection is an unordered collection.
461 Consequently, the server was unable to satisfy the Position header.
463 7 Changing a Collection Ordering: ORDERPATCH method
465 The ORDERPATCH method is used to change the ordering semantics of a
466 collection or to change the order of the collection's members in the
467 ordering or both.
469 The server MUST apply the changes in the order they appear in the
470 order XML element. The server MUST either apply all the changes or
471 apply none of them. If any error occurs during processing, all
472 executed changes MUST be undone and a proper error result returned.
474 If an ORDERPATCH request changes the ordering semantics, but does not
475 completely specify the order of the collection members, the server
476 MUST assign a position in the ordering to each collection member for
477 which a position was not specified. These server-assigned positions
478 MUST all follow the last one specified by the client. The result is
479 that all members for which the client specified a position are at the
480 beginning of the ordering, followed by any members for which the
481 server assigned positions.
483 If an ORDERPATCH request does not change the ordering semantics, any
484 member positions not specified in the request MUST remain unchanged.
486 A request to reposition a collection member at the same place in the
487 ordering is not an error.
489 Additional Marshalling:
491 The request body MUST be DAV:orderpatch element.
493
495
496
497
498
499
500
501
503 PCDATA value: segment, as defined in section 3.3 of [RFC2396].
505 The DAV:ordering-type property is modified according to the
506 DAV:ordering-type element.
508 The ordering of internal member URIs in the collection identified
509 by the Request-URI is changed based on instructions in the order-
510 member XML elements in the order they appear in the request. The
511 order-member XML elements identify the internal member URIs whose
512 positions are to be changed, and describe their new positions in
513 the ordering. Each new position can be specified as first in the
514 ordering, last in the ordering, immediately before some other
515 internal member URI, or immediately after some other internal
516 member URI.
518 If a response body for a successful request is included, it MUST
519 be a DAV:orderpatch-response XML element. Note that this document
520 does not define any elements for the ORDERPATCH response body, but
521 the DAV:orderpatch-response element is defined to ensure
522 interoperability between future extensions that do define elements
523 for the ORDERPATCH response body.
525
527 Since multiple changes can be requested in a single ORDERPATCH
528 request, if any problems are encountered, the server MUST return a
529 207 (Multi-Status) response (defined in [RFC2518]), containing
530 DAV:response elements for either the request-URI (when the
531 DAV:ordering-type could not be modified) or URIs of collection
532 members to be repositioned (when an individual positioning request
533 expressed as DAV:order-member could not be fulfilled).
535 Preconditions:
537 (DAV:collection-must-be-ordered): see section 6.1.
539 (DAV:segment-must-identify-member): see section 6.1.
541 Postconditions:
543 (DAV:ordering-type-set): if the request body contained a
544 DAV:ordering-type element, the request MUST have set the
545 DAV:ordering-type property of the collection to the value
546 specified in the request.
548 (DAV:ordering-modified): if the request body contained DAV:order-
549 member elements, the request MUST have set the ordering of
550 internal member URIs in the collection identified by the request-
551 URI based on the instructions in the DAV:order-member elements.
553 7.1 Example: Changing a Collection Ordering
555 Consider a collection /coll-1/ whose DAV:ordering-type is DAV:whim,
556 with bindings ordered as follows:
558 three.html
559 four.html
560 one.html
561 two.html
563 >> Request:
565 ORDERPATCH /coll-1/ HTTP/1.1
566 Host: example.org
567 Content-Type: text/xml; charset="utf-8"
568 Content-Length: xxx
570
571
572
573 http://example.org/inorder.ord
574
575
576 two.html
577
578
579
580 one.html
581
582
583
584 three.html
585
586
587
588 four.html
589
590
591
593 >> Response:
595 HTTP/1.1 200 OK
597 In this example, after the request has been processed, the
598 collection's ordering semantics are identified by the URI
599 http://example.org/inorder.ord. The value of the collection's
600 DAV:ordering-type property has been set to this URI. The request also
601 contains instructions for changing the positions of the collection's
602 internal member URIs in the ordering to comply with the new ordering
603 semantics. As the DAV:order-member elements are required to be
604 processed in the order they appear in the request, two.html is moved
605 to the beginning of the ordering, and then one.html is moved to the
606 beginning of the ordering. Then three.html is moved to the end of the
607 ordering, and finally four.html is moved to the end of the ordering.
608 After the request has been processed, the collection's ordering is as
609 follows:
611 one.html
612 two.html
613 three.html
614 four.html
616 7.2 Example: Failure of an ORDERPATCH Request
618 Consider a collection /coll-1/ with members ordered as follows:
620 nunavut.map
621 nunavut.img
622 baffin.map
623 baffin.desc
624 baffin.img
625 iqaluit.map
626 nunavut.desc
627 iqaluit.img
628 iqaluit.desc
630 >> Request:
632 ORDERPATCH /coll-1/ HTTP/1.1
633 Host: www.nunanet.com
634 Content-Type: text/xml; charset="utf-8"
635 Content-Length: xxx
637
638
639
640 nunavut.desc
641
642
643 nunavut.map
644
645
646
647
648 iqaluit.map
649
650
651 pangnirtung.img
652
653
654
655
657 >> Response:
659 HTTP/1.1 207 Multi-Status
660 Content-Type: text/xml; charset="utf-8"
661 Content-Length: xxx
662
663
664
665 http://www.nunanet.com/coll-1/iqaluit.map
666 HTTP/1.1 403 Forbidden
667
668
669 pangnirtung.img is not a collection member.
670
671
672
674 In this example, the client attempted to position iqaluit.map after a
675 URI that is not an internal member of the collection /coll-1/. The
676 server responded to this client error with a 403 (Forbidden) status
677 code, indicating the failed precondition DAV:segment-must-identify-
678 member. Because ORDERPATCH is an atomic method, the request to
679 reposition nunavut.desc (which would otherwise have succeeded) failed
680 as well, but doesn't need to be expressed in the multistatus response
681 body.
683 8 Listing the Members of an Ordered Collection
685 A PROPFIND request is used to retrieve a listing of the members of an
686 ordered collection, just as it is used to retrieve a listing of the
687 members of an unordered collection.
689 However, when responding to a PROPFIND on an ordered collection, the
690 server MUST order the response elements according to the ordering
691 defined on the collection. If a collection is unordered, the client
692 cannot depend on the repeatability of the ordering of results from a
693 PROPFIND request.
695 In a response to a PROPFIND with Depth: infinity, members of
696 different collections may be interleaved. That is, the server is not
697 required to do a breadth-first traversal. The only requirement is
698 that the members of any ordered collection appear in the order
699 defined for the collection. Thus for the hierarchy illustrated in the
700 following figure, where collection A is an ordered collection with
701 the ordering B C D,
703 A
704 /|\
705 / | \
706 B C D
707 / /|\
708 E F G H
710 it would be acceptable for the server to return response elements in
711 the order A B E C F G H D. In this response, B, C, and D appear in
712 the correct order, separated by members of other collections. Clients
713 can use a series of Depth: 1 PROPFIND requests to avoid the
714 complexity of processing Depth: infinity responses based on depth-
715 first traversals.
717 8.1 Example: PROPFIND on an Ordered Collection
719 Suppose a PROPFIND request is submitted to /MyColl/, which has its
720 members ordered as follows.
722 /MyColl/
723 lakehazen.html
724 siorapaluk.html
725 iqaluit.html
726 newyork.html
728 >> Request:
730 PROPFIND /MyColl/ HTTP/1.1
731 Host: example.org
732 Depth: 1
733 Content-Type: text/xml; charset="utf-8"
734 Content-Length: xxxx
736
737
738
739
740
741
742
743
745 >> Response:
747 HTTP/1.1 207 Multi-Status
748 Content-Type: text/xml; charset="utf-8"
749 Content-Length: xxxx
751
752
754
755 http://example.org/MyColl/
756
757
758
759 DAV:custom
760
761
762
763 HTTP/1.1 200 OK
765
766
767
768
769
770 HTTP/1.1 404 Not Found
771
772
773
774 http://example.org/MyColl/lakehazen.html
775
776
777
778 82N
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/siorapaluk.html
792
793
794
795 78N
796
797 HTTP/1.1 200 OK
798
799
800
801
802
803 HTTP/1.1 404 Not Found
804
805
806
807 http://example.org/MyColl/iqaluit.html
808
809
810
811 62N
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/newyork.html
824
825
826
827 45N
828
829 HTTP/1.1 200 OK
830
831
832
833
834 HTTP/1.1 404 Not Found
835
836
837
838
840 In this example, the server responded with a list of the collection
841 members in the order defined for the collection.
843 9 Relationship to versioned collections
845 The Versioning Extensions to WebDAV [RFC3253] introduce the concept
846 of versioned collections, recording both the dead properties and the
847 set of internal version-controlled bindings. This section defines how
848 this feature interacts with ordered collections.
850 This specification considers both the ordering type (DAV:ordering-
851 type property) and the ordering of collection members to be part of
852 the state of a collection. Therefore both MUST be recorded upon
853 CHECKIN or VERSION-CONTROL, and both MUST be restored upon CHECKOUT,
854 UNCHECKOUT or UPDATE (where for compatibility with RFC3253, only the
855 ordering of version-controlled members needs to be maintained).
857 9.1 Collection Version Properties
859 9.1.1 Additional semantics for DAV:version-controlled-binding-set
860 (protected)
862 For ordered collections, the DAV:version-controlled-binding elements
863 MUST appear in the ordering defined for the checked-in ordered
864 collection.
866 9.1.2 DAV:ordering-type (protected)
868 The DAV:ordering-type property records the DAV:ordering-type property
869 of the checked-in ordered collection.
871 9.2 Additional CHECKIN semantics
873 Additional Postconditions:
875 (DAV:initialize-version-controlled-bindings-ordered): If the
876 request-URL identified a both ordered and version-controlled
877 collection, then the child elements of DAV:version-controlled-
878 binding-set of the new collection version MUST appear in the
879 ordering defined for that collection.
881 (DAV:initialize-collection-version-ordering-type): If the request-
882 URL identified a both ordered and version-controlled collection,
883 then the DAV:ordering-type property of the new collection version
884 MUST be a copy of the collection's DAV:ordering-type property.
886 9.3 Additional CHECKOUT Semantics
888 Additional Postconditions:
890 (DAV:initialize-version-history-bindings-ordered): If the request
891 has been applied to a collection version with a DAV:ordering-type
892 other than "DAV:unordered", the bindings in the new working
893 collection MUST be ordered according to the collection version's
894 DAV:version-controlled-binding-set property.
896 (DAV:initialize-ordering-type): If the request has been applied to
897 a collection version, the DAV:ordering-type property of the new
898 working collection MUST be initialized from the collection
899 version's DAV:ordering-type property.
901 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics
903 Additional Postconditions:
905 (DAV:update-version-controlled-collection-members-ordered): If the
906 request modified the DAV:checked-in version of a version-
907 controlled collection and the DAV:ordering-type for the checked-in
908 version is not unordered ("DAV:unordered"), the version-controlled
909 members MUST be ordered according to the checked-in version's
910 DAV:version-controlled-binding-set property.
912 (DAV:update-version-ordering-type): If the request modified the
913 DAV:checked-in version of a version-controlled collection, the
914 DAV:ordering-type property MUST be updated from the checked-in
915 version's property.
917 10 Capability Discovery
919 Sections 9.1 and 15 of [RFC2518] describe the use of compliance
920 classes with the DAV header in responses to OPTIONS, to indicate
921 which parts of the Web Distributed Authoring protocols the resource
922 supports. This specification defines an OPTIONAL extension to
923 [RFC2518]. It defines a new compliance class, called ordered-
924 collections, for use with the DAV header in responses to OPTIONS
925 requests. If a collection resource does support ordering, its
926 response to an OPTIONS request may indicate that it does, by listing
927 the new ORDERPATCH method as one it supports, and by listing the new
928 ordered-collections compliance class in the DAV header.
930 When responding to an OPTIONS request, only a collection or a null
931 resource can include ordered-collections in the value of the DAV
932 header. By including ordered-collections, the resource indicates that
933 its internal member URIs can be ordered. It implies nothing about
934 whether any collections identified by its internal member URIs can be
935 ordered.
937 Furthermore, RFC 3253 [RFC3253] introduces the live properties
938 DAV:supported-method-set (section 3.1.3) and DAV:supported-live-
939 property-set (section 3.1.4). Servers MUST support these properties
940 as defined in RFC 3253.
942 10.1 Example: Using OPTIONS for the Discovery of Support for Ordering
944 >> Request:
946 OPTIONS /somecollection/ HTTP/1.1
947 Host: example.org
949 >> Response:
951 HTTP/1.1 200 OK
952 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
953 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH
954 DAV: 1, 2, ordered-collections
956 The DAV header in the response indicates that the resource
957 /somecollection/ is level 1 and level 2 compliant, as defined in
959 [RFC2518]. In addition, /somecollection/ supports ordering. The Allow
960 header indicates that ORDERPATCH requests can be submitted to
961 /somecollection/.
963 10.2 Example: Using Live Properties for the Discovery of Ordering
965 >> Request:
967 PROPFIND /somecollection HTTP/1.1
968 Depth: 0
969 Content-Type: text/xml; charset="utf-8"
970 Content-Length: xxx
972
973
974
975
976
977
978
980 >> Response:
982 HTTP/1.1 207 Multi-Status
983 Content-Type: text/xml; charset="utf-8"
984 Content-Length: xxx
986
987
988
989 http://example.org/somecollection
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016 HTTP/1.1 200 OK
1017
1018
1019
1021 Note that actual responses MUST contain a complete list of supported
1022 live properties.
1024 11 Security Considerations
1026 This section is provided to make WebDAV applications aware of the
1027 security implications of this protocol.
1029 All of the security considerations of HTTP/1.1 and the WebDAV
1030 Distributed Authoring Protocol specification also apply to this
1031 protocol specification. In addition, ordered collections introduce a
1032 new security concern. This issue is detailed here.
1034 11.1 Denial of Service and DAV:ordering-type
1036 There may be some risk of denial of service at sites that are
1037 advertised in the DAV:ordering-type property of collections. However,
1038 it is anticipated that widely-deployed applications will use hard-
1039 coded values for frequently-used ordering semantics rather than
1040 looking up the semantics at the location specified by DAV:ordering-
1041 type. This risk will be further reduced if clients observe the
1042 recommendation of section 5.1 that they not send requests to the URI
1043 in DAV:ordering-type.
1045 12 Internationalization Considerations
1047 This specification follows the practices of [RFC2518] in encoding all
1048 human-readable content using [XML] and in the treatment of names.
1049 Consequently, this specification complies with the IETF Character Set
1050 Policy [RFC2277].
1052 WebDAV applications MUST support the character set tagging, character
1053 set encoding, and the language tagging functionality of the XML
1054 specification. This constraint ensures that the human-readable
1055 content of this specification complies with [RFC2277].
1057 As in [RFC2518], names in this specification fall into three
1058 categories: names of protocol elements such as methods and headers,
1059 names of XML elements, and names of properties. Naming of protocol
1060 elements follows the precedent of HTTP, using English names encoded
1061 in USASCII for methods and headers. The names of XML elements used in
1062 this specification are English names encoded in UTF-8.
1064 For error reporting, [RFC2518] follows the convention of HTTP/1.1
1065 status codes, including with each status code a short, English
1066 description of the code (e.g., 423 Locked). Internationalized
1067 applications will ignore this message, and display an appropriate
1068 message in the user's language and character set.
1070 This specification introduces no new strings that are displayed to
1071 users as part of normal, error-free operation of the protocol.
1073 For rationales for these decisions and advice for application
1074 implementors, see [RFC2518].
1076 13 IANA Considerations
1078 This document uses the namespaces defined by [RFC2518] for properties
1079 and XML elements. All other IANA considerations mentioned in
1080 [RFC2518] also apply to this document.
1082 14 Copyright
1084 To be supplied by the RFC Editor.
1086 15 Intellectual Property
1088 To be supplied by the RFC Editor.
1090 16 Acknowledgements
1092 This draft has benefited from thoughtful discussion by Jim Amsden,
1093 Steve Carter, Tyson Chihaya, Geoff Clemm, Ken Coar, Ellis Cohen,
1094 Bruce Cragun, Jim Davis, Spencer Dawkins, Mark Day, Rajiv Dulepet,
1095 David Durand, Lisa Dusseault, Chuck Fay, Roy Fielding, Yaron Goland,
1096 Fred Hitt, Alex Hopmann, Marcus Jager, Chris Kaler, Manoj
1097 Kasichainula, Rohit Khare, Daniel LaLiberte, Steve Martin, Larry
1098 Masinter, Jeff McAffer, Surendra Koduru Reddy, Max Rible, Sam Ruby,
1099 Bradley Sergeant, Nick Shelness, John Stracke, John Tigue, John
1100 Turner, Kevin Wiggen, and others.
1102 Normative References
1104 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1105 Requirement Levels", BCP 14, RFC 2119, March 1997.
1107 [RFC2277] Alvestrand, H.T., "IETF Policy on Character Sets and
1108 Languages", BCP 18, RFC 2277, January 1998.
1110 [RFC2396] Berners-Lee, T., Fielding, R.T. and Masinter, L., "Uniform
1111 Resource Identifiers (URI): Generic Syntax", RFC 2396,
1112 August 1998.
1114 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S.R. and
1115 Jensen, D., "HTTP Extensions for Distributed Authoring --
1116 WEBDAV", RFC 2518, February 1999.
1118 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1119 Masinter, L., Leach, P. and Berners-Lee, T., "Hypertext
1120 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1122 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and
1123 Whitehead, J., "Versioning Extensions to WebDAV", RFC
1124 3253, March 2002.
1126 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C.M. and Maler, E.,
1127 "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C REC-
1128 xml, October 2000.
1130 Author's Addresses
1132 Judith Slein
1133 Xerox Corporation
1134 800 Phillips Road, 105-50C
1135 Webster, NY 14580
1137 EMail: jslein@crt.xerox.com
1139 Jim Whitehead
1140 UC Santa Cruz, Dept. of Computer Science
1141 1156 High Street
1142 Santa Cruz, CA 95064
1143 US
1145 EMail: ejw@cse.ucsc.edu
1146 Jason Crawford
1147 IBM Research
1148 P.O. Box 704
1149 Yorktown Heights, NY 10598
1151 EMail: ccjason@us.ibm.com
1153 Julian F. Reschke
1154 greenbytes GmbH
1155 Salzmannstrasse 152
1156 Muenster, NW 48159
1157 Germany
1159 Phone: +49 251 2807760
1160 Fax: +49 251 2807761
1161 EMail: julian.reschke@greenbytes.de
1162 URI: http://greenbytes.de/tech/webdav/
1164 A Extensions to the WebDAV Document Type Definition
1166
1167
1168
1169
1170
1171
1172
1173
1174
1176 B Change Log
1178 B.1 Since draft-ietf-webdav-ordering-protocol dated December 1999
1180 Updated contact information for all previous authors.
1181 Specify charset when using text/xml media type.
1182 Made sure artwork fits into 72 columns.
1183 Removed "Public" header from OPTIONS example.
1184 Added Julian Reschke to list of authors.
1185 Fixed broken XML in PROPFIND example and added DAV:orderingtype to
1186 list of requested properties.
1187 Added support for DAV:supported-live-property-set and DAV:supported-
1188 method-set as mandatory features.
1190 B.2 Since draft-ietf-webdav-ordering-protocol-02
1192 Updated change log to refer to expired draft version as "December
1193 1999" version.
1194 Started rewrite marshalling in RFC3253-style and added precondition
1195 and postcondition definitions.
1196 On his request, removed Geoff Clemm's name from the author list
1197 (moved to Acknowledgments).
1198 Renamed "References" to "Normative References".
1199 Removed reference to "MKREF" method.
1201 B.3 Since draft-ietf-webdav-ordering-protocol-03
1203 Added a set of issues regarding marshalling.
1204 Changed host names to use proper "example" domain names (no change
1205 tracking). Fixed host/destination header conflicts. Fixed "allow"
1206 header (multiline). Removed irrelevant response headers. Abbreviated
1207 some URIs (no change tracking).
1208 Removed Jim Davis and Chuck Fay from the author list (and added them
1209 to the Acknowledgements section).
1210 Updated section on setting the position when adding new members,
1211 removed old section on Position header.
1212 Started work on Index section.
1213 Changed structure for section 7 (no change tracking).
1214 Removed header and XML elements section (contents moved to other
1215 sections).
1216 Started new section on relation to versioned collections as per
1217 RFC3253.
1218 Do not return 424's for in ORDERPATCH multistatus (it's atomic
1219 anyway).
1221 B.4 Since draft-ietf-webdav-ordering-protocol-04
1223 Added proper reference to definition of "Coded-URL".
1224 Closed issue ordering-type-values (content model simplified and XML
1225 element / DAV property renamed) and updated examples.
1226 Renamed precondition DAV:orderingtype-set to DAV:ordering-type-set
1227 (no change tracking).
1228 Closed issue ordered-header-name (header name changed to "ordering-
1229 type", contents matches live property).
1230 Closed issue ordermember-format (now takes segment instead of href).
1231 Renamed compliance class to "ordered-collections" for consistency
1232 with newer specs, and to allow detection of compliance to final
1233 version of spec.
1234 Updated reference to XML spec to 1.0, 2nd edition.
1236 B.5 Since draft-ietf-webdav-ordering-protocol-05
1238 Typos fixed.
1239 Renamed DAV:ordermember to DAV:order-member.
1240 Made RFC3253-compatible pre/postcondition handling a MUST
1241 requirement.
1242 Reference definition of "protected property" from RFC3253.
1243 Added explanation of role of DTD fragments to Notation section.
1244 Clarified semantics for operations on versioned collections and
1245 collection versions.
1247 Index
1249 C
1251 Client-Maintained Ordering
1252 3
1254 D
1256 DAV:collection-must-be-ordered precondition
1257 6.1
1258 DAV:custom ordering type
1259 4.1.1
1260 DAV:initialize-collection-version-ordering-type
1261 9.2
1262 DAV:initialize-ordering-type
1263 9.3
1264 DAV:initialize-version-controlled-bindings-ordered postcondition
1265 9.2
1266 DAV:initialize-version-history-bindings-ordered
1267 9.3
1268 DAV:ordered-collections-supported precondition
1269 5.1
1270 DAV:ordering-modified postcondition
1271 7
1272 DAV:ordering-type property
1273 4.1.1
1274 DAV:ordering-type-set postcondition
1275 5.1, 7
1276 DAV:position-set postcondition
1277 6.1
1278 DAV:segment-must-identify-member precondition
1279 6.1
1280 DAV:unordered ordering type
1281 4.1.1
1282 DAV:update-version-controlled-collection-members-ordered
1283 9.4
1284 DAV:update-version-ordering-type
1285 9.4
1287 H
1289 Headers
1290 Ordering-Type 5.1
1292 O
1294 Ordered Collection
1295 3
1296 Ordering-Type header
1297 5.1
1298 ORDERPATCH method
1299 7
1301 P
1303 Postconditions
1304 DAV:ordering-type-set 5.1, 7
1305 DAV:position-set 6.1
1306 DAV:ordering-type-set 5.1, 7
1307 DAV:ordering-modified 7
1308 DAV:initialize-version-controlled-bindings-ordered 9.2
1309 DAV:initialize-collection-version-ordering-type 9.2
1310 DAV:initialize-version-history-bindings-ordered 9.3
1311 DAV:initialize-ordering-type 9.3
1312 DAV:update-version-controlled-collection-members-ordered 9.4
1313 DAV:update-version-ordering-type 9.4
1315 Preconditions
1316 DAV:ordered-collections-supported 5.1
1317 DAV:collection-must-be-ordered 6.1
1318 DAV:segment-must-identify-member 6.1
1320 Protected properties
1321 DAV:ordering-type 4.1.1
1323 S
1325 Server-Maintained Ordering
1326 3
1328 U
1330 Unordered Collection
1331 3
1333 Full Copyright Statement
1335 Copyright (C) The Internet Society (2003). All Rights Reserved.
1337 This document and translations of it may be copied and furnished
1338 to others, and derivative works that comment on or otherwise
1339 explain it or assist in its implementation may be prepared,
1340 copied, published and distributed, in whole or in part, without
1341 restriction of any kind, provided that the above copyright notice
1342 and this paragraph are included on all such copies and derivative
1343 works. However, this document itself may not be modified in any
1344 way, such as by removing the copyright notice or references to the
1345 Internet Society or other Internet organizations, except as needed
1346 for the purpose of developing Internet standards in which case the
1347 procedures for copyrights defined in the Internet Standards
1348 process must be followed, or as required to translate it into
1349 languages other than English.
1351 The limited permissions granted above are perpetual and will not
1352 be revoked by the Internet Society or its successors or assigns.
1354 This document and the information contained herein is provided on
1355 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
1356 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
1357 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
1358 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1359 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1361 Acknowledgement
1363 Funding for the RFC editor function is currently provided by the
1364 Internet Society.