idnits 2.17.1
draft-ietf-webdav-ordering-protocol-10.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 (August 8, 2003) is 7566 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: February 6, 2004 J. Reschke, Ed.
5 greenbytes
6 August 8, 2003
8 WebDAV Ordered Collections Protocol
9 draft-ietf-webdav-ordering-protocol-10
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 February 6, 2004.
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 6.3 Examples: Renaming a member of an ordered collection . . . . 13
71 7. Changing a Collection Ordering: ORDERPATCH method . . . . . 14
72 7.1 Example: Changing a Collection Ordering . . . . . . . . . . 16
73 7.2 Example: Failure of an ORDERPATCH Request . . . . . . . . . 17
74 8. Listing the Members of an Ordered Collection . . . . . . . . 19
75 8.1 Example: PROPFIND on an Ordered Collection . . . . . . . . . 19
76 9. Relationship to versioned collections . . . . . . . . . . . 23
77 9.1 Collection Version Properties . . . . . . . . . . . . . . . 23
78 9.1.1 Additional semantics for
79 DAV:version-controlled-binding-set (protected) . . . . . . . 23
80 9.1.2 DAV:ordering-type (protected) . . . . . . . . . . . . . . . 23
81 9.2 Additional CHECKIN semantics . . . . . . . . . . . . . . . . 23
82 9.3 Additional CHECKOUT Semantics . . . . . . . . . . . . . . . 24
83 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics . . . . . 24
84 10. Capability Discovery . . . . . . . . . . . . . . . . . . . . 25
85 10.1 Example: Using OPTIONS for the Discovery of Support for
86 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . 25
87 10.2 Example: Using Live Properties for the Discovery of
88 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . 26
89 11. Security Considerations . . . . . . . . . . . . . . . . . . 28
90 11.1 Denial of Service and DAV:ordering-type . . . . . . . . . . 28
91 12. Internationalization Considerations . . . . . . . . . . . . 29
92 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . 30
93 14. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 31
94 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 32
95 Normative References . . . . . . . . . . . . . . . . . . . . 33
96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 33
97 A. Extensions to the WebDAV Document Type Definition . . . . . 35
98 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
99 Intellectual Property and Copyright Statements . . . . . . . 38
101 1. Notational Conventions
103 Since this document describes a set of extensions to the WebDAV
104 Distributed Authoring Protocol [RFC2518], itself an extension to the
105 HTTP/1.1 protocol, the augmented BNF used here to describe protocol
106 elements is exactly the same as described in Section 2.1 of HTTP
107 [RFC2616]. Since this augmented BNF uses the basic production rules
108 provided in Section 2.2 of HTTP, these rules apply to this document
109 as well.
111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
113 document are to be interpreted as described in [RFC2119].
115 This document uses XML DTD fragments as a purely notational
116 convention. WebDAV request and response bodies can not be validated
117 due to the specific extensibility rules defined in section 23 of
118 [RFC2518] and due to the fact that all XML elements defined by this
119 specification use the XML namespace name "DAV:". In particular:
121 1. element names use the "DAV:" namespace,
123 2. element ordering is irrelevant,
125 3. extension elements (elements not already defined as valid child
126 elements) may be added anywhere, except when explicitly stated
127 otherwise,
129 4. extension attributes (attributes not already defined as valid for
130 this element) may be added anywhere, except when explicitly
131 stated otherwise.
133 2. Introduction
135 This specification builds on the collection infrastructure provided
136 by the WebDAV Distributed Authoring Protocol, adding support for the
137 server-side ordering of collection members.
139 There are many scenarios where it is useful to impose an ordering on
140 a collection at the server, such as expressing a recommended access
141 order, or a revision history order. The members of a collection
142 might represent the pages of a book, which need to be presented in
143 order if they are to make sense. Or an instructor might create a
144 collection of course readings, which she wants to be displayed in the
145 order they are to be read.
147 Orderings may be based on property values, but this is not always the
148 case. The resources in the collection may not have properties that
149 can be used to support the desired ordering. Orderings based on
150 properties can be obtained using a search protocol's ordering option,
151 but orderings not based on properties cannot. These orderings
152 generally need to be maintained by a human user.
154 The ordering protocol defined here focuses on support for such
155 human-maintained orderings. Its protocol elements allow clients to
156 specify the position of each collection member in the collection's
157 ordering, as well as the semantics governing the ordering. The
158 protocol is designed to allow support to be added in the future for
159 orderings that are maintained automatically by the server.
161 The remainder of this document is structured as follows: Section 3
162 defines terminology that will be used throughout the specification.
163 Section 4 provides an overview of ordered collections. Section 5
164 describes how to create an ordered collection, and Section 6
165 discusses how to set a member's position in the ordering of a
166 collection. Section 7 explains how to change a collection ordering.
167 Section 8 discusses listing the members of an ordered collection.
168 Section 9 discusses the impact on version-controlled collections (as
169 defined in [RFC3253]. Section 10 describes capability discovery.
170 Section 11 through Section 13 discuss security, internationalization,
171 and IANA considerations. The remaining sections provide supporting
172 information.
174 3. Terminology
176 The terminology used here follows that in [RFC2518] and [RFC3253].
177 Definitions of the terms resource, Uniform Resource Identifier (URI),
178 and Uniform Resource Locator (URL) are provided in [RFC2396].
180 Ordered Collection
182 A collection for which the results from a PROPFIND request are
183 guaranteed to be in the order specified for that collection
185 Unordered Collection
187 A collection for which the client cannot depend on the
188 repeatability of the ordering of results from a PROPFIND request
190 Client-Maintained Ordering
192 An ordering of collection members that is maintained on the server
193 based on client requests specifying the position of each
194 collection member in the ordering
196 Server-Maintained Ordering
198 An ordering of collection members that is maintained automatically
199 by the server, based on a client's choice of ordering semantics
201 Ordering Semantics
203 In general, ordering semantics are the set of structures or
204 meanings applied to the ordering of the member of a specific
205 collection. Within this document, "ordering semantics" refers
206 specifically to the structure specified in the DAV:ordering-type
207 property. See Section 4.1.1 for more information on
208 DAV:ordering-type.
210 This document uses the terms "precondition", "postcondition" and
211 "protected property" as defined in [RFC3253]. Servers MUST report
212 pre-/postcondition failures as described in section 1.6 of this
213 document.
215 4. Overview of Ordered Collections
217 If a collection is unordered, the client cannot depend on the
218 repeatability of the ordering of results from a PROPFIND request. By
219 specifying an ordering for a collection, a client requires the server
220 to follow that ordering whenever it responds to a PROPFIND request on
221 that collection.
223 Server-side orderings may be client-maintained or server-maintained.
224 For client-maintained orderings, a client must specify the ordering
225 position of each of the collection's members, either when the member
226 is added to the collection (using the Position header (Section 6)) or
227 later (using the ORDERPATCH (Section 7) method). For
228 server-maintained orderings, the server automatically positions each
229 of the collection's members according to the ordering semantics.
230 This specification supports only client-maintained orderings, but is
231 designed to allow future extension to server-maintained orderings.
233 A collection that supports ordering is not required to be ordered.
235 If a collection is ordered, each of its internal member URIs MUST be
236 in the ordering exactly once, and the ordering MUST NOT include any
237 URI that is not an internal member of the collection. The server is
238 responsible for enforcing these constraints on orderings. The server
239 MUST remove an internal member URI from the ordering when it is
240 removed from the collection. Removing an internal member MUST NOT
241 affect the ordering of the remaining internal members. The server
242 MUST add an internal member URI to the ordering when it is added to
243 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.
267 This property cannot be set using PROPPATCH. Its value can only be
268 set by 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 not being
277 advertised.
279 DAV:unordered The value DAV:unordered indicates that the collection
280 is not ordered. That is, the client cannot depend on the
281 repeatability of the ordering of results from a 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
354 client-maintained ordering. As new members are added to the
355 collection, clients or end users can use the semantics to determine
356 where to 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 Note to implementors: this specification does not mandate a
382 specific implementation of MOVE operations within the same parent
383 collection. Therefore, servers may either implement this as a
384 simple rename operation (preserving the collection member's
385 position), or as a sequence of "remove" and "add" (causing the
386 semantics of "adding a new member" to apply). Future revisions of
387 this specification may specify this behaviour more precisely based
388 on future implementation experience.
390 Additional Marshalling:
392 Position = "Position" ":" ("first" | "last" |
393 (("before" | "after") segment))
395 segment is defined in Section 3.3 of [RFC2396].
397 The segment is interpreted relative to the collection to which the
398 new member is being added.
400 When the Position header is present, the server MUST insert the
401 new member into the ordering at the specified location.
403 The "first" keyword indicates the new member is put in the
404 beginning position in the collection's ordering, while "last"
405 indicates the new member is put in the final position in the
406 collection's ordering. The "before" keyword indicates the new
407 member is added to the collection's ordering immediately prior to
408 the position of the member identified in the segment. Likewise,
409 the "after" keyword indicates the new member is added to the
410 collection's ordering immediately following the position of the
411 member identified in the segment.
413 If the request is replacing an existing resource, and the Position
414 header is present, the server MUST remove the internal member URI
415 from its previous position, and then insert it at the requested
416 position.
418 Additional Preconditions:
420 (DAV:collection-must-be-ordered): the target collection MUST be
421 ordered.
423 (DAV:segment-must-identify-member): the referenced segment MUST
424 identify a resource that exists and is different from the affected
425 resource.
427 Additional Postconditions:
429 (DAV:position-set): if a Position header was present, the request
430 MUST have created the new collection member at the specified
431 position.
433 6.2 Examples: Setting the Position of a Collection Member
435 >> Request:
437 COPY /~user/dav/spec08.html HTTP/1.1
438 Host: example.org
439 Destination: http://example.org/~slein/dav/spec08.html
440 Position: after requirements.html
442 >> Response:
444 HTTP/1.1 201 Created
446 This request resulted in the creation of a new resource at
447 example.org/~slein/dav/spec08.html. The Position header in this
448 example caused the server to set its position in the ordering of the
449 /~slein/dav/ collection immediately after requirements.html.
451 >> Request:
453 MOVE /i-d/draft-webdav-prot-08.txt HTTP/1.1
454 Host: example.org
455 Destination: http://example.org/~user/dav/draft-webdav-prot-08.txt
456 Position: first
458 >> Response:
460 HTTP/1.1 409 Conflict
461 Content-Type: text/xml; charset="utf-8"
462 Content-Length: xxxx
464
465
466
467
469 In this case, the server returned a 409 (Conflict) status code
470 because the /~user/dav/ collection is an unordered collection.
471 Consequently, the server was unable to satisfy the Position header.
473 6.3 Examples: Renaming a member of an ordered collection
475 The following sequence of requests will rename a collection member
476 while preserving it's position, independantly of how the server
477 implements the MOVE operation:
479 1. PROPFIND collection with depth 1, retrieving the
480 DAV:ordering-type property (an interactive client likely already
481 has done this in order to display the collection's content)
483 2. If the DAV:ordering-type property is present and doesn't equal
484 "dav:unordered" (thus if the collection is ordered), determine
485 current position (such as "first" or "after x") and setup
486 Position header accordingly.
488 3. Perform the MOVE operation, optionally supplying the Position
489 header computed in the previous step.
491 7. Changing a Collection Ordering: ORDERPATCH method
493 The ORDERPATCH method is used to change the ordering semantics of a
494 collection or to change the order of the collection's members in the
495 ordering or both.
497 The server MUST apply the changes in the order they appear in the
498 order XML element. The server MUST either apply all the changes or
499 apply none of them. If any error occurs during processing, all
500 executed changes MUST be undone and a proper error result returned.
502 If an ORDERPATCH request changes the ordering semantics, but does not
503 completely specify the order of the collection members, the server
504 MUST assign a position in the ordering to each collection member for
505 which a position was not specified. These server-assigned positions
506 MUST all follow the last one specified by the client. The result is
507 that all members for which the client specified a position are at the
508 beginning of the ordering, followed by any members for which the
509 server assigned positions. Note that the ordering of the
510 server-assigned positions is not defined by this document, therefore
511 servers can use whatever rule seems reasonable (for instance,
512 alphabetically or by creation date).
514 If an ORDERPATCH request does not change the ordering semantics, any
515 member positions not specified in the request MUST remain unchanged.
517 A request to reposition a collection member at the same place in the
518 ordering is not an error.
520 If an ORDERPATCH request fails, the server state preceding the
521 request MUST be restored.
523 Additional Marshalling:
525 The request body MUST be DAV:orderpatch element.
527
529
530
531
532
533
534
535
536 PCDATA value: segment, as defined in section 3.3 of [RFC2396].
538 The DAV:ordering-type property is modified according to the
539 DAV:ordering-type element.
541 The ordering of internal member URIs in the collection identified
542 by the Request-URI is changed based on instructions in the
543 order-member XML elements in the order they appear in the request.
544 The order-member XML elements identify the internal member URIs
545 whose positions are to be changed, and describe their new
546 positions in the ordering. Each new position can be specified as
547 first in the ordering, last in the ordering, immediately before
548 some other internal member URI, or immediately after some other
549 internal member URI.
551 If a response body for a successful request is included, it MUST
552 be a DAV:orderpatch-response XML element. Note that this document
553 does not define any elements for the ORDERPATCH response body, but
554 the DAV:orderpatch-response element is defined to ensure
555 interoperability between future extensions that do define elements
556 for the ORDERPATCH response body.
558
560 Since multiple changes can be requested in a single ORDERPATCH
561 request, if any problems are encountered, the server MUST return a
562 207 (Multi-Status) response (defined in [RFC2518]), containing
563 DAV:response elements for either the request-URI (when the
564 DAV:ordering-type could not be modified) or URIs of collection
565 members to be repositioned (when an individual positioning request
566 expressed as DAV:order-member could not be fulfilled).
568 Preconditions:
570 (DAV:collection-must-be-ordered): see Section 6.1.
572 (DAV:segment-must-identify-member): see Section 6.1.
574 Postconditions:
576 (DAV:ordering-type-set): if the request body contained a
577 DAV:ordering-type element, the request MUST have set the
578 DAV:ordering-type property of the collection to the value
579 specified in the request.
581 (DAV:ordering-modified): if the request body contained
582 DAV:order-member elements, the request MUST have set the ordering
583 of internal member URIs in the collection identified by the
584 request-URI based on the instructions in the DAV:order-member
585 elements.
587 7.1 Example: Changing a Collection Ordering
589 Consider an ordered collection /coll-1, with bindings ordered as
590 follows:
592 three.html
593 four.html
594 one.html
595 two.html
597 >> Request:
599 ORDERPATCH /coll-1/ HTTP/1.1
600 Host: example.org
601 Content-Type: text/xml; charset="utf-8"
602 Content-Length: xxx
604
605
606
607 http://example.org/inorder.ord
608
609
610 two.html
611
612
613
614 one.html
615
616
617
618 three.html
619
620
621
622 four.html
623
624
625
627 >> Response:
629 HTTP/1.1 200 OK
630 In this example, after the request has been processed, the
631 collection's ordering semantics are identified by the URI http://
632 example.org/inorder.ord. The value of the collection's
633 DAV:ordering-type property has been set to this URI. The request also
634 contains instructions for changing the positions of the collection's
635 internal member URIs in the ordering to comply with the new ordering
636 semantics. As the DAV:order-member elements are required to be
637 processed in the order they appear in the request, two.html is moved
638 to the beginning of the ordering, and then one.html is moved to the
639 beginning of the ordering. Then three.html is moved to the end of
640 the ordering, and finally four.html is moved to the end of the
641 ordering. After the request has been processed, the collection's
642 ordering is as follows:
644 one.html
645 two.html
646 three.html
647 four.html
649 7.2 Example: Failure of an ORDERPATCH Request
651 Consider a collection /coll-1/ with members ordered as follows:
653 nunavut.map
654 nunavut.img
655 baffin.map
656 baffin.desc
657 baffin.img
658 iqaluit.map
659 nunavut.desc
660 iqaluit.img
661 iqaluit.desc
663 >> Request:
665 ORDERPATCH /coll-1/ HTTP/1.1
666 Host: www.nunanet.com
667 Content-Type: text/xml; charset="utf-8"
668 Content-Length: xxx
670
671
672
673 nunavut.desc
674
675
676 nunavut.map
678
679
680
681
682 iqaluit.map
683
684
685 pangnirtung.img
686
687
688
689
691 >> Response:
693 HTTP/1.1 207 Multi-Status
694 Content-Type: text/xml; charset="utf-8"
695 Content-Length: xxx
697
698
699
700 http://www.nunanet.com/coll-1/iqaluit.map
701 HTTP/1.1 403 Forbidden
702
703
704 pangnirtung.img is not a collection member.
705
706
707
709 In this example, the client attempted to position iqaluit.map after a
710 URI that is not an internal member of the collection /coll-1/. The
711 server responded to this client error with a 403 (Forbidden) status
712 code, indicating the failed precondition
713 DAV:segment-must-identify-member. Because ORDERPATCH is an atomic
714 method, the request to reposition nunavut.desc (which would otherwise
715 have succeeded) failed as well, but doesn't need to be expressed in
716 the multistatus response body.
718 8. Listing the Members of an Ordered Collection
720 A PROPFIND request is used to retrieve a listing of the members of an
721 ordered collection, just as it is used to retrieve a listing of the
722 members of an unordered collection.
724 However, when responding to a PROPFIND on an ordered collection, the
725 server MUST order the response elements according to the ordering
726 defined on the collection. If a collection is unordered, the client
727 cannot depend on the repeatability of the ordering of results from a
728 PROPFIND request.
730 In a response to a PROPFIND with Depth: infinity, members of
731 different collections may be interleaved. That is, the server is not
732 required to do a breadth-first traversal. The only requirement is
733 that the members of any ordered collection appear in the order
734 defined for the collection. Thus for the hierarchy illustrated in
735 the following figure, where collection A is an ordered collection
736 with the ordering B C D,
738 A
739 /|\
740 / | \
741 B C D
742 / /|\
743 E F G H
745 it would be acceptable for the server to return response elements in
746 the order A B E C F G H D or "A B E C H G F D" as well (if C is
747 unordered).. In this response, B, C, and D appear in the correct
748 order, separated by members of other collections. Clients can use a
749 series of Depth: 1 PROPFIND requests to avoid the complexity of
750 processing Depth: infinity responses based on depth-first traversals.
752 8.1 Example: PROPFIND on an Ordered Collection
754 Suppose a PROPFIND request is submitted to /MyColl/, which has its
755 members ordered as follows.
757 /MyColl/
758 lakehazen.html
759 siorapaluk.html
760 iqaluit.html
761 newyork.html
763 >> Request:
765 PROPFIND /MyColl/ HTTP/1.1
766 Host: example.org
767 Depth: 1
768 Content-Type: text/xml; charset="utf-8"
769 Content-Length: xxxx
771
772
773
774
775
776
777
778
780 >> Response:
782 HTTP/1.1 207 Multi-Status
783 Content-Type: text/xml; charset="utf-8"
784 Content-Length: xxxx
786
787
789
790 http://example.org/MyColl/
791
792
793
794 DAV:custom
795
796
797
798 HTTP/1.1 200 OK
799
800
801
802
803
804 HTTP/1.1 404 Not Found
805
806
807
808 http://example.org/MyColl/lakehazen.html
809
810
811
812 82N
813
814 HTTP/1.1 200 OK
815
816
817
818
819
820 HTTP/1.1 404 Not Found
821
822
823
824 http://example.org/MyColl/siorapaluk.html
826
827
828
829 78N
830
831 HTTP/1.1 200 OK
832
833
834
835
836
837 HTTP/1.1 404 Not Found
838
839
840
841 http://example.org/MyColl/iqaluit.html
842
843
844
845 62N
846
847 HTTP/1.1 200 OK
848
849
850
851
852
853 HTTP/1.1 404 Not Found
854
855
856
857 http://example.org/MyColl/newyork.html
858
859
860
861 45N
863
864 HTTP/1.1 200 OK
865
866
867
868
869 HTTP/1.1 404 Not Found
870
871
872
873
875 In this example, the server responded with a list of the collection
876 members in the order defined for the collection.
878 9. Relationship to versioned collections
880 The Versioning Extensions to WebDAV [RFC3253] introduce the concept
881 of versioned collections, recording both the dead properties and the
882 set of internal version-controlled bindings. This section defines how
883 this feature interacts with ordered collections.
885 This specification considers both the ordering type
886 (DAV:ordering-type property) and the ordering of collection members
887 to be part of the state of a collection. Therefore both MUST be
888 recorded upon CHECKIN or VERSION-CONTROL, and both MUST be restored
889 upon CHECKOUT, UNCHECKOUT or UPDATE (where for compatibility with
890 RFC3253, only the ordering of version-controlled members needs to be
891 maintained).
893 9.1 Collection Version Properties
895 9.1.1 Additional semantics for DAV:version-controlled-binding-set
896 (protected)
898 For ordered collections, the DAV:version-controlled-binding elements
899 MUST appear in the ordering defined for the checked-in ordered
900 collection.
902 9.1.2 DAV:ordering-type (protected)
904 The DAV:ordering-type property records the DAV:ordering-type property
905 of the checked-in ordered collection.
907 9.2 Additional CHECKIN semantics
909 Additional Postconditions:
911 (DAV:initialize-version-controlled-bindings-ordered): If the
912 request-URL identified a both ordered and version-controlled
913 collection, then the child elements of
914 DAV:version-controlled-binding-set of the new collection version
915 MUST appear in the ordering defined for that collection.
917 (DAV:initialize-collection-version-ordering-type): If the
918 request-URL identified a both ordered and version-controlled
919 collection, then the DAV:ordering-type property of the new
920 collection version MUST be a copy of the collection's
921 DAV:ordering-type property.
923 9.3 Additional CHECKOUT Semantics
925 Additional Postconditions:
927 (DAV:initialize-version-history-bindings-ordered): If the request
928 has been applied to a collection version with a DAV:ordering-type
929 other than "DAV:unordered", the bindings in the new working
930 collection MUST be ordered according to the collection version's
931 DAV:version-controlled-binding-set property.
933 (DAV:initialize-ordering-type): If the request has been applied to
934 a collection version, the DAV:ordering-type property of the new
935 working collection MUST be initialized from the collection
936 version's DAV:ordering-type property.
938 9.4 Additional UNCHECKOUT, UPDATE, and MERGE Semantics
940 Additional Postconditions:
942 (DAV:update-version-controlled-collection-members-ordered): If the
943 request modified the DAV:checked-in version of a
944 version-controlled collection and the DAV:ordering-type for the
945 checked-in version is not unordered ("DAV:unordered"), the
946 version-controlled members MUST be ordered according to the
947 checked-in version's DAV:version-controlled-binding-set property.
948 The ordering of non-version-controlled members is server-defined.
950 (DAV:update-version-ordering-type): If the request modified the
951 DAV:checked-in version of a version-controlled collection, the
952 DAV:ordering-type property MUST be updated from the checked-in
953 version's property.
955 10. Capability Discovery
957 Sections 9.1 and 15 of [RFC2518] describe the use of compliance
958 classes with the DAV header in responses to OPTIONS, to indicate
959 which parts of the Web Distributed Authoring protocols the resource
960 supports. This specification defines an OPTIONAL extension to
961 [RFC2518]. It defines a new compliance class, called
962 ordered-collections, for use with the DAV header in responses to
963 OPTIONS requests. If a collection resource does support ordering,
964 its response to an OPTIONS request may indicate that it does, by
965 listing the new ORDERPATCH method as one it supports, and by listing
966 the new ordered-collections compliance class in the DAV header.
968 When responding to an OPTIONS request, only a collection or a null
969 resource can include ordered-collections in the value of the DAV
970 header. By including ordered-collections, the resource indicates
971 that its internal member URIs can be ordered. It implies nothing
972 about whether any collections identified by its internal member URIs
973 can be ordered.
975 Furthermore, RFC 3253 [RFC3253] introduces the live properties
976 DAV:supported-method-set (section 3.1.3) and
977 DAV:supported-live-property-set (section 3.1.4). Servers MUST support
978 these properties as defined in RFC 3253.
980 10.1 Example: Using OPTIONS for the Discovery of Support for Ordering
982 >> Request:
984 OPTIONS /somecollection/ HTTP/1.1
985 Host: example.org
987 >> Response:
989 HTTP/1.1 200 OK
990 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
991 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH
992 DAV: 1, 2, ordered-collections
994 The DAV header in the response indicates that the resource /
995 somecollection/ is level 1 and level 2 compliant, as defined in
996 [RFC2518]. In addition, /somecollection/ supports ordering. The
997 Allow header indicates that ORDERPATCH requests can be submitted to /
998 somecollection/.
1000 10.2 Example: Using Live Properties for the Discovery of Ordering
1002 >> Request:
1003 PROPFIND /somecollection HTTP/1.1
1004 Depth: 0
1005 Content-Type: text/xml; charset="utf-8"
1006 Content-Length: xxx
1008
1009
1010
1011
1012
1013
1014
1016 >> Response:
1017 HTTP/1.1 207 Multi-Status
1018 Content-Type: text/xml; charset="utf-8"
1019 Content-Length: xxx
1021
1022
1023
1024 http://example.org/somecollection
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051 HTTP/1.1 200 OK
1052
1053
1054
1056 Note that actual responses MUST contain a complete list of supported
1057 live properties.
1059 11. Security Considerations
1061 This section is provided to make WebDAV applications aware of the
1062 security implications of this protocol.
1064 All of the security considerations of HTTP/1.1 and the WebDAV
1065 Distributed Authoring Protocol specification also apply to this
1066 protocol specification. In addition, ordered collections introduce a
1067 new security concern. This issue is detailed here.
1069 11.1 Denial of Service and DAV:ordering-type
1071 There may be some risk of denial of service at sites that are
1072 advertised in the DAV:ordering-type property of collections.
1073 However, it is anticipated that widely-deployed applications will use
1074 hard-coded values for frequently-used ordering semantics rather than
1075 looking up the semantics at the location specified by
1076 DAV:ordering-type. This risk will be further reduced if clients
1077 observe the recommendation of Section 5.1 that they not send requests
1078 to the URI in DAV:ordering-type.
1080 12. Internationalization Considerations
1082 This specification follows the practices of [RFC2518] in encoding all
1083 human-readable content using [XML] and in the treatment of names.
1084 Consequently, this specification complies with the IETF Character Set
1085 Policy [RFC2277].
1087 WebDAV applications MUST support the character set tagging, character
1088 set encoding, and the language tagging functionality of the XML
1089 specification. This constraint ensures that the human-readable
1090 content of this specification complies with [RFC2277].
1092 As in [RFC2518], names in this specification fall into three
1093 categories: names of protocol elements such as methods and headers,
1094 names of XML elements, and names of properties. Naming of protocol
1095 elements follows the precedent of HTTP, using English names encoded
1096 in USASCII for methods and headers. The names of XML elements used
1097 in this specification are English names encoded in UTF-8.
1099 For error reporting, [RFC2518] follows the convention of HTTP/1.1
1100 status codes, including with each status code a short, English
1101 description of the code (e.g., 423 Locked). Internationalized
1102 applications will ignore this message, and display an appropriate
1103 message in the user's language and character set.
1105 This specification introduces no new strings that are displayed to
1106 users as part of normal, error-free operation of the protocol.
1108 For rationales for these decisions and advice for application
1109 implementors, see [RFC2518].
1111 13. IANA Considerations
1113 This document uses the namespaces defined by [RFC2518] for properties
1114 and XML elements. All other IANA considerations mentioned in
1115 [RFC2518] also apply to this document.
1117 14. Contributors
1119 This document has benefited from significant contributions from Geoff
1120 Clemm, Jason Crawford, Jim Davis, Chuck Fay and Judith Slein.
1122 15. Acknowledgements
1124 This document has benefited from thoughtful discussion by Jim Amsden,
1125 Steve Carter, Tyson Chihaya, Ken Coar, Ellis Cohen, Bruce Cragun,
1126 Spencer Dawkins, Mark Day, Rajiv Dulepet, David Durand, Lisa
1127 Dusseault, Roy Fielding, Yaron Goland, Fred Hitt, Alex Hopmann,
1128 Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, Daniel
1129 LaLiberte, Steve Martin, Larry Masinter, Jeff McAffer, Surendra
1130 Koduru Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness,
1131 John Stracke, John Tigue, John Turner, Kevin Wiggen, and others.
1133 Normative References
1135 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1136 Requirement Levels", BCP 14, RFC 2119, March 1997.
1138 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
1139 Languages", BCP 18, RFC 2277, January 1998.
1141 [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
1142 Resource Identifiers (URI): Generic Syntax", RFC 2396,
1143 August 1998.
1145 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D.
1146 Jensen, "HTTP Extensions for Distributed Authoring --
1147 WEBDAV", RFC 2518, February 1999.
1149 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1150 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext
1151 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1153 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and J.
1154 Whitehead, "Versioning Extensions to WebDAV", RFC 3253,
1155 March 2002.
1157 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
1158 "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C
1159 REC-xml, October 2000, .
1162 [1]
1164 [2]
1166 Authors' Addresses
1168 Jim Whitehead
1169 UC Santa Cruz, Dept. of Computer Science
1170 1156 High Street
1171 Santa Cruz, CA 95064
1172 US
1174 EMail: ejw@cse.ucsc.edu
1175 Julian F. Reschke (editor)
1176 greenbytes GmbH
1177 Salzmannstrasse 152
1178 Muenster, NW 48159
1179 Germany
1181 Phone: +49 251 2807760
1182 Fax: +49 251 2807761
1183 EMail: julian.reschke@greenbytes.de
1184 URI: http://greenbytes.de/tech/webdav/
1186 Appendix A. Extensions to the WebDAV Document Type Definition
1188
1189
1190
1191
1192
1193
1194
1195
1196
1198 Index
1200 C
1201 Client-Maintained Ordering 6
1203 D
1204 DAV:collection-must-be-ordered precondition 12
1205 DAV:custom ordering type 8
1206 DAV:initialize-collection-version-ordering-type 23
1207 DAV:initialize-ordering-type 24
1208 DAV:initialize-version-controlled-bindings-ordered postcondition 23
1209 DAV:initialize-version-history-bindings-ordered 24
1210 DAV:ordered-collections-supported precondition 9
1211 DAV:ordering-modified postcondition 15
1212 DAV:ordering-type property 7
1213 DAV:ordering-type-set postcondition 9, 15
1214 DAV:position-set postcondition 12
1215 DAV:segment-must-identify-member precondition 12
1216 DAV:unordered ordering type 8
1217 DAV:update-version-controlled-collection-members-ordered 24
1218 DAV:update-version-ordering-type 24
1220 H
1221 Headers
1222 Ordering-Type 9
1224 O
1225 Ordered Collection 6
1226 Ordering Semantics 6
1227 Ordering-Type header 9
1228 ORDERPATCH method 14
1230 P
1231 Postconditions
1232 DAV:initialize-collection-version-ordering-type 23
1233 DAV:initialize-ordering-type 24
1234 DAV:initialize-version-controlled-bindings-ordered 23
1235 DAV:initialize-version-history-bindings-ordered 24
1236 DAV:ordering-modified 15
1237 DAV:ordering-type-set 9, 15
1238 DAV:position-set 12
1239 DAV:update-version-controlled-collection-members-ordered 24
1240 DAV:update-version-ordering-type 24
1241 Preconditions
1242 DAV:collection-must-be-ordered 12
1243 DAV:ordered-collections-supported 9
1244 DAV:segment-must-identify-member 12
1245 Protected properties
1246 DAV:ordering-type 7
1248 S
1249 Server-Maintained Ordering 6
1251 U
1252 Unordered Collection 6
1254 Intellectual Property Statement
1256 The IETF takes no position regarding the validity or scope of any
1257 intellectual property or other rights that might be claimed to
1258 pertain to the implementation or use of the technology described in
1259 this document or the extent to which any license under such rights
1260 might or might not be available; neither does it represent that it
1261 has made any effort to identify any such rights. Information on the
1262 IETF's procedures with respect to rights in standards-track and
1263 standards-related documentation can be found in BCP-11. Copies of
1264 claims of rights made available for publication and any assurances of
1265 licenses to be made available, or the result of an attempt made to
1266 obtain a general license or permission for the use of such
1267 proprietary rights by implementors or users of this specification can
1268 be obtained from the IETF Secretariat.
1270 The IETF invites any interested party to bring to its attention any
1271 copyrights, patents or patent applications, or other proprietary
1272 rights which may cover technology that may be required to practice
1273 this standard. Please address the information to the IETF Executive
1274 Director.
1276 Full Copyright Statement
1278 Copyright (C) The Internet Society (2003). All Rights Reserved.
1280 This document and translations of it may be copied and furnished to
1281 others, and derivative works that comment on or otherwise explain it
1282 or assist in its implementation may be prepared, copied, published
1283 and distributed, in whole or in part, without restriction of any
1284 kind, provided that the above copyright notice and this paragraph are
1285 included on all such copies and derivative works. However, this
1286 document itself may not be modified in any way, such as by removing
1287 the copyright notice or references to the Internet Society or other
1288 Internet organizations, except as needed for the purpose of
1289 developing Internet standards in which case the procedures for
1290 copyrights defined in the Internet Standards process must be
1291 followed, or as required to translate it into languages other than
1292 English.
1294 The limited permissions granted above are perpetual and will not be
1295 revoked by the Internet Society or its successors or assignees.
1297 This document and the information contained herein is provided on an
1298 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1299 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1300 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1301 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1302 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1304 Acknowledgment
1306 Funding for the RFC Editor function is currently provided by the
1307 Internet Society.