DAV:ordering-type element.
The ordering of internal member URIs in the collection identified
by the Request-URI is changed based on instructions in the order-
member XML elements. Specifically, in the order that they appear
in the request. The order-member XML elements identify the
internal member URIs whose positions are to be changed, and
describe their new positions in the ordering. Each new position
can be specified as first in the ordering, last in the ordering,
immediately before some other internal member URI, or immediately
after some other internal member URI.
If a response body for a successful request is included, it MUST
be a DAV:orderpatch-response XML element. Note that this document
does not define any elements for the ORDERPATCH response body, but
the DAV:orderpatch-response element is defined to ensure
interoperability between future extensions that do define elements
for the ORDERPATCH response body.
<!ELEMENT orderpatch-response ANY>
Since multiple changes can be requested in a single ORDERPATCH
request, the server MUST return a 207 (Multi-Status) response
(defined in [RFC2518]), containing DAV:response elements for
either the request-URI (when the DAV:ordering-type could not be
modified) or URIs of collection members to be repositioned (when
an individual positioning request expressed as DAV:order-member
could not be fulfilled) if any problems are encountered.
Preconditions:
(DAV:collection-must-be-ordered): see Section 6.1.
(DAV:segment-must-identify-member): see Section 6.1.
Postconditions:
(DAV:ordering-type-set): if the request body contained a
DAV:ordering-type element, the request MUST have set the
DAV:ordering-type property of the collection to the value
specified in the request.
(DAV:ordering-modified): if the request body contained DAV:order-
member elements, the request MUST have set the ordering of
internal member URIs in the collection identified by the request-
URI based upon the instructions in the DAV:order-member elements.
7.1. Example: Changing a Collection Ordering
Consider an ordered collection /coll-1, with bindings ordered as
follows:
three.html
four.html
one.html
two.html
>> Request:
ORDERPATCH /coll-1/ HTTP/1.1
Host: example.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
<?xml version="1.0" ?>
<d:orderpatch xmlns:d="DAV:">
<d:ordering-type>
<d:href>http://example.org/inorder.ord</d:href>
</d:ordering-type>
<d:order-member>
<d:segment>two.html</d:segment>
<d:position><d:first/></d:position>
</d:order-member>
<d:order-member>
<d:segment>one.html</d:segment>
<d:position><d:first/></d:position>
</d:order-member>
<d:order-member>
<d:segment>three.html</d:segment>
<d:position><d:last/></d:position>
</d:order-member>
<d:order-member>
<d:segment>four.html</d:segment>
<d:position><d:last/></d:position>
</d:order-member>
</d:orderpatch>
>> Response:
HTTP/1.1 200 OK
In this example, after the request has been processed, the
collection’s ordering semantics are identified by the URI http://
example.org/inorder.ord. The value of the collection’s
DAV:ordering-type property has been set to this URI. The request
also contains instructions for changing the positions of the
collection’s internal member URIs in the ordering to comply with the
new ordering semantics. As the DAV:order-member elements are
required to be processed in the order they appear in the request,
two.html is moved to the beginning of the ordering, and then one.html
is moved to the beginning of the ordering. Then three.html is moved
to the end of the ordering, and finally four.html is moved to the end
of the ordering. After the request has been processed, the
collection’s ordering is as follows:
one.html
two.html
three.html
four.html
7.2. Example: Failure of an ORDERPATCH Request
Consider a collection /coll-1/ with members ordered as follows:
nunavut.map
nunavut.img
baffin.map
baffin.desc
baffin.img
iqaluit.map
nunavut.desc
iqaluit.img
iqaluit.desc
>> Request:
ORDERPATCH /coll-1/ HTTP/1.1
Host: www.nunanet.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
<?xml version="1.0" ?>
<d:orderpatch xmlns:d="DAV:">
<d:order-member>
<d:segment>nunavut.desc</d:segment>
<d:position>
<d:after>
<d:segment>nunavut.map</d:segment>
</d:after>
</d:position>
</d:order-member>
<d:order-member>
<d:segment>iqaluit.map</d:segment>
<d:position>
<d:after>
<d:segment>pangnirtung.img</d:segment>
</d:after>
</d:position>
</d:order-member>
</d:orderpatch>
>> Response:
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
<?xml version="1.0" ?>
<d:multistatus xmlns:d="DAV:">
<d:response>
<d:href>http://www.nunanet.com/coll-1/iqaluit.map</d:href>
<d:status>HTTP/1.1 403 Forbidden</d:status>
<d:responsedescription>
<d:error><d:segment-must-identify-member/></d:error>
pangnirtung.img is not a collection member.
</d:responsedescription>
</d:response>
</d:multistatus>
In this example, the client attempted to position iqaluit.map after a
URI that is not an internal member of the collection /coll-1/. The
server responded to this client error with a 403 (Forbidden) status
code, indicating the failed precondition DAV:segment-must-identify-
member. Because ORDERPATCH is an atomic method, the request to
reposition nunavut.desc (which would otherwise have succeeded) failed
as well, but does not need to be expressed in the multistatus
response body.
8. Listing the Members of an Ordered Collection
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
members of an unordered collection.
However, when responding to a PROPFIND on an ordered collection, the
server MUST order the response elements according to the ordering
defined on the collection. If a collection is unordered, the client
cannot depend on the repeatability of the ordering of results from a
PROPFIND request.
In a response to a PROPFIND with Depth: infinity, members of
different collections may be interleaved. That is, the server is not
required to do a breadth-first traversal. The only requirement is
that the members of any ordered collection appear in the order
defined for that 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 or "A B E C H G F D" as well (if C is
unordered). 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
Suppose a PROPFIND request is submitted to /MyColl/, which has its
members ordered as follows.
/MyColl/
lakehazen.html
siorapaluk.html
iqaluit.html
newyork.html
>> Request:
PROPFIND /MyColl/ HTTP/1.1
Host: example.org
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" ?>
<D:propfind xmlns:D="DAV:">
<D:prop xmlns:J="http://example.org/jsprops/">
<D:ordering-type/>
<D:resourcetype/>
<J:latitude/>
</D:prop>
</D:propfind>
>> Response:
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:J="http://example.org/jsprops/">
<D:response>
<D:href>http://example.org/MyColl/</D:href>
<D:propstat>
<D:prop>
<D:ordering-type>
<D:href>DAV:custom</D:href>
</D:ordering-type>
<D:resourcetype><D:collection/></D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<J:latitude/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://example.org/MyColl/lakehazen.html</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
<J:latitude>82N</J:latitude>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<D:ordering-type/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href
>http://example.org/MyColl/siorapaluk.html</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
<J:latitude>78N</J:latitude>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<D:ordering-type/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://example.org/MyColl/iqaluit.html</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
<J:latitude>62N</J:latitude>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<D:ordering-type/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://example.org/MyColl/newyork.html</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
<J:latitude>45N</J:latitude>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
<D:propstat>
<D:prop>
<D:ordering-type/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:propstat>
</D:response>
</D:multistatus>
In this example, the server responded with a list of the collection
members in the order defined for the collection.
9. Relationship to versioned collections
The Versioning Extensions to WebDAV [RFC3253] introduce the concept
of versioned collections, recording both the dead properties and the
set of internal version-controlled bindings. This section defines
how this feature interacts with ordered collections.
This specification considers both the ordering type (DAV:ordering-
type property) and the ordering of collection members to be part of
the state of a collection. Therefore, both MUST be recorded upon
CHECKIN or VERSION-CONTROL, and both MUST be restored upon CHECKOUT,
UNCHECKOUT or UPDATE (where for compatibility with RFC 3253, only the
ordering of version-controlled members needs to be maintained).
9.1. Collection Version Properties
9.1.1. Additional semantics for DAV:version-controlled-binding-set
(protected)
For ordered collections, the DAV:version-controlled-binding elements
MUST appear in the ordering defined for the checked-in ordered
collection.
9.1.2. DAV:ordering-type (protected)
The DAV:ordering-type property records the DAV:ordering-type property
of the checked-in ordered collection.
9.2. Additional CHECKIN semantics
Additional Postconditions:
(DAV:initialize-version-controlled-bindings-ordered): If the
request-URL identified a both ordered and version-controlled
collection, then the child elements of DAV:version-controlled-
binding-set of the new collection version MUST appear in the
ordering defined for that collection.
(DAV:initialize-collection-version-ordering-type): If the
request-URL identified a both ordered and version-controlled
collection, then the DAV:ordering-type property of the new
collection version MUST be a copy of the collection’s
DAV:ordering-type property.
9.3. Additional CHECKOUT Semantics
Additional Postconditions:
(DAV:initialize-version-history-bindings-ordered): If the request
has been applied to a collection version with a DAV:ordering-type
other than "DAV:unordered", the bindings in the new working
collection MUST be ordered according to the collection version’s
DAV:version-controlled-binding-set property.
(DAV:initialize-ordering-type): If the request has been applied to
a collection version, the DAV:ordering-type property of the new
working collection MUST be initialized from the collection
version’s DAV:ordering-type property.
9.4. Additional UNCHECKOUT, UPDATE, and MERGE Semantics
Additional Postconditions:
(DAV:update-version-controlled-collection-members-ordered): If the
request modified the DAV:checked-in version of a version-
controlled collection and the DAV:ordering-type for the checked-in
version is not unordered ("DAV:unordered"), the version-controlled
members MUST be ordered according to the checked-in version’s
DAV:version-controlled-binding-set property. The ordering of
non-version-controlled members is server-defined.
(DAV:update-version-ordering-type): If the request modified the
DAV:checked-in version of a version-controlled collection, the
DAV:ordering-type property MUST be updated from the checked-in
version’s property.
10. Capability Discovery
Sections 9.1 and 15 of [RFC2518] describe the use of compliance
classes with the DAV header in responses to OPTIONS, indicating which
parts of the Web Distributed Authoring protocols the resource
supports. This specification defines an OPTIONAL extension to
[RFC2518]. It defines a new compliance class, called ordered-
collections, for use with the DAV header in responses to OPTIONS
requests. If a collection resource does support 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 the new
ordered-collections compliance class in the DAV header.
When responding to an OPTIONS request, only a collection or a null
resource can include ordered-collections in the value of the DAV
header. By including ordered-collections, the resource indicates
that its internal member URIs can be ordered. It implies nothing
about whether any collections identified by its internal member URIs
can be ordered.
Furthermore, RFC 3253 [RFC3253] introduces the live properties
DAV:supported-method-set (section 3.1.3) and DAV:supported-live-
property-set (section 3.1.4). Servers MUST support these properties
as defined in RFC 3253.
10.1. Example: Using OPTIONS for the Discovery of Support for
Ordering
>> Request:
OPTIONS /somecollection/ HTTP/1.1
Host: example.org
>> Response:
HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH
DAV: 1, 2, ordered-collections
The DAV header in the response indicates that the resource
/somecollection/ is level 1 and level 2 compliant, as defined in
[RFC2518]. In addition, /somecollection/ supports ordering. The
Allow header indicates that ORDERPATCH requests can be submitted to
/somecollection/.
10.2. Example: Using Live Properties for the Discovery of Ordering
>> Request:
PROPFIND /somecollection HTTP/1.1
Depth: 0
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
<?xml version="1.0" encoding="UTF-8" ?>
<propfind xmlns="DAV:">
<prop>
<supported-live-property-set/>
<supported-method-set/>
</prop>
</propfind>
>> Response:
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<multistatus xmlns="DAV:">
<response>
<href>http://example.org/somecollection</href>
<propstat>
<prop>
<supported-live-property-set>
<supported-live-property>
<prop><ordering-type/></prop>
</supported-live-property>
<!-- ... other live properties omitted for brevity ... -->
</supported-live-property-set>
<supported-method-set>
<supported-method name="COPY" />
<supported-method name="DELETE" />
<supported-method name="GET" />
<supported-method name="HEAD" />
<supported-method name="LOCK" />
<supported-method name="MKCOL" />
<supported-method name="MOVE" />
<supported-method name="OPTIONS" />
<supported-method name="ORDERPATCH" />
<supported-method name="POST" />
<supported-method name="PROPFIND" />
<supported-method name="PROPPATCH" />
<supported-method name="PUT" />
<supported-method name="TRACE" />
<supported-method name="UNLOCK" />
</supported-method-set>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Note that actual responses MUST contain a complete list of supported
live properties.
11. Security Considerations
This section is provided to make WebDAV implementers aware of the
security implications of this protocol.
All of the security considerations of HTTP/1.1 and the WebDAV
Distributed Authoring Protocol specification also apply to this
protocol specification. In addition, ordered collections introduce a
new security concern. This issue is detailed here.
11.1. Denial of Service and DAV:ordering-type
There may be some risk of denial of service at sites that are
advertised in the DAV:ordering-type property of collections.
However, it is anticipated that widely-deployed applications will use
hard-coded values for frequently-used ordering semantics rather than
looking up the semantics at the location specified by DAV:ordering-
type. This risk will be further reduced if clients observe the
recommendation of Section 5.1 that requests not be sent to the URI in
DAV:ordering-type.
12. Internationalization Considerations
This specification follows the practices of [RFC2518] by encoding all
human-readable content using [XML] and in the treatment of names.
Consequently, this specification complies with the IETF Character Set
Policy [RFC2277].
WebDAV applications MUST support the character set tagging, character
set encoding, and the language tagging functionality of the XML
specification. This constraint ensures that the human-readable
content of this specification complies with [RFC2277].
As in [RFC2518], names in this specification fall into three
categories: names of protocol elements such as methods and headers,
names of XML elements, and names of properties. The naming of
protocol elements follows the precedent of HTTP using English names
encoded in USASCII for methods and headers. The names of XML
elements used in this specification are English names encoded in
UTF-8.
For error reporting, [RFC2518] follows the convention of HTTP/1.1
status codes, including with each status code a short, English
description of the code (e.g., 423 Locked). Internationalized
applications will ignore this message, and display an appropriate
message in the user’s language 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 the rationale of these decisions and advice for application
implementers, see [RFC2518].
13. IANA Considerations
This document uses the namespaces defined by [RFC2518] for properties
and XML elements. All other IANA considerations mentioned in
[RFC2518] also apply to this document.
14. Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF’s procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to
obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
15. Contributors
This document has benefited from significant contributions from Geoff
Clemm, Jason Crawford, Jim Davis, Chuck Fay and Judith Slein.
16. Acknowledgements
This document has benefited from thoughtful discussion by Jim Amsden,