draft-ietf-webdav-ordering-protocol-01.txt   draft-ietf-webdav-ordering-protocol-02.txt 
WEBDAV Working Group J. Slein, Xerox WEBDAV Working Group J. Slein, Xerox
INTERNET DRAFT E.J. Whitehead Jr., UC Irvine INTERNET DRAFT E.J. Whitehead Jr., UC Irvine
<draft-ietf-webdav-ordering-protocol-01.txt> J. Davis, CourseNet <draft-ietf-webdav-ordering-protocol-02.txt> J. Davis, CourseNet
G. Clemm, Rational G. Clemm, Rational
C. Fay, FileNet C. Fay, FileNet
J. Crawford, IBM J. Crawford, IBM
T. Chihaya, DataChannel December 20, 1999
October 15, 1999 Expires June 20, 2000
Expires April 15, 2000
WebDAV Ordered Collections Protocol WebDAV Ordered Collections Protocol
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with all This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026. Internet-Drafts are working provisions of Section 10 of RFC2026. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, and documents of the Internet Engineering Task Force (IETF), its areas, and
its working groups. Note that other groups may also distribute working its working groups. Note that other groups may also distribute working
documents as Internet-Drafts. documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress". or to cite them other than as "work in progress".
To view the list Internet-Draft Shadow Directories, see The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
Distribution of this document is unlimited. Please send comments to the Distribution of this document is unlimited. Please send comments to the
Distributed Authoring and Versioning (WebDAV) working group at <w3c- Distributed Authoring and Versioning (WebDAV) working group at <w3c-
dist-auth@w3.org>, which may be joined by sending a message with subject dist-auth@w3.org>, which may be joined by sending a message with subject
"subscribe" to <w3c-dist-auth-request@w3.org>. "subscribe" to <w3c-dist-auth-request@w3.org>.
Discussions of the WEBDAV working group are archived at URL: Discussions of the WEBDAV working group are archived at URL:
<http://lists.w3.org/Archives/Public/w3c-dist-auth/>. <http://lists.w3.org/Archives/Public/w3c-dist-auth/>.
Abstract Abstract
The WebDAV Distributed Authoring Protocol provides basic support for This specification extends the WebDAV Distributed Authoring Protocol to
collections, offering the ability to create and list unordered support server-side ordering of collection members. Of particular
collections. interest are orderings that are not based on property values, and so
cannot be achieved using a search protocol's ordering option and cannot
This specification is one of a group of three specifications that be maintained automatically by the server. Protocol elements are
supplement the WebDAV Distributed Authoring Protocol to increase the defined to let clients specify the position in the ordering of each
power of WebDAV collections. This specification defines a protocol collection member, as well as the semantics governing the ordering.
supporting server-side ordering of collection members. The companion
specifications "WebDAV Bindings"[B] and "WebDAV Redirect Reference
Resources"[RR] define two mechanisms for allowing a single resource to
appear in more than one collection.
Table of Contents Table of Contents
1 Notational Conventions......................................2 1 Notational Conventions.......................................2
2 Introduction................................................3 2 Introduction.................................................2
3 Terminology.................................................3 3 Terminology..................................................3
4 Overview of Ordered Collections.............................4 4 Overview of Ordered Collections..............................4
5 Creating an Ordered Collection..............................5 5 Creating an Ordered Collection...............................4
5.1 Overview.....................................................4
5.2 Example: Creating an Ordered Collection......................5
6 Setting the Position of a Collection Member..................5
6.1 Overview.....................................................5
6.2 Status Codes.................................................6
6.3 Examples: Setting the Position of a Collection Member........6
5.1 Overview....................................................5 7 Changing a Collection Ordering...............................6
5.2 Example: Creating an Ordered Collection.....................5 7.1 ORDERPATCH Method............................................6
6 Setting the Position of a Collection Member.................6 7.1.1 Status Codes.................................................7
6.1 Overview....................................................6 7.1.2 Example: Changing a Collection Ordering......................7
6.2 Status Codes................................................6 7.1.3 Example: Failure of an ORDERPATCH Request....................9
6.3 Examples: Setting the Position of a Collection Member.......6 8 Listing the Members of an Ordered Collection................10
7 Changing a Collection Ordering..............................7 8.1 Example: PROPFIND on an Ordered Collection..................11
7.1 ORDERPATCH Method...........................................7 9 Headers.....................................................12
7.1.1 Status Codes................................................7 9.1 Ordered Entity Header.......................................12
7.1.2 Example: Changing a Collection Ordering.....................8 9.2 Position Request Header.....................................13
7.1.3 Example: Failure of an ORDERPATCH Request...................9 10 Properties..................................................13
8 Listing the Members of an Ordered Collection...............10 10.1 orderingtype Property.......................................13
8.1 Example: PROPFIND on an Ordered Collection.................11 11 XML Elements................................................14
9 Status Codes...............................................13 11.1 unordered XML Element.......................................14
9.1 418 Unordered Collection...................................13 11.2 custom XML Element..........................................14
10 Headers....................................................13 11.3 order XML Element...........................................14
10.1 Ordered Entity Header......................................13 11.4 ordermember XML Element.....................................14
10.2 Position Request Header....................................13 11.5 position XML Element........................................15
11 Properties.................................................14 11.6 first XML Element...........................................15
11.1 orderingtype Property......................................14 11.7 last XML Element............................................15
12 XML Elements...............................................14 11.8 before XML Element..........................................15
12.1 unordered XML Element......................................14 11.9 after XML Element...........................................15
12.2 custom XML Element.........................................15 11.10 segment XML Element.........................................16
12.3 order XML Element..........................................15 12 Capability Discovery........................................16
12.4 ordermember XML Element....................................15 12.1 Example: Discovery of Support for Ordering..................16
12.5 position XML Element.......................................15 13 Security Considerations.....................................17
12.6 first XML Element..........................................15 13.1 Denial of Service and DAV:orderingtype......................17
12.7 last XML Element...........................................16 14 Internationalization Considerations.........................17
12.8 before XML Element.........................................16 15 IANA Considerations.........................................18
12.9 after XML Element..........................................16 16 Copyright...................................................18
12.10 options XML Element........................................16 17 Intellectual Property.......................................18
12.11 orderingoptions XML Element................................16 18 Acknowledgements............................................18
13 Capability Discovery.......................................17 19 References..................................................18
13.1 Example: Discovery of Support for Ordering.................17 20 Authors' Addresses..........................................18
13.2 Additional Capabilities....................................18 21 Appendices..................................................19
13.3 Example: Discovery of Ordering Options.....................18 21.1 Appendix 1: Extensions to the WebDAV Document Type
14 Security Considerations....................................19 Definition..................................................19
14.1 Denial of Service and DAV:orderingtype.....................19
15 Internationalization Considerations........................19
16 IANA Considerations........................................19
17 Copyright..................................................20
18 Intellectual Property......................................20
19 Acknowledgements...........................................20
20 References.................................................20
21 Authors' Addresses.........................................20
22 Appendices.................................................21
22.1 Appendix 1: Extensions to the WebDAV Document Type
Definition.................................................21
1 Notational Conventions 1 Notational Conventions
Since this document describes a set of extensions to the WebDAV Since this document describes a set of extensions to the WebDAV
Distributed Authoring Protocol [WebDAV], itself an extension to the Distributed Authoring Protocol [WebDAV], itself an extension to the
HTTP/1.1 protocol, the augmented BNF used here to describe protocol 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]. elements is exactly the same as described in Section 2.1 of [HTTP].
Since this augmented BNF uses the basic production rules provided in Since this augmented BNF uses the basic production rules provided in
Section 2.2 of [HTTP], these rules apply to this document as well. Section 2.2 of [HTTP], these rules apply to this document as well.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
2 Introduction 2 Introduction
The simple collections that the WebDAV Distributed Authoring Protocol This specification builds on the collection infrastructure provided by
specification supports are powerful enough to be widely useful. They the WebDAV Distributed Authoring Protocol, adding support for the
provide for the hierarchical organization of resources, with mechanisms
for creating and deleting collections, copying and moving them, locking
them, adding members to them and removing members from them, and getting
listings of their members. Delete, copy, move, list, and lock
operations can be applied recursively, so that a client can operate on
whole hierarchies with a single request.
This specification is one of a family of three specifications that build server-side ordering of collection members.
on the infrastructure defined in [HTTP] and [WebDAV] to extend the
capabilities of collections. The companion specifications "WebDAV
Bindings"[B] and "WebDAV Redirect Reference Resources"[RR] define
mechanisms for allowing the same resource to appear in multiple
collections. The present specification defines protocol extensions to
support ordered collections.
There are many scenarios where it is useful to impose an ordering on a There are many scenarios where it is useful to impose an ordering on a
collection at the server, such as expressing a recommended access order, collection at the server, such as expressing a recommended access order,
or a revision history order. Orderings may be based on property values, or a revision history order. The members of a collection might
but they may be completely independent of any properties on the represent the pages of a book, which need to be presented in order if
resources identified by the collection's internal member URIs. they are to make sense. Or an instructor might create a collection of
Orderings based on properties can be obtained using a search protocol, course readings, which she wants to be displayed in the order they are
but orderings not based on properties need some other mechanism. These to be read.
orderings generally need to be maintained by a human user. The ordering
protocol defined here focuses on support for such human-maintained Orderings may be based on property values, but this is not always the
orderings, but also allows for server-maintained orderings. 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 ordering. The protocol is designed
to allow support to be added in the future for orderings that are
maintained automatically by the server.
The remainder of this document is structured as follows: Section 3 The remainder of this document is structured as follows: Section 3
defines terminology that will be used throughout the specification. defines terminology that will be used throughout the specification.
Section 4 provides an overview of ordered collections. Section 5 Section 4 provides an overview of ordered collections. Section 5
describes how to create an ordered collection, and Section 6 discusses 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 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 7 explains how to change a collection ordering. Section 8 discusses
listing the members of an ordered collection. Sections 9 through 12 listing the members of an ordered collection. Sections 9 through 11
define the status codes, headers, properties, and XML elements needed to define the headers, properties, and XML elements needed to support
support ordered collections. Section 13 describes capability discovery. ordered collections. Section 12 describes capability discovery.
Sections 14 through 16 discuss security, internationalization, and IANA Sections 13 through 15 discuss security, internationalization, and IANA
considerations. The remaining sections provide supporting information. considerations. The remaining sections provide supporting information.
3 Terminology 3 Terminology
The terminology used here follows that in the WebDAV Distributed The terminology used here follows that in the WebDAV Distributed
Authoring Protocol specification [WebDAV]. Definitions of the terms Authoring Protocol specification [WebDAV]. Definitions of the terms
resource, Uniform Resource Identifier (URI), and Uniform Resource resource, Uniform Resource Identifier (URI), and Uniform Resource
Locator (URL) are provided in [URI]. Definitions of the terms URI Locator (URL) are provided in [URI].
mapping, path segment, binding, collection, and internal member URI are
provided in [B].
Ordered Collection Ordered Collection
A collection for which the results from a PROPFIND request are A collection for which the results from a PROPFIND request are
guaranteed to be in the order specified for that collection guaranteed to be in the order specified for that collection
Unordered Collection Unordered Collection
A collection for which the client cannot depend on the A collection for which the client cannot depend on the
repeatability of the ordering of results from a PROPFIND request repeatability of the ordering of results from a PROPFIND request
Client-Maintained Ordering Client-Maintained Ordering
skipping to change at line 199 skipping to change at line 187
by the server, based on a client's choice of ordering semantics by the server, based on a client's choice of ordering semantics
4 Overview of Ordered Collections 4 Overview of Ordered Collections
If a collection is unordered, the client cannot depend on the If a collection is unordered, the client cannot depend on the
repeatability of the ordering of results from a PROPFIND request. By repeatability of the ordering of results from a PROPFIND request. By
specifying an ordering for a collection, a client requires the server to specifying an ordering for a collection, a client requires the server to
follow that ordering whenever it responds to a PROPFIND request on that follow that ordering whenever it responds to a PROPFIND request on that
collection. collection.
These server-side orderings may be client-maintained or server- Server-side orderings may be client-maintained or server-maintained.
maintained. For client-maintained orderings, a client must specify the For client-maintained orderings, a client must specify the ordering
position of each of the collection's bindings in the ordering, either position of each of the collection's members, either when the member is
when the binding is added to the collection (using the Position header) added to the collection (using the Position header) or later (using the
or later (using the ORDERPATCH method). For server-maintained ORDERPATCH method). For server-maintained orderings, the server
orderings, the server automatically positions each of the collection's automatically positions each of the collection's members according to
bindings according to the ordering semantics. the ordering semantics. This specification supports only client-
maintained orderings, but is designed to allow future extension to
server-maintained orderings.
A collection that supports ordering may be ordered, but is not required A collection that supports ordering is not required to be ordered. It
to be. It is up to the client to decide whether a given collection is is up to the client to decide whether a given collection is ordered and,
ordered and, if so, to specify the semantics to be used for ordering its if so, to specify the semantics to be used for ordering its members.
bindings. If a collection is ordered, each of its bindings, and hence
internal member URIs, MUST be in the ordering exactly once, and the
ordering MUST NOT include any binding that is not contained by the
collection. Only one ordering can be attached to any collection. An
ordering is considered to be part of the state of a collection resource,
and hence is the same across all URI mappings to the 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.
The server is responsible for enforcing these constraints on orderings. If a collection is ordered, each of its internal member URIs MUST be in
The server MUST remove a binding (and its derived internal member URI) the ordering exactly once, and the ordering MUST NOT include any URI
from the ordering when it is removed from the collection. The server that is not an internal member of the collection. The server is
MUST add a binding (and its derived internal member URI) to the ordering responsible for enforcing these constraints on orderings. The server
when it is added to the collection. MUST remove an internal member URI from the ordering when it is removed
from the collection. The server MUST 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.
5 Creating an Ordered Collection 5 Creating an Ordered Collection
5.1 Overview 5.1 Overview
When a collection is created, the client MAY request that it be ordered When a collection is created, the client MAY request that it be ordered
and specify the semantics of the ordering by using the new Ordered and specify the semantics of the ordering by using the new Ordered
header (defined in Section 10.1) with a MKCOL request. header (defined in Section 9.1) with a MKCOL request.
For collections that are ordered, the client SHOULD identify the For collections that are ordered, the client SHOULD identify the
semantics of the ordering with a URI in the Ordered header. This URI semantics of the ordering with a URI in the Ordered header, although the
may identify a server-maintained ordering. Clients can discover the
available server-maintained orderings using the mechanism defined in
Section 13.2. The URI may identify a semantics for a client-maintained
ordering, providing the information a human user or software package
needs to insert new collection members into the ordering intelligently.
Although the URI in the Ordered header MAY point to a resource that
contains a definition of the semantics of the ordering, clients are
discouraged from accessing that resource, in order to avoid
overburdening its server. The client MAY set the header value to
DAV:custom to indicate that the collection is ordered, but the semantics
of the ordering are not being advertised. If the client does not want
the collection to be ordered, it may omit the Ordered header, or use it
with the value DAV:unordered.
If the server does not recognize the value of the Ordered header as one
of its server-maintained orderings, it MUST assume that a client-
maintained ordering is intended. If the value of the Ordered header is
one of the server-maintained orderings that the server supports, it MUST
maintain the collection's ordering according to that ordering semantics
as new members are added.
Every collection MUST have a DAV:orderingtype property (defined in client MAY simply set the header value to DAV:custom to indicate that
Section 11.1), which indicates whether the collection is ordered and, if the collection is ordered but the semantics of the ordering are not
so, identifies the semantics of the ordering. The server sets the being advertised. Setting the value to a URI that identifies the
initial value of this property based on the value of the Ordering header ordering semanticsprovides the information a human user or software
in the MKCOL request. If the collection is unordered, the package needs to insert new collection members into the ordering
DAV:orderingtype property MUST have the value DAV:unordered. An intelligently. Although the URI in the Ordered header MAY point to a
ordering-aware client interacting with an ordering-unaware server (e.g., resource that contains a definition of the semantics of the ordering,
one that is implemented only according to [WebDAV]) SHOULD assume that clients SHOULD NOT access that resource, in order to avoid overburdening
if a collection does not have the DAV:orderingtype property, the its server. A value of DAV:unordered in the Ordering header indicates
collection is unordered. that the client wants the collection to be unordered. If the Ordered
header is not present, the collection will be unordered.
Every collection that supports ordering MUST have a DAV:orderingtype
property (defined in Section 10.1), which indicates whether the
collection is ordered and, if so, identifies the semantics of the
ordering. The server sets the initial value of this property based on
the value of the Ordering header in the MKCOL request, if any. If the
Ordered header is not present, the server sets the value to
DAV:unordered. An ordering-aware client interacting with an ordering-
unaware server (e.g., one that is implemented only according to
[WebDAV]) SHOULD assume that if a collection does not have the
DAV:orderingtype property, the collection is unordered.
5.2 Example: Creating an Ordered Collection 5.2 Example: Creating an Ordered Collection
>>Request: >>Request:
MKCOL /theNorth/ HTTP/1.1 MKCOL /theNorth/ HTTP/1.1
Host: www.server.org Host: www.server.org
Ordered: <http://www.server.org/orderings/compass.html> Ordered: <http://www.server.org/orderings/compass.html>
>>Response: >>Response:
skipping to change at line 294 skipping to change at line 277
URI identifies the semantics governing a client-maintained ordering. As URI identifies the semantics governing a client-maintained ordering. As
new members are added to the collection, clients or end users can use 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 the semantics to determine where to position the new members in the
ordering. ordering.
6 Setting the Position of a Collection Member 6 Setting the Position of a Collection Member
6.1 Overview 6.1 Overview
When a new member is added to a collection with a client-maintained When a new member is added to a collection with a client-maintained
ordering (for example, with PUT, MKREF, or MKCOL), its position in the ordering (for example, with PUT, MKREF, COPY, or MKCOL), its position in
ordering can be set with the new Position header (defined in Section the ordering can be set with the new Position header (defined in Section
10.2). The Position header allows the client to specify that the member 9.2). The Position header allows the client to specify that an internal
should be first in the collection's ordering, last in the collection's member URI should be first in the collection's ordering, last in the
ordering, immediately before some other binding in the collection's collection's ordering, immediately before some other internal member URI
ordering, or immediately after some other binding in the collection's in the collection's ordering, or immediately after some other internal
ordering. member URI in the collection's ordering.
6.2 Status Codes If the Position request header is not used when adding a member to an
ordered collection, then:
409 (Conflict): The request specifies a position that is before or after o If the request is replacing an existing resource, the server MUST
a URI that is not an internal member URI of the collection, or before or preserve the present ordering.
after itself.
418 (Unordered Collection): The request specifies a collection position o If the request is adding a new internal member URI to the collection,
in an unordered collection or in a collection with a server-maintained the server MUST append the new member to the end of the ordering.
ordering.
6.2 Status Codes
409 (Conflict): Several conditions may cause this response. The request
may specify a position that is before or after a URI that is not an
internal member URI of the collection, or before or after itself. The
request may attempt to specify the new member's position in an unordered
collection.
6.3 Examples: Setting the Position of a Collection Member 6.3 Examples: Setting the Position of a Collection Member
>> Request: >> Request:
MKREF /~whitehead/dav/spec08.ref HTTP/1.1 COPY /~whitehead/dav/spec08.html HTTP/1.1
HOST: www.ics.uci.edu Host: www.ics.uci.edu
Ref-Target: <http://www.ics.uci.edu/i-d/draft-webdav-protocol-08.txt> Destination: http://www.xerox.com/~slein/dav/spec08.html
Position: after <requirements.html> Position: after requirements.html
>> Response: >> Response:
HTTP/1.1 201 Created HTTP/1.1 201 Created
This request resulted in the creation of a new referential resource at This request resulted in the creation of a new resource at
www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource www.xerox.com/~slein/dav/spec08.html. The Position header in this
identified by the Ref-Target header. The Position header in this
example caused the server to set its position in the ordering of the example caused the server to set its position in the ordering of the
/~whitehead/dav/ collection immediately after requirements.html. /~slein/dav/ collection immediately after requirements.html.
>> Request: >> Request:
MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1
Host: www.ics.uci.edu Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/~whitehead/dav/draft-webdav- Destination: http://www.ics.uci.edu/~whitehead/dav/draft-webdav-
protocol-08.txt protocol-08.txt
Position: first Position: first
>> Response: >> Response:
HTTP/1.1 418 Unordered Collection HTTP/1.1 409 Conflict
In this case, the server returned a 418 (Unordered Collection) status In this case, the server returned a 409 (Conflict) status code because
code because the /~whitehead/dav/ collection is an unordered collection. the /~whitehead/dav/ collection is an unordered collection.
Consequently, the server was unable to satisfy the Position header. Consequently, the server was unable to satisfy the Position header.
7 Changing a Collection Ordering 7 Changing a Collection Ordering
7.1 ORDERPATCH Method 7.1 ORDERPATCH Method
The ORDERPATCH method is used to change the ordering semantics of a The ORDERPATCH method is used to change the ordering semantics of a
collection or to change the order of bindings in a client-maintained collection or to change the order of the collection's members in the
ordering or both. ordering or both.
The ORDERPATCH method changes the ordering semantics of the collection The ORDERPATCH method changes the ordering semantics of the collection
identified by the Request-URI, based on the value of DAV:orderingtype identified by the Request-URI, based on the value of DAV:orderingtype
submitted in the request entity body. If the new value identifies a submitted in the request entity body.
client-maintained ordering, the client is responsible for updating the
collection's ordering according to the new semantics. If it identifies
a server-maintained ordering, the server MUST reorder the collection
according to the new semantics.
The ORDERPATCH method alters the ordering of bindings in the collection The ORDERPATCH method alters the ordering of internal member URIs in the
identified by the Request-URI, based on instructions in the ordermember collection identified by the Request-URI, based on instructions in the
XML elements in the request entity body. The ordermember XML elements ordermember XML elements in the request entity body. The ordermember XML
identify the bindings whose positions are to be changed, and describes elements identify the internal member URIs whose positions are to be
their new positions in the ordering. Each new position can be specified changed, and describe their new positions in the ordering. Each new
as first in the ordering, last in the ordering, immediately before some position can be specified as first in the ordering, last in the
other binding, or immediately after some other binding. ordering, immediately before some other internal member URI, or
immediately after some other internal member URI.
The server MUST apply the changes in the order they appear in the order 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 XML element. The server MUST either apply all the changes or apply none
of them. If any error occurs during processing, all executed changes of them. If any error occurs during processing, all executed changes
MUST be undone and a proper error result returned. 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 all
follow the last one 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.
If an ORDERPATCH request does not change the ordering semantics, any
member positions not specified in the request MUST remain unchanged.
7.1.1 Status Codes 7.1.1 Status Codes
Since multiple changes can be requested in a single ORDERPATCH request, Since multiple changes can be requested in a single ORDERPATCH request,
the server MUST return a 207 (Multi-Status) response, as defined in if any problems are encountered, the server MUST return a 207 (Multi-
[WebDAV]. Status) response, as defined in [WebDAV].
The following are examples of response codes one would expect to be used The following are examples of response codes one would expect to be used
in a 207 (Multi-Status) response for this method: in a 207 (Multi-Status) response for this method:
200 (OK): The change in ordering was successfully made. 200 (OK): The change in ordering was successfully made.
409 (Conflict): The request specifies a position that is before or after 409 (Conflict): Several conditions may cause this response. The request
a URI that is not an internal member URI of the collection, or before or may specify a position that is before or after a URI that is not an
after itself. internal member URI of the collection, or before or after itself. The
request may attempt to set the positions of members of an unordered
418 (Unordered Collection): The request specifies a collection position collection.
in an unordered collection or in a collection with a server-maintained
ordering.
A request to reposition a binding at the same place in the ordering is A request to reposition a collection member at the same place in the
not an error. ordering is not an error.
7.1.2 Example: Changing a Collection Ordering 7.1.2 Example: Changing a Collection Ordering
Consider a collection /coll-1/ whose DAV:orderingtype is DAV:unordered, Consider a collection /coll-1/ whose DAV:orderingtype is DAV:whim, with
with bindings ordered as follows: bindings ordered as follows:
nunavut.map three.html
nunavut.img four.html
baffin.map one.html
baffin.desc two.html
baffin.img
iqaluit.map
nunavut.desc
iqaluit.img
iqaluit.desc
>> Request: >> Request:
ORDERPATCH /coll-1/ HTTP/1.1 ORDERPATCH /coll-1/ HTTP/1.1
Host: www.nunanet.com Host: www.myserver.com
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxx Content-Length: xxx
<?xml version="1.0" ?> <?xml version="1.0" ?>
<d:order xmlns:d="DAV:"> <d:order xmlns:d="DAV:">
<d:orderingtype> <d:orderingtype>
<d:href>http://www.nunanet.com/geog.ord</d:href> <d:href>http://www.myserver.com/inorder.ord</d:href>
</d:orderingtype> </d:orderingtype>
<d:ordermember> <d:ordermember>
<d:href>nunavut.desc</d:href> <d:href>two.html</d:href>
<d:position> <d:position>
<d:after> <d:first/>
<d:href>nunavut.map</d:href>
</d:after>
</d:position> </d:position>
</d:ordermember> </d:ordermember>
<d:ordermember> <d:ordermember>
<d:href>iqaluit.img</d:href> <d:href>one.html</d:href>
<d:position>
<d:first/>
</d:position>
</d:ordermember>
<d:ordermember>
<d:href>three.html</d:href>
<d:position>
<d:last/>
</d:position>
</d:ordermember>
<d:ordermember>
<d:href>four.html</d:href>
<d:position> <d:position>
<d:last/> <d:last/>
</d:position> </d:position>
</d:ordermember> </d:ordermember>
</d:order> </d:order>
>> Response: >> Response:
HTTP/1.1 207 Multi-Status HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0" ?> In this example, after the request has been processed, the collection's
<d:multistatus xmlns:d="DAV:"> ordering semantics are identified by the URI
<d:response> http://www.myserver.com/inorder.ord. The value of the collection's
<d:href>http://www.nunanet.com/coll-1/</d:href> DAV:orderingtype property has been set to this URI. The request also
<d:propstat>
<d:prop><d:orderingtype/></d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
</d:response>
<d:response>
<d:href>http://www.nunanet.com/coll-1/nunavut.desc</d:href>
<d:status>HTTP/1.1 200 OK</d:status>
</d:response>
<d:response>
<d:href>http://www.nunanet.com/coll-1/iqaluit.img</d:href>
<d:status>HTTP/1.1 200 OK</d:status>
</d:response>
</d:multistatus>
In this example, after the request has been processed, the previously contains instructions for changing the positions of the collection's
unordered collection has become an ordered collection whose ordering internal member URIs in the ordering to comply with the new ordering
semantics are identified by the URI http://www.nunanet.com/geog.ord. The semantics. If href elements are relative URIs, as in this example, they
value of the collection's DAV:orderingtype property has been set to this are interpreted relative to the collection whose ordering is being
URI. Since this is a client-maintained ordering, the request also modified. The DAV:ordermember elements are required to be processed in
contained instructions for changing the positions of the bindings in the the order they appear in the request. Consequently, two.html is moved
ordering to comply with the new ordering semantics. If href elements are to the beginning of the ordering, and then one.html is moved to the
relative URIs, as in this example, they are interpreted relative to the beginning of the ordering. Then three.html is moved to the end of the
collection whose ordering is being modified. After the request has been ordering, and finally four.html is moved to the end of the ordering.
processed, the collection's ordering is as follows: After the request has been processed, the collection's ordering is as
follows:
nunavut.map one.html
nunavut.desc two.html
nunavut.img three.html
baffin.map four.html
baffin.desc
baffin.img
iqaluit.map
iqaluit.desc
iqaluit.img
7.1.3 Example: Failure of an ORDERPATCH Request 7.1.3 Example: Failure of an ORDERPATCH Request
Consider a collection /coll-1/ with bindings ordered as follows: Consider a collection /coll-1/ with members ordered as follows:
nunavut.map nunavut.map
nunavut.img nunavut.img
baffin.map baffin.map
baffin.desc baffin.desc
baffin.img baffin.img
iqaluit.map iqaluit.map
nunavut.desc nunavut.desc
iqaluit.img iqaluit.img
iqaluit.desc iqaluit.desc
skipping to change at line 516 skipping to change at line 495
Host: www.nunanet.com Host: www.nunanet.com
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxx Content-Length: xxx
<?xml version="1.0" ?> <?xml version="1.0" ?>
<d:order xmlns:d="DAV:"> <d:order xmlns:d="DAV:">
<d:ordermember> <d:ordermember>
<d:href>nunavut.desc</d:href> <d:href>nunavut.desc</d:href>
<d:position> <d:position>
<d:after> <d:after>
<d:href>nunavut.map</d:href> <d:segment>nunavut.map</d:segment>
</d:after> </d:after>
</d:position> </d:position>
</d:ordermember> </d:ordermember>
<d:ordermember> <d:ordermember>
<d:href>iqaluit.map</d:href> <d:href>iqaluit.map</d:href>
<d:position> <d:position>
<d:after> <d:after>
<d:href>pangnirtung.img</d:href> <d:segment>pangnirtung.img</d:segment>
</d:after> </d:after>
</d:position> </d:position>
</d:ordermember> </d:ordermember>
</d:order> </d:order>
>> Response: >> Response:
HTTP/1.1 207 Multi-Status HTTP/1.1 207 Multi-Status
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxx Content-Length: xxx
skipping to change at line 551 skipping to change at line 530
</d:response> </d:response>
<d:response> <d:response>
<d:href>http://www.nunanet.com/coll-1/iqaluit.map</d:href> <d:href>http://www.nunanet.com/coll-1/iqaluit.map</d:href>
<d:status>HTTP/1.1 409 Conflict</d:status> <d:status>HTTP/1.1 409 Conflict</d:status>
<d:responsedescription>pangnirtung.img is not a collection <d:responsedescription>pangnirtung.img is not a collection
member.</d:responsedescription> member.</d:responsedescription>
</d:response> </d:response>
</d:multistatus> </d:multistatus>
In this example, the client attempted to position iqaluit.map after a In this example, the client attempted to position iqaluit.map after a
binding that is not contained in the collection /coll-1/. The server URI that is not an internal member of the collection /coll-1/. The
responded to this client error with a 409 (Conflict) status code. server responded to this client error with a 409 (Conflict) status code.
Because ORDERPATCH is an atomic method, the request to reposition Because ORDERPATCH is an atomic method, the request to reposition
nunavut.desc (which would otherwise have succeeded) failed with a 424 nunavut.desc (which would otherwise have succeeded) failed with a 424
(Failed Dependency) status code. (Failed Dependency) status code.
8 Listing the Members of an Ordered Collection 8 Listing the Members of an Ordered Collection
A PROPFIND request is used to retrieve a listing of the members of an A PROPFIND request is used to retrieve a listing of the members of an
ordered collection, just as it is used to retrieve a listing of the ordered collection, just as it is used to retrieve a listing of the
members of an unordered collection. members of an unordered collection.
However, when responding to a PROPFIND on an ordered collection, the However, when responding to a PROPFIND on an ordered collection, the
server MUST order the response elements according to the ordering server MUST order the response elements according to the ordering
defined on the collection. If a collection is unordered, the client defined on the collection. If a collection is unordered, the client
cannot depend on the repeatability of the ordering of results from a cannot depend on the repeatability of the ordering of results from a
PROPFIND request. PROPFIND request.
When responding to a PROPFIND on an ordered collection, the server In a response to a PROPFIND with Depth: infinity, members of different
SHOULD include the DAV:orderingtype property in the DAV:response element collections may be interleaved. That is, the server is not required to
for the collection, even if the client did not explicitly request it. do a breadth-first traversal. The only requirement is that the members
of any ordered collection appear in the order defined for the
collection. Thus for the hierarchy illustrated in the following figure,
where collection A is an ordered collection with the ordering B C D,
A
/|\
/ | \
B C D
/ /|\
E F G H
it would be acceptable for the server to return response elements in the
order A B E C F G H D. In this response, B, C, and D appear in the
correct order, separated by members of other collections. Clients can
use a series of Depth: 1 PROPFIND requests to avoid the complexity of
processing Depth: infinity responses based on depth-first traversals.
8.1 Example: PROPFIND on an Ordered Collection 8.1 Example: PROPFIND on an Ordered Collection
Suppose a PROPFIND request is submitted to the following collection, Suppose a PROPFIND request is submitted to /MyCollection/, which has its
which has its members ordered according to their distance from the members ordered as follows.
equator.
/MyCollection/ /MyCollection/
lakehazen.html lakehazen.html
siorapaluk.html siorapaluk.html
iqaluit.html iqaluit.html
newyork.html newyork.html
>> Request: >> Request:
PROPFIND /MyCollection/ HTTP/1.1 PROPFIND /MyCollection/ HTTP/1.1
skipping to change at line 615 skipping to change at line 609
Content-Length: xxxx Content-Length: xxxx
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:multistatus xmlns:D="DAV:" <D:multistatus xmlns:D="DAV:"
xmlns:J="http:www.svr.com/jsprops/"> xmlns:J="http:www.svr.com/jsprops/">
<D:response> <D:response>
<D:href>http://www.svr.com/MyCollection/</D:href> <D:href>http://www.svr.com/MyCollection/</D:href>
<D:propstat> <D:propstat>
<D:prop> <D:prop>
<D:resourcetype><D:collection/></D:resourcetype> <D:resourcetype><D:collection/></D:resourcetype>
<D:orderingtype>
<D:href>http://www.svr.com/jslatitudedesc</D:href>
</D:orderingtype>
</D:prop> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status> <D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:propstat>
<D:propstat> <D:propstat>
<D:prop> <D:prop>
<J:latitude/> <J:latitude/>
</D:prop> </D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status> <D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat> </D:propstat>
</D:response> </D:response>
skipping to change at line 671 skipping to change at line 662
<D:prop> <D:prop>
<D:resourcetype/> <D:resourcetype/>
<J:latitude>45N</J:latitude> <J:latitude>45N</J:latitude>
</D:prop> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status> <D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:propstat>
</D:response> </D:response>
</D:multistatus> </D:multistatus>
In this example, the server responded with a list of the collection In this example, the server responded with a list of the collection
members ordered according to their distance from the equator, as members in the order defined for the collection.
specified by the value of DAV:orderingtype. Although the client did not
explicitly ask for the value of DAV:orderingtype, the server provided it
as one of the collection properties, allowing the client to tell that
the collection is ordered and to identify the ordering semantics.
9 Status Codes
9.1 418 Unordered Collection
The 418 (Unordered Collection) status code indicates that the client
attempted to set the position of an internal collection member in an
unordered collection or in a collection with a server-maintained
ordering.
10 Headers 9 Headers
10.1 Ordered Entity Header 9.1 Ordered Entity Header
Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url)
The Ordered header may be used with MKCOL to request that the new The Ordered header may be used with MKCOL to request that the new
collection be ordered and to specify its ordering semantics. A value of collection be ordered and to specify its ordering semantics. A value of
"DAV:unordered" indicates that the collection is not ordered. A value of "DAV:unordered" indicates that the collection is not ordered. A value of
"DAV:custom" indicates that the collection is to be ordered, but the "DAV:custom" indicates that the collection is to be ordered, but the
semantics of the ordering is not being advertised. Any other Coded-url semantics of the ordering is not being advertised. Any other Coded-url
value indicates that the collection is ordered, and identifies the value indicates that the collection is ordered, and identifies the
semantics of the ordering. semantics of the ordering.
10.2 Position Request Header 9.2 Position Request Header
Position = "Position" ":" ("first" | "last" | Position = "Position" ":" ("first" | "last" |
(("before" | "after") Generic-Coded-url)) (("before" | "after") segment))
Generic-Coded-url = "<" (absoluteURI | relativeURI) ">" segment is defined in Section 3.3 of [URI].
absoluteURI is defined in Section 3 of [URI].
relativeURI is defined in Section 5 of [URI].
The Position header may be used with any method that adds a binding to a The Position header may be used with any method that adds a member to an
collection with a client-maintained ordering, to tell the server where ordered collection, to tell the server where in the collection ordering
in the collection ordering to position the new binding being added to to position the new member being added to the collection. Examples of
the collection. Examples of methods that add bindings to collections methods that add members to collections are BIND, PUT, COPY, MOVE, etc.
are BIND, PUT, COPY, MOVE, etc.
If the Generic-Coded-url is a relative URL, it is interpreted relative The segment is interpreted relative to the collection to which the new
to the collection to which the new binding is being added. member is being added.
The server MUST insert the new binding into the ordering at the location The server MUST insert the new member into the ordering at the location
specified in the Position header, if one is present (and if the specified in the Position header, if one is present (and if the
collection has a client-maintained ordering). collection is ordered).
The "first" keyword indicates the new binding is put in the beginning The "first" keyword indicates the new member is put in the beginning
position in the collection's ordering, while "last" indicates the new position in the collection's ordering, while "last" indicates the new
binding is put in the final position in the collection's ordering. The member is put in the final position in the collection's ordering. The
"before" keyword indicates the new member is added to the collection's
"before" keyword indicates the new binding is added to the collection's ordering immediately prior to the position of the member identified in
ordering immediately prior to the position of the binding identified in the segment. Likewise, the "after" keyword indicates the new member is
the Generic-Coded-url. Likewise, the "after" keyword indicates the new added to the collection's ordering immediately following the position of
binding is added to the collection's ordering immediately following the the member identified in the segment.
position of the binding identified in the Generic-Coded-url.
If the request is replacing an existing resource, and the Position If the request is replacing an existing resource, and the Position
header is present, the server MUST remove the binding from its previous header is present, the server MUST remove the internal member URI from
position, and then insert it at the requested position. its previous position, and then insert it at the requested position.
If the Position request header is not used when adding a binding to a
collection with a client-maintained ordering, 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 binding to the collection, the server
MUST append the new binding to the end of the ordering.
If an attempt is made to use the Position header on a collection that is If an attempt is made to use the Position header on a collection that is
unordered or that has a server-maintained ordering, the server MUST fail unordered, the server MUST fail the request with a 409 (Conflict) status
the request with a 418 (Unordered) status code. code.
11 Properties 10 Properties
11.1 orderingtype Property 10.1 orderingtype Property
Name: orderingtype Name: orderingtype
Namespace: DAV: Namespace: DAV:
Purpose: Indicates whether the collection is ordered and, if so, Purpose: Indicates whether the collection is ordered and, if so,
uniquely identifies the semantics of the ordering being uniquely identifies the semantics of the ordering being
used. May also point to an explanation of the semantics in used. May also point to an explanation of the semantics in
human and / or machine-readable form. At a minimum, this human and / or machine-readable form. At a minimum, this
allows human users who add members to the collection to allows human users who add members to the collection to
understand where to position them in the ordering. This understand where to position them in the ordering. This
property cannot be set using PROPPATCH. Its value can only property cannot be set using PROPPATCH. Its value can only
skipping to change at line 772 skipping to change at line 737
or by submitting an ORDERPATCH request. or by submitting an ORDERPATCH request.
Value: The value unordered indicates that the collection is not Value: The value unordered indicates that the collection is not
ordered. The value custom indicates that the collection is ordered. The value custom indicates that the collection is
ordered, but the semantics governing the ordering are not ordered, but the semantics governing the ordering are not
being advertised. If the value is an href element, it being advertised. If the value is an href element, it
contains a URI that uniquely identifies the semantics of the contains a URI that uniquely identifies the semantics of the
collection's ordering. collection's ordering.
<!ELEMENT orderingtype (unordered | custom | href) > <!ELEMENT orderingtype (unordered | custom | href) >
12 XML Elements 11 XML Elements
12.1 unordered XML Element 11.1 unordered XML Element
Name: unordered Name: unordered
Namespace: DAV: Namespace: DAV:
Purpose: A value of the DAV:orderingtype property that indicates that Purpose: A value of the DAV:orderingtype property that indicates that
the collection is not ordered. That is, the client cannot the collection is not ordered. That is, the client cannot
depend on the repeatability of the ordering of results from depend on the repeatability of the ordering of results from
a PROPFIND request. a PROPFIND request.
<!ELEMENT unordered EMPTY > <!ELEMENT unordered EMPTY >
12.2 custom XML Element 11.2 custom XML Element
Name: custom Name: custom
Namespace: DAV: Namespace: DAV:
Purpose: A value of the DAV:orderingtype property that indicates that Purpose: A value of the DAV:orderingtype property that indicates that
the collection is ordered, but the semantics of the ordering the collection is ordered, but the semantics of the ordering
are not being advertised. are not being advertised.
<!ELEMENT custom EMPTY > <!ELEMENT custom EMPTY >
12.3 order XML Element 11.3 order XML Element
Name: order Name: order
Namespace: DAV: Namespace: DAV:
Purpose: For use with the new ORDERPATCH method. Describes a change Purpose: For use with the new ORDERPATCH method. Describes a change
to be made in a collection's ordering semantics or in the to be made in a collection's ordering semantics or in the
positions of its bindings in the ordering or both. positions of its members in the ordering or both.
Value: An optional identifier of an ordering semantics for the Value: An optional identifier of an ordering semantics for the
collection, followed by a list of changes to be made in the collection, followed by a list of changes to be made in the
positions of the bindings in the collection's ordering. positions of the members in the collection's ordering.
<!ELEMENT order (orderingtype?, ordermember*) > <!ELEMENT order (orderingtype?, ordermember*) >
12.4 ordermember XML Element 11.4 ordermember XML Element
Name: ordermember Name: ordermember
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the order XML element, and describes the new Purpose: Occurs in the order XML element, and describes the new
position of a single binding in the collection's ordering. position of a single internal member URI in the collection's
Value: An href containing a binding's path segment, and a ordering.
Value: An href containing a member's path segment, and a
description of its new position in the ordering. The href description of its new position in the ordering. The href
XML element is defined in [WebDAV], Section 11.3. XML element is defined in [WebDAV], Section 11.3.
<!ELEMENT ordermember (href, position) > <!ELEMENT ordermember (href, position) >
12.5 position XML Element 11.5 position XML Element
Name: position Name: position
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the ordermember XML element. Describes the new Purpose: Occurs in the ordermember XML element. Describes the new
position in a collection's ordering of one of the bindings position in a collection's ordering of one of the members it
it contains. contains.
Value: The new position can be described as first in the Value: The new position can be described as first in the
collection's ordering, last in the collection's ordering, collection's ordering, last in the collection's ordering,
immediately before some other binding, or immediately after immediately before some other collection member, or
some other binding. immediately after some other collection member.
<!ELEMENT position (first | last | before | after)> <!ELEMENT position (first | last | before | after)>
12.6 first XML Element 11.6 first XML Element
Name: first Name: first
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the position XML element. Specifies that the Purpose: Occurs in the position XML element. Specifies that the
binding should be placed first in the collection's ordering. member should be placed first in the collection's ordering.
<!ELEMENT first EMPTY > <!ELEMENT first EMPTY >
12.7 last XML Element 11.7 last XML Element
Name: last Name: last
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the position XML element. Specifies that the Purpose: Occurs in the position XML element. Specifies that the
binding should be placed last in the collection's ordering. member should be placed last in the collection's ordering.
<!ELEMENT last EMPTY > <!ELEMENT last EMPTY >
12.8 before XML Element 11.8 before XML Element
Name: before Name: before
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the position XML element. Specifies that the Purpose: Occurs in the position XML element. Specifies that the
binding should be placed immediately before the binding in member should be placed immediately before the member in the
the enclosed href XML element in the collection's ordering. enclosed segment XML element in the collection's ordering.
Value: href of the member it precedes in the ordering Value: URI (relative to the parent collection) of the member
it precedes in the ordering
<!ELEMENT before href > <!ELEMENT before segment >
12.9 after XML Element 11.9 after XML Element
Name: after Name: after
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the position XML element. Specifies that the Purpose: Occurs in the position XML element. Specifies that the
binding should be placed immediately after the binding in member should be placed immediately after the member in the
the enclosed href XML element in the collection's ordering. enclosed segment XML element in the collection's ordering.
Value: href of the member it follows in the ordering Value: URI (relative to the parent collection) of the member
it follows in the ordering
<!ELEMENT after href >
12.10 options XML Element
Name: options
Namespace: DAV:
Purpose: Used in OPTIONS requests to ask for more detailed
information about capabilities than can be provided in the
DAV: response header. Used in OPTIONS responses to provide
that information.
Value: List of elements identifying or providing the additional
information desired.
<!ELEMENT options (orderingoptions | ANY)+ >
12.11 orderingoptions XML Element <!ELEMENT after segment >
Name: orderingoptions 11.10 segment XML Element
Name: segment
Namespace: DAV: Namespace: DAV:
Purpose: Used in OPTIONS requests to ask for the list of server- Purpose: Identifies a member of a collection, used in the DAV:before
maintained orderings that can be supported at the request- and DAV:after elements, to define one member's position in
URI. Used in OPTIONS responses to provide that information. a collection ordering relative to another member of the
These values can be used in the Ordered header or the collection.
DAV:orderingtype property to request that a particular Value: segment ; as defined in section 3.3 of [URI].
server-maintained ordering be applied to the collection.
Value: EMPTY on requests. On responses, it is the list of server-
maintained orderings available for the request-URI.
<!ELEMENT orderingoptions ( (#PCDATA)+ | EMPTY) > <!ELEMENT segment (#PCDATA)>
13 Capability Discovery 12 Capability Discovery
Sections 9.1 and 15 of [WebDAV] describe the use of compliance classes Sections 9.1 and 15 of [WebDAV] describe the use of compliance classes
with the DAV header in responses to OPTIONS, to indicate which parts of with the DAV header in responses to OPTIONS, to indicate which parts of
the Web Distributed Authoring protocols the resource supports. This the Web Distributed Authoring protocols the resource supports. This
specification defines an OPTIONAL extension to [WebDAV]. It defines a specification defines an OPTIONAL extension to [WebDAV]. It defines a
new compliance class, called orderedcoll, for use with the DAV header in new compliance class, called orderedcoll, for use with the DAV header in
responses to OPTIONS requests. If a collection resource does support responses to OPTIONS requests. If a collection resource does support
ordering, its response to an OPTIONS request MUST indicate that it does, ordering, its response to an OPTIONS request may indicate that it does,
by listing the new ORDERPATCH method as one it supports, and by listing by listing the new ORDERPATCH method as one it supports, and by listing
the new orderedcoll compliance class in the DAV header. the new orderedcoll compliance class in the DAV header.
When responding to an OPTIONS request, only a collection or a null When responding to an OPTIONS request, only a collection or a null
resource can include orderedcoll in the value of the DAV header. By resource can include orderedcoll in the value of the DAV header. By
including orderedcoll, the resource indicates that its bindings can be including orderedcoll, the resource indicates that its internal member
ordered. It implies nothing about whether any collections identified by URIs can be ordered. It implies nothing about whether any collections
its internal member URIs can be ordered. identified by its internal member URIs can be ordered.
13.1 Example: Discovery of Support for Ordering 12.1 Example: Discovery of Support for Ordering
>> Request: >> Request:
OPTIONS /somecollection/ HTTP/1.1 OPTIONS /somecollection/ HTTP/1.1
HOST: somehost.org HOST: somehost.org
>> Response: >> Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Tue, 20 Jan 1998 20:52:29 GMT Date: Tue, 20 Jan 1998 20:52:29 GMT
skipping to change at line 947 skipping to change at line 899
PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH
DAV: 1, 2, orderedcoll DAV: 1, 2, orderedcoll
The DAV header in the response indicates that the resource The DAV header in the response indicates that the resource
/somecollection/ is level 1 and level 2 compliant, as defined in /somecollection/ is level 1 and level 2 compliant, as defined in
[WebDAV]. In addition, /somecollection/ supports ordering. The Allow [WebDAV]. In addition, /somecollection/ supports ordering. The Allow
header indicates that ORDERPATCH requests can be submitted to header indicates that ORDERPATCH requests can be submitted to
/somecollection/. The Public header shows that other Request-URIs on /somecollection/. The Public header shows that other Request-URIs on
the server support additional methods. the server support additional methods.
13.2 Additional Capabilities 13 Security Considerations
Clients may need detailed information about specific areas of Web
Distributed Authoring functionality. This information can be requested
by sending an OPTIONS request with an XML body that includes a
DAV:options element. The DAV:options element contains a list of empty
elements identifying the information the client needs.
As described in Section 3, servers may offer a set of server-maintained
orderings on collections. Clients can discover the list of server-
maintained orderings available for the request-URI by including an empty
DAV:orderingoptions element in the DAV:options element. The response
will include a DAV:orderingoptions element with the list of supported
server-maintained orderings. Servers SHOULD advertise the server-
maintained orderings available using this mechanism.
13.3 Example: Discovery of Ordering Options
>> Request:
OPTIONS /somecollection/ HTTP/1.1
HOST: somehost.org
<?xml version="1.0" ?>
<D:options xmlns:D="DAV:">
<D:orderingoptions/>
</D:options>
>> Response:
HTTP/1.1 200 OK
Date: Tue, 20 Jan 1998 20:52:29 GMT
Connection: close
Accept-Ranges: none
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL,
PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL,
PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH
DAV: 1, sharing, orderedcoll
<?xml version="1.0" ?>
<D:options xmlns:D="DAV:">
<D:orderingoptions xmlns:X="Xerox:">
<X:author-ascending/>
<X:title-ascending/>
<X:date-descending/>
</D:orderingoptions>
</D:options>
This response indicates that the resource /somecollection/ is level 1
compliant, as defined in [WebDAV]. In addition, /somecollection/
supports ordering. The client also asked for a list of the server-
maintained orderings that are supported for /somecollection/. The
response indicates that the orderings Xerox:author-ascending,
Xerox:title-ascending, and Xerox:date-descending are supported.
14 Security Considerations
This section is provided to make WebDAV applications aware of the This section is provided to make WebDAV applications aware of the
security implications of this protocol. security implications of this protocol.
All of the security considerations of HTTP/1.1 and the WebDAV All of the security considerations of HTTP/1.1 and the WebDAV
Distributed Authoring Protocol specification also apply to this protocol Distributed Authoring Protocol specification also apply to this protocol
specification. In addition, ordered collections introduce a new specification. In addition, ordered collections introduce a new
security concern. This issue is detailed here. security concern. This issue is detailed here.
14.1 Denial of Service and DAV:orderingtype 13.1 Denial of Service and DAV:orderingtype
There may be some risk of denial of service at sites that are advertised There may be some risk of denial of service at sites that are advertised
in the DAV:orderingtype property of collections. However, it is in the DAV:orderingtype property of collections. However, it is
anticipated that widely-deployed applications will use hard-coded values anticipated that widely-deployed applications will use hard-coded values
for frequently-used ordering semantics rather than looking up the for frequently-used ordering semantics rather than looking up the
semantics at the location specified by DAV:orderingtype. In addition, semantics at the location specified by DAV:orderingtype. This risk will
Section 3 discourages clients from looking up the semantics at that be further reduced if clients observe the recommendation of Section 5.1
location. that they not send requests to the URI in DAV:orderingtype.
15 Internationalization Considerations 14 Internationalization Considerations
This specification follows the practices of [WebDAV] in encoding all This specification follows the practices of [WebDAV] in encoding all
human-readable content using XML [XML] and in the treatment of names. human-readable content using XML [XML] and in the treatment of names.
Consequently, this specification complies with the IETF Character Set Consequently, this specification complies with the IETF Character Set
Policy [Alvestrand]. Policy [RFC2277].
WebDAV applications MUST support the character set tagging, character WebDAV applications MUST support the character set tagging, character
set encoding, and the language tagging functionality of the XML set encoding, and the language tagging functionality of the XML
specification. This constraint ensures that the human-readable content specification. This constraint ensures that the human-readable content
of this specification complies with [Alvestrand]. of this specification complies with [RFC2277].
As in [WebDAV}, names in this specification fall into three categories: As in [WebDAV}, names in this specification fall into three categories:
names of protocol elements such as methods and headers, names of XML names of protocol elements such as methods and headers, names of XML
elements, and names of properties. Naming of protocol elements follows elements, and names of properties. Naming of protocol elements follows
the precedent of HTTP, using English names encoded in USASCII for the precedent of HTTP, using English names encoded in USASCII for
methods and headers. The names of XML elements used in this methods and headers. The names of XML elements used in this
specification are English names encoded in UTF-8. specification are English names encoded in UTF-8.
For error reporting, [WebDAV] follows the convention of HTTP/1.1 status For error reporting, [WebDAV] follows the convention of HTTP/1.1 status
codes, including with each status code a short, English description of codes, including with each status code a short, English description of
the code (e.g., 423 Locked). Internationalized applications will ignore the code (e.g., 423 Locked). Internationalized applications will ignore
this message, and display an appropriate message in the user's language this message, and display an appropriate message in the user's language
and character set. and character set.
This specification introduces no new strings that are displayed to users
as part of normal, error-free operation of the protocol.
For rationales for these decisions and advice for application For rationales for these decisions and advice for application
implementors, see [WebDAV]. implementors, see [WebDAV].
16 IANA Considerations 15 IANA Considerations
This document uses the namespaces defined by [WebDAV] for properties and This document uses the namespaces defined by [WebDAV] for properties and
XML elements. All other IANA considerations mentioned in [WebDAV] also XML elements. All other IANA considerations mentioned in [WebDAV] also
apply to this document. apply to this document.
In addition, this document defines a new HTTP/1.1 status code, 418 16 Copyright
(Unordered Collection) defined in Section 9.1.
17 Copyright
To be supplied by the RFC Editor. To be supplied by the RFC Editor.
18 Intellectual Property 17 Intellectual Property
To be supplied by the RFC Editor. To be supplied by the RFC Editor.
19 Acknowledgements 18 Acknowledgements
This draft has benefited from thoughtful discussion by Jim Amsden, Steve This draft has benefited from thoughtful discussion by Jim Amsden, Steve
Carter, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Mark Day, Carter, Tyson Chihaya, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer
Rajiv Dulepet, David Durand, Roy Fielding, Yaron Goland, Fred Hitt, Alex Dawkins, Mark Day, Rajiv Dulepet, David Durand, Roy Fielding, Yaron
Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, Goland, Fred Hitt, Alex Hopmann, Marcus Jager, Chris Kaler, Manoj
Daniel LaLiberte, Steve Martin, Larry Masinter, Jeff McAffer, Surendra Kasichainula, Rohit Khare, Daniel LaLiberte, Lisa Lippert, Steve Martin,
Koduru Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness, John Larry Masinter, Jeff McAffer, Surendra Koduru Reddy, Max Rible, Sam
Stracke, John Tigue, John Turner, and others. Ruby, Bradley Sergeant, Nick Shelness, John Stracke, John Tigue, John
Turner, Kevin Wiggen, and others.
20 References 19 References
[RFC2277] H.T. Alvestrand, "IETF Policy on Character Sets and
Languages." RFC 2277, BCP 18. Uninett. January, 1998.
[URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource [URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource
Identifiers (URI): Generic Syntax." RFC 2396. MIT/LCS, U.C. Irvine, Identifiers (URI): Generic Syntax." RFC 2396. MIT/LCS, U.C. Irvine,
Xerox. August, 1998. Xerox. August, 1998.
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement
Levels." RFC 2119, BCP 14. Harvard University. March, 1997. Levels." RFC 2119, BCP 14. Harvard University. March, 1997.
[XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup [XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup
Language (XML)." World Wide Web Consortium Recommendation REC-xml- Language (XML)." World Wide Web Consortium Recommendation REC-xml-
19980210. http://www.w3.org/TR/1998/REC-xml-19980210. 19980210. http://www.w3.org/TR/1998/REC-xml-19980210.
[HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. [HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P.
Leach, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC Leach, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC
2616. UC Irvine, Compaq, W3C, Xerox, Microsoft. June, 1999. 2616. UC Irvine, Compaq, W3C, Xerox, Microsoft. June, 1999.
[WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D.
Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." RFC 2518. Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." RFC 2518.
Microsoft, U.C. Irvine, Netscape, Novell. February, 1999. Microsoft, U.C. Irvine, Netscape, Novell. February, 1999.
[B] J. Slein, E.J. Whitehead Jr., J. Davis, G. Clemm, C. Fay, J. 20 Authors' Addresses
Crawford, T. Chihaya, "WebDAV Bindings." Internet Draft (work in
progress) draft-ietf-webdav-binding-protocol-00. Xerox, UC Irvine,
CourseNet, Rational, FileNet, IBM, DataChannel. August, 1999.
[RR] J. Slein, E.J. Whitehead Jr., J. Davis, G. Clemm, C. Fay, J.
Crawford, T. Chihaya, "WebDAV Redirect References." Internet Draft (work
in progress) draft-ietf-webdav-redirectref-protocol-00. Xerox, UC
Irvine, CourseNet, Rational, FileNet, IBM, DataChannel. August, 1999.
21 Authors' Addresses
J. Slein J. Slein
Xerox Corporation Xerox Corporation
800 Phillips Road, 105-50C 800 Phillips Road, 105-50C
Webster, NY 14580 Webster, NY 14580
Email: jslein@crt.xerox.com Email: jslein@crt.xerox.com
E. J. Whitehead, Jr. E. J. Whitehead, Jr.
Dept. of Information and Computer Science Dept. of Information and Computer Science
University of California, Irvine University of California, Irvine
skipping to change at line 1143 skipping to change at line 1032
Lexington, MA 02173-3104 Lexington, MA 02173-3104
Email: gclemm@rational.com Email: gclemm@rational.com
C. Fay C. Fay
FileNet Corporation FileNet Corporation
3565 Harbor Boulevard 3565 Harbor Boulevard
Costa Mesa, CA 92626-1420 Costa Mesa, CA 92626-1420
Email: cfay@filenet.com Email: cfay@filenet.com
J. Crawford J. Crawford
IBM IBM Research
P.O. Box 704
Yorktown Heights, NY 10598
Email: ccjason@us.ibm.com Email: ccjason@us.ibm.com
T. Chihaya 21 Appendices
DataChannel, Inc.
155 108th Ave. N.E., Suite 400
Bellevue, WA 98004
Email: Tyson@DataChannel.com
22 Appendices
22.1 Appendix 1: Extensions to the WebDAV Document Type Definition 21.1 Appendix 1: Extensions to the WebDAV Document Type Definition
<!--============= XML Elements from Section 12 ================--> <!--============= XML Elements from Section 11 ================-->
<!ELEMENT unordered EMPTY > <!ELEMENT unordered EMPTY >
<!ELEMENT custom EMPTY > <!ELEMENT custom EMPTY >
<!ELEMENT order (orderingtype?, ordermember*) > <!ELEMENT order (orderingtype?, ordermember*) >
<!ELEMENT ordermember (href, position) > <!ELEMENT ordermember (href, position) >
<!ELEMENT position (first | last | before | after)> <!ELEMENT position (first | last | before | after)>
<!ELEMENT first EMPTY > <!ELEMENT first EMPTY >
<!ELEMENT last EMPTY > <!ELEMENT last EMPTY >
<!ELEMENT before href > <!ELEMENT before segment >
<!ELEMENT after href > <!ELEMENT after segment >
<!ELEMENT options (refintegrityoptions | orderingoptions)+ > <!ELEMENT segment (#PCDATA)>
<!--============= Property Elements from Section 10 =============-->
<!ELEMENT orderingoptions ( (#PCDATA)+ | EMPTY) >
<!--============= Property Elements from Section 0 ==================-->
<!ELEMENT orderingtype (unordered | custom | href) > <!ELEMENT orderingtype (unordered | custom | href) >
Expires April 15, 2000 Expires June 20, 2000
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/