Request for Comments: 3648 U.C. Santa Cruz
Category: Standards Track J. Reschke, Ed.
greenbytes
December 2003
Web Distributed Authoring and Versioning (WebDAV)
Ordered Collections Protocol
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract
This specification extends the Web Distributed Authoring and
Versioning (WebDAV) Protocol to support the server-side ordering of
collection members. Of particular interest are orderings that are
not based on property values, and so cannot be achieved using a
search protocol’s ordering option and cannot be maintained
automatically by the server. Protocol elements are defined to let
clients specify the position in the ordering of each collection
member, as well as the semantics governing the ordering.
Table of Contents
1. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Overview of Ordered Collections . . . . . . . . . . . . . . . 5
4.1. Additional Collection properties . . . . . . . . . . . . 6
4.1.1. DAV:ordering-type (protected). . . . . . . . . . 6
5. Creating an Ordered Collection . . . . . . . . . . . . . . . . 7
5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7
5.2. Example: Creating an Ordered Collection. . . . . . . . . 8
6. Setting the Position of a Collection Member. . . . . . . . . . 8
6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8
6.2. Examples: Setting the Position of a Collection Member. . 10
6.3. Examples: Renaming a member of an ordered collection . . 10
7. Changing a Collection Ordering: ORDERPATCH method. . . . . . . 11
7.1. Example: Changing a Collection Ordering. . . . . . . . . 13
7.2. Example: Failure of an ORDERPATCH Request. . . . . . . . 14
8. Listing the Members of an Ordered Collection . . . . . . . . . 16
8.1. Example: PROPFIND on an Ordered Collection . . . . . . . 17
9. Relationship to versioned collections. . . . . . . . . . . . . 19
9.1. Collection Version Properties. . . . . . . . . . . . . . 20
9.1.1. Additional semantics for
DAV:version-controlled-binding-set (protected) . 20
9.1.2. DAV:ordering-type (protected). . . . . . . . . . 20
9.2. Additional CHECKIN semantics . . . . . . . . . . . . . . 20
9.3. Additional CHECKOUT Semantics. . . . . . . . . . . . . . 20
9.4. Additional UNCHECKOUT, UPDATE, and MERGE Semantics . . . 21
10. Capability Discovery . . . . . . . . . . . . . . . . . . . . . 21
10.1. Example: Using OPTIONS for the Discovery of Support for
Ordering . . . . . . . . . . . . . . . . . . . . . . . . 22
10.2. Example: Using Live Properties for the Discovery of
Ordering . . . . . . . . . . . . . . . . . . . . . . . . 22
11. Security Considerations. . . . . . . . . . . . . . . . . . . . 23
11.1. Denial of Service and DAV:ordering-type . . . . . . . . 23
12. Internationalization Considerations. . . . . . . . . . . . . . 24
13. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 24
14. Intellectual Property Statement. . . . . . . . . . . . . . . . 25
15. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 25
16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 25
17. Normative References . . . . . . . . . . . . . . . . . . . . . 26
A. Extensions to the WebDAV Document Type Definition. . . . . . . 27
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Authors’ Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 30
1. Notational Conventions
Since this document describes a set of extensions to the WebDAV
Distributed Authoring Protocol [RFC2518], which is itself an
extension to the HTTP/1.1 protocol, the augmented BNF used here to
describe protocol elements is exactly the same as described in
Section 2.1 of HTTP [RFC2616]. Since this augmented BNF uses the
basic production rules provided in Section 2.2 of HTTP, these rules
apply to this document as well.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
This document uses XML DTD fragments as a purely notational
convention. WebDAV request and response bodies can not be validated
due to the specific extensibility rules defined in section 23 of
[RFC2518] and due to the fact that all XML elements defined by this
specification use the XML namespace name "DAV:". In particular:
1. element names use the "DAV:" namespace,
2. element ordering is irrelevant,
3. extension elements (elements not already defined as valid child
elements) may be added anywhere, except where explicitly stated
otherwise,
4. extension attributes (attributes not already defined as valid for
this element) may be added anywhere, except where explicitly
stated otherwise.
2. Introduction
This specification builds on the collection infrastructure provided
by the WebDAV Distributed Authoring Protocol, adding support for the
server-side ordering of collection members.
There are many scenarios in which it is useful to impose an ordering
on a collection at the server, such as expressing a recommended
access order, or a revision history order. The members of a
collection might represent the pages of a book, which need to be
presented in order if they are to make sense, or an instructor might
create a collection of course readings that she wants to be displayed
in the order they are to be read.
Orderings may be based on property values, but this is not always the
case. The resources in the collection may not have properties that
can be used to support the desired ordering. Orderings based on
properties can be obtained using a search protocol’s ordering option,
but orderings not based on properties cannot. These orderings
generally need to be maintained by a human user.
The ordering protocol defined here focuses on support for such
human-maintained orderings. Its protocol elements allow clients to
specify the position of each collection member in the collection’s
ordering, as well as the semantics governing the order. The protocol
is designed to allow additional support in the future for orderings
that are maintained automatically by the server.
The remainder of this document is structured as follows: Section 3
defines terminology that will be used throughout the specification.
Section 4 provides an overview of ordered collections. Section 5
describes how to create an ordered collection, and Section 6
discusses how to set a member’s position in the ordering of a
collection. Section 7 explains how to change a collection ordering.
Section 8 discusses listing the members of an ordered collection.
Section 9 discusses the impact on version-controlled collections (as
defined in [RFC3253]). Section 10 describes capability discovery.
Sections 11 through 13 discuss security, internationalization, and
IANA considerations. The remaining sections provide supporting
information.
3. Terminology
The terminology used here follows that in [RFC2518] and [RFC3253].
Definitions of the terms resource, Uniform Resource Identifier (URI),
and Uniform Resource Locator (URL) are provided in [RFC2396].
Ordered Collection
A collection for which the results from a PROPFIND request are
guaranteed to be in the order specified for that collection.
Unordered Collection
A collection for which the client cannot depend on the
repeatability of the ordering of results from a PROPFIND request.
Client-Maintained Ordering
An ordering of collection members that is maintained on the server
based on client requests specifying the position of each
collection member in the ordering.
Server-Maintained Ordering
An ordering of collection members that is maintained automatically
by the server, based on a client’s choice of ordering semantics.
Ordering Semantics
In general, ordering semantics are the set of structures or
meanings applied to the ordering of the member of a specific
collection. Within this document, "ordering semantics" refers
specifically to the structure specified in the DAV:ordering-type
property. See Section 4.1.1 for more information on
DAV:ordering-type.
This document uses the terms "precondition", "postcondition" and
"protected property" as defined in [RFC3253]. Servers MUST report
pre-/postcondition failures as described in section 1.6 of this
document.
4. Overview of Ordered Collections
If a collection is not ordered, the client cannot depend on the
repeatability of the ordering of results from a PROPFIND request. By
specifying an ordering for a collection, a client requires the server
to follow that ordering whenever it responds to a PROPFIND request on
that collection.
Server-side orderings may be client-maintained or server-maintained.
For client-maintained orderings, a client must specify the ordering
position of each of the collection’s members, either when the member
is added to the collection (using the Position header (Section 6)) or
later (using the ORDERPATCH (Section 7) method). For server-
maintained orderings, the server automatically positions each of the
collection’s members according to the ordering semantics. This
specification supports only client-maintained orderings, but is
designed to allow the future extension with server-maintained
orderings.
A collection that supports ordering is not required to be ordered.
If a collection is ordered, each of its internal member URIs MUST
appear in the ordering exactly once, and the ordering MUST NOT
include any URIs that are not internal members of the collection.
The server is responsible for enforcing these constraints on
orderings. The server MUST remove an internal member URI from the
ordering when it is removed from the collection. Removing an
internal member MUST NOT affect the ordering of the remaining
internal members. The server MUST add an internal member URI to the
ordering when it is added to the collection.
Only one ordering can be attached to any collection. Multiple
orderings of the same resources can be achieved by creating multiple
collections referencing those resources, and attaching a different
ordering to each collection.
An ordering is considered to be part of the state of a collection
resource. Consequently, the ordering is the same no matter which URI
is used to access the collection and is protected by locks or access
control constraints on the collection.
4.1. Additional Collection properties
A DAV:allprop PROPFIND request SHOULD NOT return any of the
properties defined in this document.
4.1.1. DAV:ordering-type (protected)
The DAV:ordering-type property indicates whether the collection is
ordered and, if so, uniquely identifies the semantics of the
ordering. It may also point to an explanation of the semantics in
human and/or machine-readable form. At a minimum, this allows human
users who add members to the collection to understand where to
position them in the ordering. This property cannot be set using
PROPPATCH. Its value can only be set by including the Ordering-Type
header with a MKCOL request or by submitting an ORDERPATCH request.
Ordering types are identified by URIs that uniquely identify the
semantics of the collection’s ordering. The following two URIs are
predefined:
DAV:custom: The value DAV:custom indicates that the collection is
ordered, but the semantics governing the ordering are not being
advertised.
DAV:unordered: The value DAV:unordered indicates that the collection
is not ordered. That is, the client cannot depend on the
repeatability of the ordering of results from a PROPFIND request.
An ordering-aware client interacting with an ordering-unaware server
(e.g., one that is implemented only according to [RFC2518]) SHOULD
assume that the collection is unordered if a collection does not have
the DAV:ordering-type property.
<!ELEMENT ordering-type (href) >
5. Creating an Ordered Collection
5.1. Overview
When a collection is created, the client MAY request that it be
ordered and specify the semantics of the ordering by using the new
Ordering-Type header (defined below) with a MKCOL request.
For collections that are ordered, the client SHOULD identify the
semantics of the ordering with a URI in the Ordering-Type header,
although the client MAY simply set the header value to DAV:custom to
indicate that the collection is ordered but the semantics of the
ordering are not being advertised. Setting the value to a URI that
identifies the ordering semantics provides the information a human
user or software package needs to insert new collection members into
the ordering intelligently. Although the URI in the Ordering-Type
header MAY point to a resource that contains a definition of the
semantics of the ordering, clients SHOULD NOT access that resource to
avoid overburdening its server. A value of DAV:unordered in the
Ordering-Type header indicates that the client wants the collection
to be unordered. If the Ordering-Type header is not present, the
collection will be unordered.
Additional Marshalling:
Ordering-Type = "Ordering-Type" ":" absoluteURI
; absoluteURI: see RFC2396, section 3
The URI "DAV:unordered" indicates that the collection is not
ordered, while "DAV:custom" indicates that the collection is to be
ordered, but the semantics of the ordering is not being
advertised. Any other URI value indicates that the collection is
ordered, and identifies the semantics of the ordering.
Additional Preconditions:
(DAV:ordered-collections-supported): the server MUST support
ordered collections in the part of the URL namespace identified by
the request URL.
Additional Postconditions:
(DAV:ordering-type-set): if the Ordering-Type header was present,
the request MUST have created a new collection resource with the
DAV:ordering-type being set according to the Ordering-Type request
header. The collection MUST be ordered unless the ordering type
is "DAV:unordered".
5.2. Example: Creating an Ordered Collection
>> Request:
MKCOL /theNorth/ HTTP/1.1
Host: example.org
Ordering-Type: http://example.org/orderings/compass.html
>> Response:
HTTP/1.1 201 Created
In this example, a new ordered collection was created. Its
DAV:ordering-type property has the URI from the Ordering-Type header
as its value http://example.org/orderings/compass.html. In this
case, the URI identifies the semantics governing a client-maintained
ordering. As new members are added to the collection, clients or end
users can use the semantics to determine where to position the new
members in the ordering.
6. Setting the Position of a Collection Member
6.1. Overview
When a new member is added to a collection with a client-maintained
ordering (for example, with PUT, COPY, or MKCOL), its position in the
ordering can be set with the new Position header. The Position
header allows the client to specify that an internal member URI
should be first in the collection’s ordering, last in the
collection’s ordering, immediately before some other internal member
URI in the collection’s ordering, or immediately after some other
internal member URI in the collection’s ordering.
If the Position request header is not used when adding a member to an
ordered collection, then:
o If the request is replacing an existing resource, the server MUST
preserve the present ordering.
o If the request is adding a new internal member URI to the
collection, the server MUST append the new member to the end of
the ordering.
Note to implementers: this specification does not mandate a specific
implementation of MOVE operations within the same parent collection.
Therefore, servers may either implement this as a simple rename
operation (preserving the collection member’s position), or as a
sequence of "remove" and "add" (causing the semantics of "adding a
new member" to apply). Future revisions of this specification may
specify this behaviour more precisely based on future implementation
experience.
Additional Marshalling:
Position = "Position" ":" ("first" | "last" |
(("before" | "after") segment))
segment is defined in Section 3.3 of [RFC2396].
The segment is interpreted relative to the collection to which the
new member is being added.
When the Position header is present, the server MUST insert the
new member into the ordering at the specified location.
The "first" keyword indicates that the new member is placed in the
beginning position in the collection’s ordering, while "last"
indicates that the new member is placed in the final position in
the collection’s ordering. The "before" keyword indicates that
the new member is added to the collection’s ordering immediately
prior to the position of the member identified in the segment.
Likewise, the "after" keyword indicates that the new member is
added to the collection’s ordering immediately following the
position of the member identified in the segment.
If the request is replacing an existing resource and the Position
header is present, the server MUST remove the internal member URI
from its current position, and insert it at the newly requested
position.
Additional Preconditions:
(DAV:collection-must-be-ordered): the target collection MUST be
ordered.
(DAV:segment-must-identify-member): the referenced segment MUST
identify a resource that exists and is different from the affected
resource.
Additional Postconditions:
(DAV:position-set): if a Position header is present, the request
MUST create the new collection member at the specified position.
6.2. Examples: Setting the Position of a Collection Member
>> Request:
COPY /~user/dav/spec08.html HTTP/1.1
Host: example.org
Destination: http://example.org/~slein/dav/spec08.html
Position: after requirements.html
>> Response:
HTTP/1.1 201 Created
This request resulted in the creation of a new resource at
example.org/~slein/dav/spec08.html. The Position header in this
example caused the server to set its position in the ordering of the
/~slein/dav/ collection immediately after requirements.html.
>> Request:
MOVE /i-d/draft-webdav-prot-08.txt HTTP/1.1
Host: example.org
Destination: http://example.org/~user/dav/draft-webdav-prot-08.txt
Position: first
>> Response:
HTTP/1.1 409 Conflict
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:error xmlns:D="DAV:">
<D:collection-must-be-ordered/>
</D:error>
In this case, the server returned a 409 (Conflict) status code
because the /~user/dav/ collection is an unordered collection.
Consequently, the server was unable to satisfy the Position header.
6.3. Examples: Renaming a member of an ordered collection
The following sequence of requests will rename a collection member
while preserving its position, independently of how the server
implements the MOVE operation:
1. PROPFIND collection with depth 1, retrieving the DAV:ordering-type
property (an interactive client has already likely done this in
order to display the collection’s content).
2. If the DAV:ordering-type property is present and does not equal
"dav:unordered" (thus if the collection is ordered), determine the
current position (such as "first" or "after x") and setup the
Position header accordingly.
3. Perform the MOVE operation, optionally supplying the Position
header computed in the previous step.
7. Changing a Collection Ordering: ORDERPATCH method
The ORDERPATCH method is used to change the ordering semantics of a
collection, to change the order of the collection’s members in the
ordering, or both.
The server MUST apply the changes in the order they appear in the
order XML element. The server MUST either apply all the changes or
apply none of them. If any error occurs during processing, all
executed changes MUST be undone and a proper error result returned.
If an ORDERPATCH request changes the ordering semantics, but does not
completely specify the order of the collection members, the server
MUST assign a position in the ordering to each collection member for
which a position was not specified. These server-assigned positions
MUST follow the last position specified by the client. The result is
that all members for which the client specified a position are at the
beginning of the ordering, followed by any members for which the
server assigned positions. Note that the ordering of the server-
assigned positions is not defined by this document, therefore servers
can use whatever rule seems reasonable (for instance, alphabetically
or by creation date).
If an ORDERPATCH request does not change the ordering semantics, any
member positions not specified in the request MUST remain unchanged.
A request to reposition a collection member to the same place in the
ordering is not an error.
If an ORDERPATCH request fails, the server state preceding the
request MUST be restored.
Additional Marshalling:
The request body MUST be DAV:orderpatch element.
<!ELEMENT orderpatch (ordering-type?, order-member*) >
<!ELEMENT order-member (segment, position) >
<!ELEMENT position (first | last | before | after)>
<!ELEMENT segment (#PCDATA)>
<!ELEMENT first EMPTY >
<!ELEMENT last EMPTY >
<!ELEMENT before segment >
<!ELEMENT after segment >
PCDATA value: segment, as defined in section 3.3 of [RFC2396].
The DAV:ordering-type property is modified according to the