draft-ietf-webdav-collection-protocol-03.txt   draft-ietf-webdav-collection-protocol-04.txt 
WEBDAV Working Group J. Slein, Xerox WEBDAV Working Group J. Slein, Xerox
INTERNET DRAFT J. Davis, Xerox INTERNET DRAFT E.J. Whitehead Jr., UC Irvine
<draft-ietf-webdav-collection-protocol-03> T. Chihaya, DataChannel J. Davis, CourseNet
G. Clemm, Rational G. Clemm, Rational
C. Fay, FileNet C. Fay, FileNet
E.J. Whitehead Jr., UC Irvine J. Crawford, IBM
A. Babich, FileNet T. Chihaya, DataChannel
February 26, 1999 June 18, 1999
Expires August 26, 1999 Expires December 18, 1999
WebDAV Advanced Collections Protocol WebDAV Advanced Collections Protocol
draft-ietf-webdav-collection-protocol-04.txt
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://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth>. <http://lists.w3.org/Archives/Public/w3c-dist-auth/>.
Abstract Abstract
The base WebDAV protocol [WebDAV] provides basic support for The WebDAV Distributed Authoring Protocol provides basic support for
collections. It defines a MKCOL method for creating collections and collections, offering the ability to create and list unordered
specifies how other HTTP and WebDAV methods interact with collections. collections. Many applications, however, need more powerful
It supports internal members of collections, which it defines as URIs collections, especially for resource sharing and collection ordering.
that are immediately relative to the URI of the collection.
Many applications, however, need more powerful collections. There are
two areas in particular where more powerful functionality is often
needed: referential resources and ordering.
This draft specifies extensions to the base WebDAV protocol to support This specification defines HTTP methods, headers, and XML elements that
these more powerful collections. supplement the WebDAV Distributed Authoring Protocol to support resource
sharing and collection orderings. Resource sharing is provided by
bindings and redirect references. Bindings create new mappings of URIs
to resources, while redirect references respond to most requests with an
HTTP Redirection (i.e., a 302 status code). An ordered collection
always returns a listing of its members in a specific order. Together,
these capabilities are referred to as WebDAV Advanced Collections.
Table of Contents Table of Contents
1 Notational Conventions........................................4 1 Notational Conventions......................................3
2 Terminology...................................................4 2 Terminology.................................................4
3 Introduction..................................................5 3 Introduction................................................5
4 Referential Resources.........................................5
4.1 Scope.........................................................5
4.2 Overview......................................................6
4.3 Creating Referential Resources................................8
4.3.1 The MKREF Method..............................................8
4.3.2 Status Codes..................................................9
4.3.3 Example: MKREF................................................9
4.4 Listing Referential Members of a Collection...................9
4.4.1 Example: PROPFIND on a Collection with References............10
4.4.2 Example: PROPFIND with No-Passthrough on a Collection with
References...................................................12
4.5 Copying Referential Resources................................15
4.5.1 COPY for Direct References...................................15
4.5.2 COPY for Redirect References.................................16
4.5.3 Example: COPY on a Direct Reference..........................16
4.5.4 Example: COPY on a Redirect Reference........................16
4.5.5 Example: COPY on a Collection That Contains a Direct
Reference and a Redirect Reference...........................17
4.6 Deleting and Moving Referential Resources....................18
4.7 Locking Referential Resources................................19
4.7.1 LOCK on Direct References....................................19
4.7.2 LOCK on Redirect References..................................20
4.7.3 Example: LOCK on a Direct Reference..........................21
4.7.4 Example: LOCK on a Redirect Reference........................22
4.7.5 Example: LOCK on a Collection That Contains a Direct
Reference and a Redirect Reference...........................22
4.8 Other WebDAV Operations on Redirect Referential Resources....24
4.8.1 Example: PROPPATCH on a Redirect Reference...................24
4.9 Other WebDAV Operations on Direct Referential Resources......24
4.9.1 Example: PROPPATCH on a Direct Reference.....................25
4.10 HTTP Operations on Redirect Referential Resources............25
4.10.1 Example: GET on a Redirect Reference.........................26
4.10.2 Example: GET on a Redirect Reference with No-Passthrough.....26
4.11 HTTP Operations on Direct Referential Resources..............26
4.11.1 Example: GET on a Direct Reference...........................26
4.11.2 Example: GET on a Direct Reference with No-Passthrough.......26
4.12 Operations on Targets of Referential Resources...............26
4.13 Discovering a Target’s References............................26
4.14 Behavior of Dangling Direct References.......................27
4.14.1 Example: PROPFIND on a Collection with a Dangling Direct
Reference....................................................28
4.15 Chains of Direct References..................................29
4.16 URIs and References..........................................29
5 Ordered Collections..........................................30
5.1 Overview.....................................................30
5.2 Creating an Ordered Collection...............................31
5.2.1 Overview.....................................................31
5.2.2 Status Codes.................................................31
5.2.3 Example: Creating an Ordered Collection......................31
5.3 Setting the Position of a Collection Member..................32
5.3.1 Overview.....................................................32
5.3.2 Status Codes.................................................32
5.3.3 Examples: Setting the Position of a Collection Member........32
5.4 Changing the Semantics of a Collection Ordering..............33
5.5 Changing the Position of a Collection Member.................33
5.5.1 The ORDERPATCH Method........................................33
5.5.2 Status Codes.................................................33 4 Shared Resources............................................6
5.5.3 Example: Changing the Positions of Collection Members in 4.1 Overview....................................................6
the Ordering.................................................34 4.2 Bindings....................................................7
5.5.4 Design Rationale.............................................35 4.2.1 BIND Method.................................................8
6 Headers......................................................35 4.2.2 Bindings to Collections.....................................9
6.1 Ref-Target Entity Header.....................................35 4.2.3 URI Mappings Created by BIND...............................10
6.1.1 Example: Resolving a Relative URI in Ref-Target..............36 4.2.4 Example: Generating the Set of URI Mappings................10
6.2 Ref-Type Entity Header.......................................37 4.2.5 Status Codes...............................................11
6.3 Ref-Integrity Request Header.................................37 4.2.6 Example: BIND..............................................11
6.4 No-Passthrough Request Header................................37 4.2.7 Example: BIND Conflict.....................................12
6.5 Ordered Entity Header........................................38 4.2.8 DELETE and Bindings........................................12
6.6 Position Request Header......................................38 4.2.9 COPY and Bindings..........................................13
7 Properties...................................................39 4.2.10 MOVE and Bindings..........................................13
7.1 reftarget Property...........................................39 4.2.11 LOCK and UNLOCK............................................15
7.1.1 Example: Resolving a Relative URI in the DAV:reftarget.......39 4.2.12 Bindings and Other Methods.................................16
7.2 refintegrity Property........................................40 4.2.13 Discovering the Bindings to a Resource.....................16
7.3 reftype Property.............................................41 4.3 Redirect References........................................17
7.4 location Property............................................41 4.3.1 MKREF Method...............................................17
7.5 references Property..........................................41 4.3.2 Listing the Redirect References in a Collection............19
7.6 orderingtype Property........................................42 4.3.3 Copying Redirect References................................22
8 XML Elements.................................................42 4.3.4 Deleting and Moving Redirect References....................24
8.1 reference XML Element........................................42 4.3.5 Locking Redirect References................................24
8.2 direct XML Element...........................................42 4.3.6 LOCK on Redirect References................................25
8.3 redirect XML Element.........................................42 4.3.7 Other Operations on Redirect References....................28
8.4 weak XML Element.............................................43 4.3.8 Operations on Targets of Redirect References...............30
8.5 unordered XML Element........................................43 4.3.9 Relative URIs in Ref-Target and DAV:reftarget..............31
8.6 custom XML Element...........................................43 4.3.10 Redirect References to Collections.........................32
8.7 order XML Element............................................43 5 Ordered Collections........................................33
8.8 ordermember XML Element......................................43 5.1 Overview...................................................33
8.9 position XML Element.........................................44 5.2 Creating an Ordered Collection.............................34
8.10 first XML Element............................................44 5.2.1 Overview...................................................34
8.11 last XML Element.............................................44 5.2.2 Example: Creating an Ordered Collection....................34
8.12 before XML Element...........................................44 5.3 Setting the Position of a Collection Member................35
8.13 after XML Element............................................44 5.3.1 Overview...................................................35
9 Extensions to the DAV:response XML Element for Multi-Status 5.3.2 Status Codes...............................................35
Responses....................................................45 5.3.3 Examples: Setting the Position of a Collection Member......35
10 Capability Discovery.........................................45 5.4 Changing the Semantics of a Collection Ordering............36
10.1 Using OPTIONS................................................45 5.5 Changing the Position of a Collection Member...............36
10.2 Example: Capability Discovery................................46 5.5.1 ORDERPATCH Method..........................................36
11 Dependencies on Other Specifications.........................46 5.5.2 Status Codes...............................................36
12 Security Considerations......................................46 5.5.3 Example: Changing Positions in an Ordered Collection.......37
12.1 Privacy Concerns.............................................46 5.5.4 Example: Failure of an ORDERPATCH Request..................38
12.2 Redirect Loops...............................................47 6 Headers....................................................39
12.3 References and Denial of Service.............................47 6.1 All-Bindings Request Header................................39
12.4 References May Reveal Private Locations......................47 6.2 Ref-Target Entity Header...................................39
12.5 DAV:references and Denial of Service.........................48 6.3 Resource-Type Entity Header................................40
12.6 DAV:references and Malicious Deletion of Resources...........48 6.4 Passthrough Request Header.................................40
12.7 Denial of Service and DAV:orderingtype.......................48 6.5 Ordered Entity Header......................................40
13 Internationalization Considerations..........................48 6.6 Position Request Header....................................40
14 IANA Considerations..........................................48 7 Status Codes...............................................41
15 Copyright....................................................49
16 Intellectual Property........................................49
17 Acknowledgements.............................................49
18 References...................................................49
18.1 Normative References.........................................49
18.2 Informational References.....................................49 7.1 506 Loop Detected..........................................41
19 Authors' Addresses...........................................50 7.2 425 Unordered Collection...................................41
20 Appendices...................................................50 8 Properties.................................................41
8.1 reftarget Property.........................................41
8.2 location Property..........................................42
8.3 bindings Property..........................................42
8.4 orderingtype Property......................................42
9 XML Elements...............................................43
9.1 redirectref XML Element....................................43
9.2 segment XML Element........................................43
9.3 unordered XML Element......................................43
9.4 custom XML Element.........................................43
9.5 order XML Element..........................................44
9.6 ordermember XML Element....................................44
9.7 position XML Element.......................................44
9.8 first XML Element..........................................44
9.9 last XML Element...........................................44
9.10 before XML Element.........................................45
9.11 after XML Element..........................................45
9.12 options XML Element........................................45
9.13 orderingoptions XML Element................................45
10 Extensions to the DAV:response XML Element for Multi-Status
Responses..................................................45
11 Capability Discovery.......................................46
11.1 Compliance Classes.........................................46
11.2 Example: Discovery of Compliance Classes...................46
11.3 Additional Advanced Collections Capabilities...............47
11.4 Example: Discovery of Ordering Options.....................47
12 Security Considerations....................................48
12.1 Privacy Concerns...........................................48
12.2 Redirect Loops.............................................48
12.3 Redirect References, Bindings, and Denial of Service.......48
12.4 Private Locations May Be Revealed..........................49
12.5 DAV:bindings and Denial of Service.........................49
12.6 Denial of Service and DAV:orderingtype.....................49
13 Internationalization Considerations........................49
14 IANA Considerations........................................50
15 Copyright..................................................50
16 Intellectual Property......................................50
17 Acknowledgements...........................................50
18 References.................................................50
18.1 Normative References.......................................50
18.2 Informational References...................................51
19 Authors' Addresses.........................................51
20 Appendices.................................................52
20.1 Appendix 1: Extensions to the WebDAV Document Type 20.1 Appendix 1: Extensions to the WebDAV Document Type
Definition...................................................50 Definition.................................................52
20.2 Appendix 2: Summary of Referencing Headers Required in
Responses....................................................51
20.3 Appendix 3: Summary of Method Semantics for References.......52
1 Notational Conventions 1 Notational Conventions
Since this document describes a set of extensions to the HTTP/1.1 Since this document describes a set of extensions to the HTTP/1.1
protocol, the augmented BNF used here to describe protocol elements is protocol, the augmented BNF used here to describe protocol elements is
exactly the same as described in Section 2.1 of [HTTP]. Since this exactly the same as described in Section 2.1 of [HTTP]. Since this
augmented BNF uses the basic production rules provided in Section 2.2 of augmented BNF uses the basic production rules provided in Section 2.2 of
[HTTP], these rules apply to this document as well. [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 Terminology 2 Terminology
The terminology used here follows and extends that in the base WebDAV The terminology used here follows and extends that in the WebDAV
protocol specification [WebDAV]. Distributed Authoring Protocol specification [WebDAV]. Definitions of
the terms resource, Uniform Resource Identifier (URI), and Uniform
Resource Locator (URL) are provided in [URI].
Collection Association
A resource that contains a set of URIs, termed member URIs, which A direct or indirect connection between a resource and a namespace
identify member resources element that supports resource sharing. The bindings, URI
mappings, and redirect references defined in this specification
are types of associations.
Member URI URI Mapping
A URI which is a member of the set of URIs contained by a An association between an absolute URL or URI and a resource.
collection Since a resource can represent items that are not network
retrievable, as well as those that are, it is possible for a
resource to have zero, one, or many URI mappings to URLs or URIs.
Mapping a resource to an "http" scheme URL makes it possible to
submit HTTP protocol requests to the resource using the URL.
Referential Resource (or Reference) Path Segment
A resource that has no body of its own (though it does have Informally, the characters found between slashes ("/") in a URL or
properties), but rather is a reference to another resource URI. Formally, as defined in section 3.3 of [URI].
Ordinary Resource Binding
A resource that is not a reference to another resource An association between a single path segment (in a collection) and
a resource. A binding creates one or more URI mappings, and hence
is a mechanism for resource sharing, allowing a single resource to
be accessed from multiple locations in a URI namespace.
Target Resource Collection
The resource referenced by a referential resource A resource that contains, as part of its state, a set of bindings
which identify member resources.
Direct Reference Internal Member URI
A reference that is resolved by the server without any client The URI mapping, created by a binding that is contained in a
action, giving the client the illusion that it is operating collection. While, in general, bindings can create multiple URI
directly on the target resource mappings to a resource, for a given request, only one of these URI
mappings is referred to as the internal member. The URI of the
parent collection used in a given request determines the base URI
for internal member URI calculation.
In [WebDAV], a collection is defined as containing a list of
internal member URIs, where an internal member URI is the URI of
the collection, plus a single path segment. This definition
combines the two concepts of binding and mapping that are
separated in this specification. As a result, this specification
redefines a collection's state to be a set of bindings, and
redefines an internal member URI to be a mapping derived from a
binding. After this redefinition, an internal member URI can be
used when reading [WebDAV] without loss of meaning. For purposes
of interpretation, when [WebDAV] discusses a collection
"containing" an internal member URI, this should be read as the
collection containing a binding whose mapping to a URI creates an
internal member URI, in this sense "containing" the internal
member URI. The authors of this specification anticipate and
recommend that future revisions of [WebDAV] perform a full
reconciliation of terms between these two specifications.
Reference
A resource whose purpose is to provide access to another resource.
Redirect Reference Redirect Reference
A reference that requires client action before it can be resolved, A resource whose purpose is to provide access to another resource,
so that the client is aware that a reference is mediating between and that requires client action before it can be resolved. The
it and the target resource client is aware that this type of reference is mediating between
it and the target resource.
Strong Reference Ordinary Resource
A reference whose referential integrity is enforced by the server A resource that is not a reference to another resource.
Weak Reference Target Resource
A reference whose referential integrity is not enforced by the The resource referenced by a referential resource.
server
Referential Integrity Referential Integrity
The integrity of a reference is preserved as long as it points to The integrity of a reference is preserved as long as it points to
the same resource it pointed to when it was created. Its the same resource it pointed to when it was created. Its
integrity may be destroyed if the target resource is moved without integrity may be destroyed if the target resource is moved without
updating the reference to reflect its new location, or if the updating the reference to reflect its new location, or if the
target resource is deleted. target resource is deleted while a reference to it still exists.
3 Introduction 3 Introduction
The simple collections that the base WebDAV specification supports are The simple collections that the WebDAV Distributed Authoring Protocol
powerful enough to be widely useful. They provide for the hierarchical specification supports are powerful enough to be widely useful. They
organization of resources, with mechanisms for creating and deleting provide for the hierarchical organization of resources, with mechanisms
collections, copying and moving them, locking them, adding members to for creating and deleting collections, copying and moving them, locking
them and removing members from them, and getting listings of their them, adding members to them and removing members from them, and getting
members. Delete, copy, move, list, and lock operations can be applied listings of their members. Delete, copy, move, list, and lock
recursively, so that a client can operate on whole hierarchies with a operations can be applied recursively, so that a client can operate on
single request. whole hierarchies with a single request.
Many applications, however, need more powerful collections. There are Many applications, however, need more powerful collections. There are
two areas in particular where more powerful functionality is often two areas in particular where more powerful functionality is often
needed: references and ordering. needed: shared resources and ordering. This specification defines
extensions to [WebDAV] in both these areas.
References make it possible for many collections, on the same or Organizing resources into hierarchies places them into smaller
different servers, to share the same resource. Because the collections groupings, known as collections, which are more easily browsed and
share the resource by referencing it, only one physical copy of the manipulated than a flat namespace. However, hierarchies require
resource need exist, and any changes made in the resource are visible categorization decisions that locate resources at a single location in
from all the collections that reference it. the hierarchy, a drawback when a resource has multiple valid categories.
For example, in a hierarchy of vehicle descriptions containing
collections for cars and boats, a description of a combination car/boat
vehicle could belong in either collection. Ideally, the description
It is useful for many applications to be able to impose an ordering on a should be accessible from both.
collection. Orderings may be based on property values, but they may be
completely independent of any properties on the resources identified by
the collection’s member URIs. Orderings based on properties can be
obtained using a search protocol [DASL], but orderings not based on
properties need some other mechanism.
Since these two areas are independent of each other, servers may elect Hierarchies also make resource sharing more difficult, since resources
to comply with the Referential Resources section of this specification that have utility across many collections are still forced into a single
or with the Ordered Collections section or both. A server that supports collection. For example, the mathematics department at one university
referencing MUST support redirect references, and MAY support direct might create a collection of information on fractals that contains
references. A server MUST advertise its compliance with particular bindings to some local resources, but also provides access to some
parts of this specification through its response to an OPTIONS request, resources at other universities. For many reasons, it may be
as specified in Section 10 below. undesirable to make physical copies of the shared resources on the local
server - to conserve disk space, to respect copyright constraints, or to
make any changes in the shared resources visible automatically.
4 Referential Resources This protocol provides two mechanisms for allowing resources to appear
in multiple places in an http URL hierarchy, and for sharing resources:
bindings and redirect references.
4.1 Scope The WebDAV Distributed Authoring Protocol added to the Web the ability
to navigate Web resources hierarchically, complementing existing
hypertext navigation facilities. In hypertext navigation, links appear
in a specific order in a document. By contrast, hierarchical navigation
has fewer mechanisms for expressing the ordering of a set of resources.
[CollReq] distinguishes between "weak" references and "strong" There are many scenarios where it is useful to impose an ordering on a
references, and also between "redirect" references and "direct" collection, such as expressing a recommended access order, or a revision
history order. Orderings may be based on property values, but they may
be completely independent of any properties on the resources identified
by the collection's internal member URIs. Orderings based on properties
can be obtained using a search protocol [DASL], but orderings not based
on properties need some other mechanism. These orderings generally need
to be maintained by a human user. The ordering protocol defined here
focuses on support for such human-maintained orderings, but also allows
for server-maintained orderings.
references. This specification supports weak references, direct 4 Shared Resources
references, and redirect references, and is designed so that it can be
extended to support strong references in the future.
Strong references are references whose integrity is enforced by the 4.1 Overview
server; weak references are those whose integrity is not enforced by the
server. Strong references and weak references are both useful in
different contexts. Some applications cannot tolerate broken links. A
software development application, for example, must be able to rely on
the integrity of references to component modules. Such applications must
be able to request strong references. Other applications may want to
reference target resources on multiple servers, where referential
integrity cannot be enforced, and may be less concerned about possible
broken references.
Several considerations led to the decision not to support strong Shared resources make the same resource accessible from multiple
references in the current specification. First, there are many possible locations in http URL namespaces. This protocol provides two mechanisms
policies that applications and services might use in enforcing for sharing resources: bindings and redirect references.
referential integrity. Some examples are:
o Delete strong references when their targets are deleted. The binding mechanism defined in this specification provides a way for
o Decline to delete targets of strong references. clients to add new URI mappings to existing resources. A URI mapping is
o Notify strong references when their targets have been deleted. an association between an absolute URI and a resource, which makes it
o Replace strong references with copies of their targets before possible to submit requests to the resource using that URI as the
deleting the targets. Request-URI. Bindings, and the URI mappings based on them, are appealing
mechanisms for resource sharing because:
There appears to be no common practice in this area. Moreover, some of o Once URI mappings are created with a BIND request, clients need do
the policies have significant security risks. nothing special to use them. They behave just like any other URI
mappings, transparently applying operations to the target resource.
o HTTP and WebDAV servers already provide URI mappings, so there is
little extra work involved in allowing clients to create them.
o The integrity of bindings is guaranteed. MOVE and DELETE operations
cannot leave bindings in an inconsistent state.
o Moving a target of strong references could be a security risk to the A limitation of bindings is that a server would need proxy capabilities
owner of the target by revealing secret locations on the target's in order to support bindings to resources on another server. In light
server. of this complexity, support for cross-server bindings is OPTIONAL.
o A strong reference could be a security risk to the owner of the
reference by revealing secret locations on his server.
o The presence of strong references to resources on a server could make
it impossible to reclaim space on that server by moving or deleting
those target resources.
These considerations together led to the decision not to support strong A redirect reference is a resource whose purpose is to provide access to
references in the short term. another resource. It redirects most requests on the reference to
another resource, thereby providing a form of mediated access to the
other resource. Since the HTTP 302 (Moved Temporarily) status code is
used to redirect client requests on a redirect reference, from the
clientÆs point of view redirect references are less convenient to use
than bindings. Redirect references require action by the client before
they can be resolved. Moreover, the server is not required to enforce
the integrity of redirect references. However, redirect references have
a number of advantages:
4.2 Overview o They are simple for servers to implement. Servers already provide
redirect resources in the form of 301 / 302 redirection control, and
the same mechanism can be used for redirect references.
o The same simple implementation works equally well for target
resources that reside on the same server and for target resources
that reside on a different server.
o Redirect references have only limited security implications.
o Since redirect references are resources, they can carry properties of
their own.
A referential resource is a resource that has no body of its own, but Ideally, non-referencing clients should be able to use both bindings and
instead references another resource. The resource it references may redirect references. This goal is more difficult to meet for redirect
have a URI in the same collection as the reference, or in any other references, since client action is required to resolve them. The
collection. This target resource may be a collection or a simple strategy of having redirect references respond to most requests with a
resource or another reference, or any other sort of resource that may be 302 (Moved Temporarily), accompanied by the URI of the target resource
defined in the future. A resource may be the target of any number of in the Location header, fulfills this goal in most cases.
referential resources. To make it possible to distinguish references
from ordinary resources, a new value of the DAV:resourcetype property is
defined here. The DAV:resourcetype property of all references MUST have
the value DAV:reference.
Redirect references are references that require action by the client 4.2 Bindings
before they can be resolved. They are simple for servers to implement, Bindings are part of the state of a collection. In general, there is a
straightforward for clients to use, and have only limited security one-to-one correspondence between a collection's bindings and its
implications. Any server that complies with WebDAV referencing MUST internal member URIs. The URI segment associated with a resource by one
provide redirect references. of a collection's bindings is also the final segment of one of the
collection's internal member URIs. The final segment of each internal
member URI identifies one of the bindings that is part of the
collection's state, unless the internal member URI is not bound to a
resource.
If the client is aware that it is operating on a redirect reference, it Even though a binding is just an association between a path segment and
can resolve the reference by retrieving the reference’s DAV:reftarget a resource, a binding creates one or more URI mappings of a URI to a
property, whose value is the URI of the target resource. It can then resource. For example, if the segment "index.html" is being bound to a
submit requests to the target resource. resource in a collection with URL "http://www.foo.net/A/", the binding
creates a URI mapping of URL "http://www.foo.net/A/index.html" to the
HTML resource. If the parent collection is then bound to the segment
"B", this creates two URI mappings, "http://www.foo.net/B/" to the
collection resource, and "http://www.foo.net/B/index.html" to the HTML
resource. Both the collection and the HTML resource are now accessible
via two URLs apiece.
Otherwise, the client submits a request to the redirect reference. For For a resource implemented by a computer, the relationship between a URI
most operations, the response is a 302 (Moved Temporarily), accompanied mapping and a resource is highlighted in the following diagram:
by the Ref-Type header with the value "DAV:redirect" and the Location
header with the URI of the target resource. The client can then
resubmit the request to the URI of the target resource. A few
operations, for reasons that will be explained, are exceptions to this
general behavior. These exceptional operations are applied to the
reference itself and do not result in a 302 response.
Direct references, in contrast, are resolved automatically by the URI 1 URI 2 ... URI N
server. They give the client the illusion that it is operating directly | | |
on the target resource. These references are more complex for the | | | <------- URI Mappings
server to implement, and raise additional security issues. | | |
Consequently, servers are not required to provide direct references in +---------------------+
order to be compliant with WebDAV referencing. | Resource R |
+---------------------+
The default behavior of a direct reference is to apply most operations As discussed in [URI], a resource is an abstraction that maps a URI to
directly to its target, so that the client is not aware that a reference an entity or set of entities. This resource can have multiple URIs/URLs
is mediating between it and the target resource. The exceptions are mapped to it.
operations that affect membership in a collection rather than the state
of the target resource. At present, the operations that fall into this
category are DELETE and MOVE. These operations are applied to the
reference itself rather than to its target, so that only the collection
containing the reference is affected.
The No-Passthrough request header is also provided, to force an The identity of a binding is determined by the URI segment (in its
operation to be applied to the reference itself rather than its target. collection) and the resource that the binding associates. If the
It can be used with most requests to direct or redirect references. resource is destroyed, the binding also goes out of existence. If the
This header is particularly useful with PROPFIND, to allow clients to URI segment comes to be associated with a different resource, the
view the reference’s own properties. original binding ceases to exist and another binding is created.
Ideally, non-referencing clients should be able to use both direct and Bindings are not unique to advanced collections, although the BIND
redirect references. This goal is more difficult to meet for redirect method for explicitly creating bindings is introduced here. Existing
references, since client action is required to resolve them. The methods that create resources, such as PUT, MOVE, COPY, and MKCOL,
strategy of having redirect references respond to most requests with a implicitly create bindings. There is no difference between implicitly
302 (Moved Temporarily), accompanied by the URI of the target resource created bindings and bindings created with BIND.
in the Location header, fulfills this goal in most cases.
To distinguish between direct and redirect references, a new DAV:reftype Since a binding is an association between a path segment and a resource,
property is defined, with the values DAV:direct and DAV:redirect. Every it would be very undesirable if one binding could be destroyed as a side
reference MUST have the DAV:reftype property. The DAV:reftype property effect of operating on the resource through a different binding. It is
of a direct reference MUST have the value DAV:direct. The DAV:reftype not acceptable for a DELETE or MOVE through a different binding to
property of a redirect reference MUST have the value DAV:redirect. destroy the resource or fail to update one binding, turning that binding
into a dangling path segment. As a result, implementations MUST act to
ensure the integrity of bindings.
Every reference MUST have the DAV:reftarget property, whose value is the It is especially difficult to maintain the integrity of cross-server
bindings. Unless the server where the resource resides knows about all
bindings on all servers to that resource, it may unwittingly destroy the
resource or move it without notifying a server where a binding resides.
For example, if server A permits creation of a binding to a resource on
server B, server A must notify server B about its binding and must have
an agreement with B that B will not destroy the resource while A's
binding exists. Otherwise server B may receive a DELETE request that it
thinks removes the last binding to the resource and destroy the resource
while A's binding still exists.
URI of the reference’s target resource. Consequently, support for cross-server bindings is OPTIONAL.
Although strong references are not currently supported, a new 4.2.1 BIND Method
DAV:refintegrity property is defined in anticipation of future support
for strong references. DAV:refintegrity will allow clients to
distinguish between weak and strong references. All references MUST
have this property. Although the only currently defined for
DAV:refintegrity is DAV:weak, other values may be defined in the future,
and servers MAY use extension values to identify their policy for
enforcing referential integrity for that resource.
4.3 Creating Referential Resources The BIND method creates a new binding from the final segment of the
Request-URI (minus any trailing slash) to the resource identified
by the Destination header. This binding is added to the collection
identified by the Request-URI minus its trailing slash (if present) and
final segment. The Destination header is defined in Section 9.3 of
4.3.1 The MKREF Method [WebDAV].
Referential resources are created using the MKREF method. The request- If a server cannot guarantee the binding behavior specified for GET
URI of the MKREF request identifies the resource to be created. The (Section 4.2.12), DELETE (Section 4.2.8), and MOVE (Section 4.2.10), the
REQUIRED Ref-Target header contains the URI of the target resource. BIND request MUST fail with a 501 (Not Implemented) status code.
An OPTIONAL Ref-Integrity request header is defined below, primarily for If the Request-URI ends in a slash ("/") (i.e., the Request-URI
future support for strong references. The only values currently defined identifies a collection), the resource identified by the Destination
for this header are "do-not-enforce" and "enforce", although other header MUST be a collection resource, or the request fails with a 409
values may be used by private agreement. If a server receives the value (Conflict) status code. This ensures that URIs ending in a slash are
"do-not-enforce", it MUST NOT enforce referential integrity for the always bound to collections. If the Request-URI does not contain a path
reference being created. If a server receives the value "enforce", it segment (i.e., it consists simply of a slash "/"), the BIND operation
MUST enforce referential integrity for the reference being created, but MUST fail and report a 409 (Conflict) status code.
is free to follow any policy it chooses for enforcing referential
integrity. If the Ref-Integrity header is not used with a MKREF
request, the server MAY enforce referential integrity, but is not
required to do so, and if it does enforce referential integrity, it may
do so according to any policy it likes. Clients and servers MAY use
other values of Ref-Integrity by private agreement, but if a server
receives a value it does not understand, it MUST fail the request.
An OPTIONAL Ref-Type general header is defined below, with values After successful processing of a BIND request, it MUST be possible for
"DAV:direct" and "DAV:redirect". The default value is "DAV:redirect" if clients to use the Request-URI to submit requests to the resource
the header is not present. identified by the Destination header.
An OPTIONAL Position request header supports ordered collections by By default, if the Request-URI identifies an existing binding, the new
allowing the client creating a reference to specify where the new member binding replaces the existing binding. This default binding replacement
is to be placed in the collection's ordering. (This header can also be behavior can be overridden using the Overwrite header defined in Section
used with any other method that adds a member to a collection, to 9.6 of [WebDAV].
specify its position in the collection ordering.)
When a server processes a MKREF request, it MUST set the The Position request header (defined in Section 6.6) MAY be used in BIND
DAV:resourcetype property (defined in [WebDAV]) of the new resource to requests.
be DAV:reference.
When a server processes a MKREF request, it MUST set the DAV:reftarget A server MAY allow the BIND method to be used to create bindings to
property to the URI of the target resource. resources that support content negotiation or to resources that
dynamically generate response entities.
When a server processes a MKREF request, it MUST set the DAV:reftype 4.2.2 Bindings to Collections
property based on the value of the Ref-Type header.
When a server processes a MKREF request, it MUST set the BIND can create a binding to a collection resource. A collection
accessed through such a binding behaves exactly as would a collection
accessed through any other binding. Bindings to collections can result
in loops, which servers MUST detect when processing "Depth: infinity"
requests. When a loop is detected, the server MUST respond with a 506
(Loop Detected) status code (defined in Section 7.1).
DAV:refintegrity property to "DAV:weak" if it is not enforcing Creating a new binding to a collection makes each resource associated
referential integrity for the newly-created reference. If it is with a binding in that collection accessible via a new URI, but does not
enforcing referential integrity for the new reference, it MAY set the result in the creation of a new binding for each of these resources.
value of DAV:refintegrity to an extension value identifying its
enforcement policy.
The client MUST NOT send any content with the MKREF request, and so MUST For example, suppose a new binding COLLX is created for collection C1 in
NOT use the Content-Length or Transfer-Encoding headers. (See [HTTP] the figure below. It immediately becomes possible to access resource R1
Section 4.3.) using the URI /COLLX/x.gif and to access resource R2 using the URI
/COLLX/y.jpg, but no new bindings for these child resources were
created. This is because bindings are part of the state of a
collection, and associate a URI that is *relative to that collection*
with its target resource. No change to the bindings in Collection C1 is
needed to make its children accessible using /COLLX/x.gif and
/COLLX/y.jpg.
If a MKREF request has a request-URI that identifies an existing +-------------------------+
resource, the request MUST fail. This behavior is analogous to the | Root Collection |
behavior of the MKCOL method [WebDAV].
4.3.2 Status Codes | (properties) |
| bindings: |
| coll1 COLLX |
+-------------------------+
| /
| /
| /
+------------------+
| Collection C1 |
| (properties) |
| bindings: |
| x.gif y.jpg |
+------------------+
| \
| \
| \
+-------------+ +-------------+
| Resource R1 | | Resource R2 |
+-------------+ +-------------+
Servers MUST use the HTTP/1.1 status codes as defined in [HTTP]. Some 4.2.3 URI Mappings Created by BIND
likely client errors for MKREF include:
400 (Bad Request): The client attempted to send content with the The set of URI mappings created by a successful BIND operation MUST be
request, or set an invalid value for the Ref-Target, Ref-Integrity, Ref- determined as follows:
Type, or Position header.
405 (Method Not Allowed): A resource already exists at the request-URI. 1. Start with an empty set of URLs, called U.
2. Take the Request-URI and remove path segments (and associated "/"
characters) from the right until either (a) a non-WebDAV collection, or
a non-WebDAV advanced collection is found, or (b) the root, "/" is
reached (i.e., no characters after the scheme and authority parts of the
URL). This is the base URL B.
3. Add B, and all possible domain name variants of B (i.e., all other
domain names which can be substituted for the domain name in B, and
still retrieve the resource mapped to B), to URL set U.
4. Calculate the next path segment of the Request-URI, going from right
to left, and call it S, which is bound to resource R.
5. For each member of URL set U, called Um, remove Um, then for every
possible binding to R, create a new URL by adding the binding's path
segment to Um, then add this new URL to U.
6. If there is no further path segment, then U has the complete set of
URI mappings. Otherwise, go back to step 4.
4.2.4 Example: Generating the Set of URI Mappings
Assume a server responds to two domain names, www.fuzz.com, and
fuzz.com, and has a top level that is not WebDAV-aware, called A/.
Below A/ is an advanced collection that is bound to both 1/ and one/. In
collection one/ there is a resource called index.html.
>> Request:
BIND /A/1/info.html HTTP/1.1
Host: www.fuzz.com
Destination: http://www.fuzz.com/A/one/index.html
>> Response:
HTTP/1.1 201 Created
The set of all possible URI mappings to the resource identified by
http://www.fuzz.com/A/one/index.html is calculated as follows:
1. U is empty.
2. The base URL, B, is http://www.fuzz.com/A/, since A/ is not WebDAV-
aware.
3. Since there are two domain names for this server, the domain name
variations of B are added to U, making U contain: http://www.fuzz.com/A/
and http://fuzz.com/A/.
4. (iteration 1) The next path segment of the Request-URI is 1/, which
is bound to an advanced collection resource, R.
5. (iteration 1) Since the advanced collection resource R is bound to 1/
and one/, the value of U after the operation is:
http://www.fuzz.com/A/1/, http://www.fuzz.com/A/one/,
http://fuzz.com/A/1/, and http://fuzz.com/A/one/.
6. Go back to step 4, since there is one more path segment in the
Request-URI.
4. (iteration 2) The next path segment of the Request-URI is info.html,
which is bound to an HTML resource, R.
5. (iteration 2) Since the HTML resource is bound to info.html and
index.html, the value of U after the operation is:
http://www.fuzz.com/A/1/index.html, http://www.fuzz.com/A/1/info.html,
http://www.fuzz.com/A/one/index.html,
http://www.fuzz.com/A/one/info.html, http://fuzz.com/A/1/index.html,
http://fuzz.com/A/1/info.html, http://fuzz.com/A/one/index.html,
http://fuzz.com/A/one/info.html.
6. Since there are no further path segments in the Request-URI, U now
has the complete set of URI mappings for the resource identified by the
Destination header.
4.2.5 Status Codes
201 (Created): The binding was successfully created.
400 (Bad Request): The client set an invalid value for the Destination
or Position header.
409 (Conflict): Several conditions may produce this response. The URI
in the Destination header is not mapped to a resource. The request is
attempting to create a binding in a collection that does not exist. The
request is attempting to position the binding in an unordered
collection. The request is attempting to re-bind the top-level
collection.
412 (Precondition Failed): The Overwrite header is "F", and a binding
already exists for the request-URI.
4.2.6 Example: BIND
>> Request:
BIND /~whitehead/dav/spec08.txt HTTP/1.1
Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/pub/i-d/draft-webdav-protocol-08.txt
>> Response:
HTTP/1.1 201 Created
The server created a new binding, associating "spec08.txt" with the
resource identified by the URL "http://www.ics.uci.edu/pub/i-d/draft-
webdav-protocol-08.txt". Clients can now use the Request-URI,
"http://www.ics.uci.edu/~whitehead/dav/spec08.txt", to submit requests
to that resource. As part of this operation, the server added the
binding "spec08.txt" to collection /~whitehead/dav/.
4.2.7 Example: BIND Conflict
>> Request:
BIND /press/prlogo.gif HTTP/1.1
Host: www.softcorp.com
Destination: http://www.softcorp.com/logos/
>> Response:
HTTP/1.1 409 Conflict
The client requested the server to create a binding between "prlogo.gif"
and the resource identified by the URL "http://www.softcorp.com/logos/".
Since the Destination does end in a slash, while the Request-URI does
not, the server failed the request, returning a 409 (Conflict) status
code.
4.2.8 DELETE and Bindings
The DELETE method requests that the server remove the binding between
the resource identified by the Request-URI and the binding name, the
last path segment of the Request-URI. The binding MUST be removed from
its parent collection, identified by the Request-URI minus its trailing
slash (if present) and final segment. The All-Bindings header may be
used with DELETE to request that the server remove all bindings to the
resource identified by the Request-URI.
Once all bindings to the resource are removed, the server MAY reclaim
system resources associated with the resource. If DELETE removes a
binding to a resource, but there remain other bindings to that resource,
the server MUST NOT reclaim system resources associated with the
resource.
Since DELETE as specified in [WebDAV] is not an atomic operation, it may
happen that parts of the hierarchy under the request-URI cannot be
deleted. In this case, the response is as described in [WebDAV].
[HTTP] states that "the DELETE method requests that the origin server
delete the resource identified by the Request-URI." Because [HTTP] did
not distinguish between bindings and resources, the intent of its
definition of DELETE is unclear. We consider the definition presented
here to be a clarification of the definition in [HTTP].
Section 8.6.1 of [WebDAV] states that during DELETE processing, a server
"MUST remove any URI for the resource identified by the Request-URI from
collections which contain it as a member." Servers that support
bindings SHOULD NOT follow this requirement.
4.2.9 COPY and Bindings
As defined in Section 8.8 of [WebDAV], COPY causes the resource
identified by the Request-URI to be duplicated, and makes the new
resource accessible using the URI specified in the Destination header.
Upon successful completion of a COPY, a new binding is created between
the last path segment of the Destination header (including trailing "/",
if present), and the destination resource. The new binding is added to
its parent collection, identified by the Destination header minus its
trailing slash (if present) and final segment.
A COPY with "Depth: 0" MUST NOT duplicate the bindings contained by the
collection.
As an example, suppose that a COPY is issued to URI 3 for resource R
below (which is also mapped to URI 1 and URI 2), with the Destination
header set to URIX. After successful completion of the COPY operation,
resource R is duplicated to create resource R', and a new binding has
been created which creates at least the URI mapping between URIX and the
new resource (although other URI mappings may also have been created).
URI 1 URI 2 URI 3 URIX
| | | |
| | | <---- URI Mappings ----> |
| | | |
+---------------------+ +------------------------+
| Resource R | | Resource RÆ |
+---------------------+ +------------------------+
4.2.10 MOVE and Bindings
The MOVE method has the effect of creating a new binding to a resource
(at the Destination), and removing an existing binding (at the Request-
URI). The name of the new binding is the last path segment of the
Destination header, and the new binding is added to its parent
collection, identified by the Destination header minus its trailing
slash (if present) and final segment.
As an example, suppose that a MOVE is issued to URI 3 for resource R
below (which is also mapped to URI 1 and URI 2), with the Destination
header set to URIX. After successful completion of the MOVE operation,
a new binding has been created which creates at least the URI mapping
between URIX and resource R (although other URI mappings may also have
been created). The binding corresponding to the final segment of URI 3
has been removed, which also causes the URI mapping between URI 3 and R
to be removed.
>> Before Request:
URI 1 URI 2 URI 3
| | |
| | | <---- URI Mappings
| | |
+---------------------+
| Resource R |
+---------------------+
>> After Request:
URI 1 URI 2 URIX
| | |
| | | <---- URI Mappings
| | |
+---------------------+
| Resource R |
+---------------------+
Since MOVE as specified in [WebDAV] is not an atomic operation, it may
happen that parts of the hierarchy under the request-URI can be moved.
In this case, the response is as described in [WebDAV].
4.2.10.1 Implementation Note
In some situations, particularly when the destination is on a different
server from the original resource, the server may implement MOVE by
performing a COPY, performing some consistency maintenance on bindings
and properties, and then performing a DELETE. In the end, all of the
original bindings except the one corresponding to the Request-URI will
be associated with the new resource. The binding corresponding to the
URI in the Destination header will be associated with the new resource.
And the original resource together with the binding corresponding to the
Request-URI will have been deleted. This implementation is in accord
with the definition of MOVE in [WebDAV], and is logically equivalent to
the definition given above.
The consistency maintenance processing that is required for this
implementation is as follows:
The DAV:creationdate property of the new resource SHOULD have the same
value as the DAV:creationdate property of the old resource.
The DAV:getlastmodified property of the new resource SHOULD have the
same value as the DAV:getlastmodified property of the old resource.
All URIs that were bound to the original resource except for the
Request-URI MUST be bound instead to the new resource.
Consider again the case where a MOVE is issued to URI 3 for resource R
(which is also mapped to URI 1 and URI 2), with the Destination header
set to URIX. Unlike the previous example, in this implementation, after
successful completion of the MOVE operation, resource R has been
duplicated as resource R'. The original bindings corresponding to URI 1
and URI2 are now associated with R'. The binding corresponding to the
Request-URI (URI 3) has been removed. And a new binding has been
created which creates at least the URI mapping between URIX and resource
R'. Note that the server may reclaim the storage associated with
resource R once the MOVE operation has finished.
>> Before Request:
URI 1 URI 2 URI 3
| | |
| | | <---- URI Mappings
| | |
+---------------------+
| Resource R |
+---------------------+
>> After Request:
URI1 URI2 --------------------------------- URIX
| | |
----------------------------------------- | |
| | |
+---------------------+ +------------------------+
| Resource R | | Resource RÆ |
+---------------------+ +------------------------+
4.2.11 LOCK and UNLOCK
Bindings do not affect the semantics of locks, as specified in [WebDAV].
Specifically, the requirement in section 8.10.3 that "a LOCK request on
a resource MUST NOT succeed if it can not be honored by all the URIs
through which the resource is accessible" still holds. The LOCK method
locks the resource, and a lock is visible via all URIs mapped to that
resource. Similarly, a successful UNLOCK issued via any URI mapping to a
resource removes the lock from the resource, and this lock removal is
visible via all URI mappings.
When a resource is locked, the lock owner expects to be able to access
the resource -- using the same Request-URI that he used to lock the
resource -- for as long as he holds the lock. This would not be
possible if another user could move or delete any of the collections
corresponding to segments of the request-URI.
Consequently, for the duration of a lock, it MUST NOT be possible for a
principal other than the lock owner to make a locked resource
inaccessible via the URI mapping used to lock the resource. Only the
lock owner can move or delete any of the collections corresponding to
segments of the Request-URI. This restriction does not prevent others
from modifying those collections, by adding members to them, removing
members from them, or changing their property values.
For example, if a user locks /plants/herbs/rosemary.html, it is not
possible for another user to move /plants/herbs/ to
/plants/flowering/herbs/, or to completely delete /plants/herbs/, though
it is possible this delete operation may succeed in deleting everything
except for /plants/herbs/rosemary.html and /plants/herbs/.
4.2.12 Bindings and Other Methods
This section describes the interaction of bindings with those HTTP
methods not yet explicitly discussed. The semantics of the methods GET,
HEAD, PUT, POST and OPTIONS are specified in [HTTP]. The semantics of
PROPFIND, PROPPATCH, and MKCOL are specified in [WebDAV].
For most of these methods, no new complexities are introduced by
allowing explicit creation of multiple bindings to the same resource.
For the access operations (GET, HEAD, OPTIONS, and PROPFIND), it is
simply the case that no matter which URI mapping to a given resource is
used as the Request-URI, the response is mediated by that same resource.
The responses may, however, vary depending upon which Request-URI was
used. For example, the response to a GET request may contain the
Request-URI in its entity.
The same is true for POST. No matter which URI mapping to a given
resource is used as the Request-URI, the response is mediated by that
same resource. The changes made on the server and the responses may,
however, vary depending upon which Request-URI was used.
If the Request-URI of a PUT identifies an existing resource, then a PUT
via one URI mapping to this resource MUST produce the same result as a
PUT with the same headers and request entity body via any other URI
mapping to the same resource. The change made by a PUT via one URI
mapping MUST affect the resource that generates the GET response for all
URI mappings to the same resource.
A PROPPATCH through one URI mapping to a resource MUST produce the same
changes to its properties as the same PROPPATCH request through a
different URI mapping to the same resource.
As specified in [WebDAV], MKCOL cannot overwrite an existing resource.
MKCOL through any URI mapping to an existing resource must fail.
The semantics of MKREF are specified in Section 4.5.1 below. A MKREF
through one URI mapping to a resource MUST produce the same result as a
MKREF with the same headers through any other URI mapping to the same
resource. By default, it overwrites the resource with a new redirect
reference.
The semantics of ORDERPATCH are specified in 5.5.1 below. An ORDERPATCH
through one URI mapping to a collection MUST produce the same changes to
its ordering as the same ORDERPATCH request through any other URI
mapping to the same collection.
4.2.13 Discovering the Bindings to a Resource
An OPTIONAL DAV:bindings property on a resource provides a list of the
bindings that associate URI segments with that resource. By retrieving
this property, a client can discover the bindings that point to the
resource and the collections that contain bindings to the resource. As
for all DAV: properties, this specification is silent as to how the
DAV:bindings property is implemented on the server.
Rationale: A number of scenarios require clients to navigate from a
resource to the bindings that point to it, and to the collections that
contain those bindings. This capability is particularly important for
Document Management Systems. Their clients may need to determine, for
any object in the DMS, what collections contain bindings to that object.
This information can be used for upward navigation through a hierarchy
or to discover related documents in other collections.
Risks: When deciding whether to support the DAV:bindings property,
server implementers / administrators should balance the benefits it
provides against the cost of maintaining the property and the security
risks enumerated in Sections 12.5 and 12.6.
4.3 Redirect References
For most operations submitted to a redirect reference, the response is a
302 (Moved Temporarily), accompanied by the Resource-Type header
(defined in Section 6.2 below) set to "DAV:redirectref" and the Location
header set to the URI of the target resource. With this information,
the client can resubmit the request to the URI of the target resource.
The methods COPY (for collections containing redirect references),
DELETE, MOVE, and LOCK, for reasons that will be explained, are
exceptions to this general behavior. These exceptional operations are
applied to the reference itself and do not result in a 302 response.
If the client is aware that it is operating on a redirect reference, it
can resolve the reference by retrieving the reference's DAV:reftarget
property (defined in Section 7.1 below), whose value is the URI of the
target resource. It can then submit requests to the target resource.
A redirect reference is a new type of resource. To distinguish redirect
references from ordinary resources, a new value of the DAV:resourcetype
property (defined in [WebDAV]), DAV:redirectref, is defined in Section
8.1 below.
Since a redirect reference is a resource, it is possible to apply
methods to the reference rather than to its target. The Passthrough
request header (defined in Section 6.4 below) is provided so that
referencing-aware clients can control whether an operation is applied to
the redirect reference or to its target resource. The Passthrough
header can be used with most requests to redirect references. This
header is particularly useful with PROPFIND, to retrieve the reference's
own properties.
4.3.1 MKREF Method
The MKREF method creates a redirect reference resource identified by the
Request-URI, whose target is identified by the REQUIRED Ref-Target
header. MKREF sets the value of the REQUIRED DAV:reftarget property to
the value of the Ref-Target header.
The MKREF method creates a new binding between the new redirect
reference resource and the last path segment of the Request-URI. The
new binding is added to its parent collection, identified by the
Request-URI minus its trailing slash (if present) and final segment.
The Position request header (defined in Section 6.6) MAY be used in
MKREF requests.
MKREF requests MAY include an entity body. This specification does not
define the action to be taken if a request entity body is present, but
allows it for extensibility.
By default, if the Request-URI of the MKREF request identifies an
existing resource, the server MUST perform a delete operation on the
existing resource before performing the MKREF. This default behavior can
be overridden using the Overwrite header defined in Section 9.6 of
[WebDAV].
4.3.1.1 Status Codes
201 (Created): The redirect reference resource was successfully created.
400 (Bad Request): The client set an invalid value for the Ref-Target or
Position header.
409 (Conflict): Several conditions may produce this response. There may 409 (Conflict): Several conditions may produce this response. There may
be no resource at the location specified in Ref-Target, on a server that be no resource at the location specified in Ref-Target, on a server that
prohibits dangling references. The request may be attempting to create prohibits dangling references. The request may be attempting to create
the reference in a collection that does not exist. The request may be the reference in a collection that does not exist. The request may be
attempting to position the reference before or after a resource that is attempting to position the reference before or after a resource that is
not in the collection, or before or after itself. The request may be not in the collection, or before or after itself. The request may be
attempting to position the reference in an unordered collection. attempting to position the reference in an unordered collection.
4.3.3 Example: MKREF 412 (Precondition Failed): The Overwrite header is "F", and a resource
already exists at the request-URI.
Request: 4.3.1.2 Example: MKREF
>> Request:
MKREF /~whitehead/dav/spec08.ref HTTP/1.1 MKREF /~whitehead/dav/spec08.ref HTTP/1.1
HOST: www.ics.uci.edu Host: www.ics.uci.edu
Ref-Target: </i-d/draft-webdav-protocol-08.txt> Ref-Target: /i-d/draft-webdav-protocol-08.txt
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 redirect reference at
www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource
identified by the Ref-Target header. Its DAV:resourcetype property is identified by the Ref-Target header. In this example, the target
set to DAV:reference. Its DAV:reftarget property is set to the URI of resource of the referential resource is identified by the URI
its target resource. Its DAV:refintegrity property is set to the value http://www.ics.uci.edu/~whitehead/dav/i-d/draft-webdav-protocol-08.txt.
of DAV:weak, indicating that the server will not enforce referential The referential resource's DAV:resourcetype property is set to
integrity for the new reference. Its DAV:reftype property is set to the DAV:redirectref. Its DAV:reftarget property is set to the value of the
default value of DAV:redirect. Ref-Target header, "/i-d/draft-webdav-protocol-08.txt".
4.4 Listing Referential Members of a Collection
A URI of a reference can be a member of a collection just as the URI of 4.3.2 Listing the Redirect References in a Collection
an ordinary resource can. A listing of members of a collection shows
all of the URIs in the collection, whether they identify references or
ordinary resources. That is, a WebDAV PROPFIND request on a collection
resource with Depth = 1 or infinity MUST return a response XML element
for each URI in the collection, whether it identifies an ordinary
resource or a referential resource.
For each direct reference, the properties returned by the PROPFIND MUST A URI of a redirect reference can be an internal member URI of a
be the properties of the target resource unless the No-Passthrough collection just as the URI of an ordinary resource can. A listing of
header is included with the PROPFIND request. the internal member URIs of a collection shows all of the URIs that are
internal members of the collection, whether they identify redirect
references or ordinary resources. That is, a WebDAV PROPFIND request on
a collection resource with the Depth header set to 1 or infinity MUST
return a response XML element for each member URI in the collection,
whether it identifies an ordinary resource or a redirect reference.
For each redirect reference, the response element MUST contain a 302 For each redirect reference, the response element MUST contain a 302
(Moved Temporarily) status code unless the No-Passthrough header is (Moved Temporarily) status code unless a Passthrough header with the
included with the PROPFIND request. The DAV:location and DAV:reftype value "F" is included with the PROPFIND request. The DAV:location and
properties MUST be included with the 302 status code, extending the DAV:resourcetype properties MUST be included with the 302 status code,
syntax of the DAV:response element that was defined in [WebDAV] as extending the syntax of the DAV:response element that was defined in
described in Section 9 below. A referencing client can tell from the [WebDAV] as described in Section 9 below. A referencing-aware client
DAV:reftype property that the collection contains a redirect reference. can tell from the DAV:resourcetype property that the collection contains
The DAV:location property contains the absolute URI of the target a redirect reference. The DAV:location property contains the absolute
resource. A referencing client can either use the DAV:location property URI of the target resource. A referencing-aware client can either use
to retrieve the properties of the target resource or can submit a the URI value of the DAV:location property to retrieve the properties of
PROPFIND to the redirect reference with the No-Passthrough header to the target resource, or it can submit a PROPFIND to the redirect
retrieve its properties. The DAV:location property is expected to be reference with "Passthrough: F" to retrieve its properties. It is
defined in a future revision of [WebDAV], at which time non-referencing recommended that future editors of [WebDAV] define the DAV:location
clients will also be able to use the response to retrieve the properties property in [WebDAV], so that non-referencing clients will also be able
of the target resource. to use the response to retrieve the properties of the target resource.
If Depth = infinity in the PROPFIND request, the server MUST NOT follow If the Depth header is set to infinity in the PROPFIND request, the
redirect references into any collections to which they may refer. server MUST NOT follow redirect references into any collections to which
they may refer.
If Depth = infinity in the PROPFIND request, the server MUST follow The Passthrough header (defined in Section 6.4) MAY be used with a
direct references into any collections to which they may refer unless PROPFIND request on a collection.
the No-Passthrough header is used with the request. That is, if the
target resource is a collection, the server MUST list the members of
that collection.
The No-Passthrough header MAY be used with a PROPFIND request on a 4.3.2.1 Example: PROPFIND on a Collection with Redirect References
collection. If the No-Passthrough header is present, then the
properties of the references in the collection MUST be returned, 302
(Moved Temporarily) status codes MUST NOT be returned for redirect
references, direct references MUST NOT pass the request through to their
target resources, and the server MUST NOT follow direct references to
collections into their target collections.
4.4.1 Example: PROPFIND on a Collection with References Suppose a PROPFIND request with Depth = infinity is submitted to the
following collection, with the members shown here:
http://www.svr.com/MyCollection/ http://www.svr.com/MyCollection/
(ordinary resource) diary.html (ordinary resource) diary.html
(direct reference) tuva
(redirect reference) nunavut (redirect reference) nunavut
The target of http://www.svr.com/MyCollection/tuva is a collection: >> Request:
http://www.feynman.com/tuva/
(ordinary resource) history.html
(ordinary resource) music.html
Request:
PROPFIND /MyCollection/ HTTP/1.1 PROPFIND /MyCollection/ HTTP/1.1
Host: www.svr.com Host: www.svr.com
Depth: infinity Depth: infinity
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxxx Content-Length: xxxx
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:propfind xmlns:D="DAV: "> <D:propfind xmlns:D="DAV: ">
<D:prop xmlns:J="http://www.svr.com/jsprops/"> <D:prop xmlns:J="http://www.svr.com/jsprops/">
<D:resourcetype/> <D:resourcetype/>
<J:keywords/> <J:keywords/>
</D:prop> </D:prop>
</D:propfind> </D:propfind>
Response: >> Response:
HTTP/1.1 207 Multi-Status HTTP/1.1 207 Multi-Status
Content-Type: text/xml Content-Type: text/xml
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>collection</D:resourcetype> <D:resourcetype><D:collection/></D:resourcetype>
<J:keywords>diary, interests, hobbies</J:keywords> <J:keywords>diary, interests, hobbies</J:keywords>
</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:response> <D:response>
<D:href>http://www.svr.com/MyCollection/diary.html</D:href> <D:href>http://www.svr.com/MyCollection/diary.html</D:href>
<D:propstat> <D:propstat>
<D:prop> <D:prop>
<D:resourcetype></D:resourcetype> <D:resourcetype/>
<J:keywords>diary, travel, family, history</J:keywords> <J:keywords>diary, travel, family, history</J:keywords>
</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:response> <D:response>
<D:href>http://www.svr.com/MyCollection/tuva</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>collection</D:resourcetype>
<J:keywords>history, music, throat-singing</J:keywords>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.svr.com/MyCollection/tuva/history.html</D:href>
<D:propstat>
<D:prop>
<D:resourcetype></D:resourcetype>
<J:keywords>history, language, culture</J:keywords>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.svr.com/MyCollection/tuva/music.html</D:href>
<D:propstat>
<D:prop>
<D:resourcetype></D:resourcetype>
<J:keywords>music, throat-singing</J:keywords>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.svr.com/MyCollection/nunavut</D:href> <D:href>http://www.svr.com/MyCollection/nunavut</D:href>
<D:status>HTTP/1.1 302 Moved Temporarily</D:status> <D:status>HTTP/1.1 302 Moved Temporarily</D:status>
<D:prop> <D:prop>
<D:location> <D:location>
<D:href>http://www.inac.gc.ca/art/inuit/</D:href> <D:href>http://www.inac.gc.ca/art/inuit/</D:href>
</D:location> </D:location>
<D:reftype>redirect</D:reftype> <D:resourcetype><D:redirectref/></D:resourcetype>
</D:prop> </D:prop>
</D:response> </D:response>
</D:multistatus> </D:multistatus>
In this example, Depth = infinity and the No-Passthrough header is not In this example the Depth header is set to infinity, and the Passthrough
used. The collection contains one URI that identifies a redirect header is not used. The collection contains one URI that identifies a
reference. The response element for the redirect reference has a status redirect reference. The response element for the redirect reference has
of 302 (Moved Temporarily), and includes a DAV:prop element with the a status of 302 (Moved Temporarily), and includes a DAV:prop element
DAV:location and DAV:reftype properties to allow clients to retrieve the with the DAV:location and DAV:resourcetype properties to allow clients
properties of its target resource. The collection also contains one URI to retrieve the properties of its target resource. (The response
that identifies a direct reference. The response element for the direct element for the redirect reference does not include the requested
reference contains the properties of its target collection. There are properties. The client can submit another PROPFIND request to the URI
also response elements for each member of its target collection. in the DAV:location property to retrieve those properties.)
4.4.2 Example: PROPFIND with No-Passthrough on a Collection with 4.3.2.2 Example: PROPFIND with Passthrough: F on a Collection with
References Redirect References
Suppose a PROPFIND request with Passthrough = F and Depth = infinity is
submitted to the following collection, with the members shown here:
/MyCollection/ /MyCollection/
(collection) photos/
(ordinary resource) family.gif
(ordinary resource) trip.gif
(ordinary resource) diary.html (ordinary resource) diary.html
(direct reference) tuva
(redirect reference) nunavut (redirect reference) nunavut
Request: >> Request:
PROPFIND /MyCollection/ HTTP/1.1 PROPFIND /MyCollection/ HTTP/1.1
Host: www.svr.com Host: www.svr.com
Depth: infinity Depth: infinity
No-Passthrough: Passthrough: F
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxxx Content-Length: xxxx
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:propfind xmlns:D="DAV:"> <D:propfind xmlns:D="DAV:">
<D:prop> <D:prop>
<D:resourcetype/> <D:resourcetype/>
<D:reftype/>
<D:reftarget/> <D:reftarget/>
</D:prop> </D:prop>
</D:propfind> </D:propfind>
Response: >> Response:
HTTP/1.1 207 Multi-Status HTTP/1.1 207 Multi-Status
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxxx Content-Length: xxxx
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:multistatus xmlns:D="DAV:"> <D:multistatus xmlns:D="DAV:">
<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>collection</D:resourcetype> <D:resourcetype><D:collection/></D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop> <D:reftype/> <D:reftarget/> </D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.svr.com/MyCollection/photos/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>collection</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop> <D:reftype/> <D:reftarget/> </D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.svr.com/MyCollection/photos/family.gif</D:href>
<D:propstat>
<D:prop>
<D:resourcetype></D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop> <D:reftype/> <D:reftarget/> </D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.svr.com/MyCollection/photos/trip.gif</D:href>
<D:propstat>
<D:prop>
<D:resourcetype></D:resourcetype>
</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:reftype/> <D:reftarget/> </D:prop> <D:prop> <D:reftarget/> </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>
<D:response> <D:response>
<D:href>http://www.svr.com/MyCollection/diary.html</D:href> <D:href>http://www.svr.com/MyCollection/diary.html</D:href>
<D:propstat> <D:propstat>
<D:prop> <D:prop>
<D:resourcetype></D:resourcetype> <D:resourcetype/>
</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:reftype/> <D:reftarget/> </D:prop> <D:prop> <D:reftarget/> </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>
<D:response> <D:response>
<D:href>http://www.svr.com/MyCollection/tuva</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>reference</D:resourcetype>
<D:reftype>direct</D:reftype>
<D:reftarget>
<D:href>http://www.feynman.com/tuva/</D:href>
</D:reftarget>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.svr.com/MyCollection/nunavut</D:href> <D:href>http://www.svr.com/MyCollection/nunavut</D:href>
<D:propstat> <D:propstat>
<D:prop> <D:prop>
<D:resourcetype>reference</D:resourcetype> <D:resourcetype><D:redirectref/></D:resourcetype>
<D:reftype>redirect</D:reftype>
<D:reftarget> <D:reftarget>
<D:href>http://www.inac.gc.ca/art/inuit/</D:href> <D:href>http://www.inac.gc.ca/art/inuit/</D:href>
</D:reftarget> </D:reftarget>
</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>
Since the No-Passthrough header is present, the response shows the Since the Passthrough header has the value "F", the response shows the
properties of the references in the collection rather than the properties of the redirect reference in the collection rather than the
properties of their targets. Even though Depth = infinity, the No- properties of its target. The value of the Passthrough header also
Passthrough header prevents the server from listing the members of the prevents a 302 response from being returned for the redirect reference.
collection that is the target of the direct reference. No-Passthrough
also prevents a 302 response from being returned for the redirect
reference.
4.5 Copying Referential Resources
In determining the semantics of COPY, the desire to provide intuitively 4.3.3 Copying Redirect References
correct behavior was weighed against consistency considerations.
A clients intent in performing a COPY operation is to create a new A client's intent in performing a COPY operation is to create a new
resource that is similar to the original resource and behaves like the resource that is similar to the original resource and behaves like the
original resource, and that can be modified without affecting the original resource, and that can be modified without affecting the
original resource. For references to ordinary resources, the original resource. For a COPY request to a redirect reference, the
expectation would be that the target resource be copied. This would expectation would be a 302 response that the client could use to copy
yield an independent resource that could be modified without affecting the target resource. This would yield an independent resource that
the original resource. For collections the situation is less clear. could be modified without affecting the original resource. For COPY
There is tension between two expectations. On the one hand, the client requests to collections that contain redirect references, the situation
may expect the new copy of the collection to behave like the old one is less clear. There is tension between two expectations. On the one
(which implies having references where the old one had references). On hand, the client may expect the new copy of the collection to behave
the other hand, the client may expect that it will be possible to modify like the old one (which implies having references where the old one had
the members of the new collection without affecting the members of the references). On the other hand, the client may expect that it will be
old collection (which implies having copies of the targets where the possible to modify the resources in the new collection without affecting
original collection had references). the resources in the old collection (which implies having copies of the
targets where the original collection had references).
4.5.1 COPY for Direct References
COPY follows the general principle that operations on direct references
are applied to the target resource unless the No-Passthrough header is
used. A COPY on a direct reference MUST be applied to its target
resource unless the No-Passthrough header is used. If the No-
Passthrough header is used, then the COPY MUST be applied to the direct
reference rather than to its target.
For consistency, the same is true when a COPY request is sent to a
collection, and direct references are encountered inside the collection.
Unless the No-Passthrough header is present on the request, the targets
of the direct references MUST be copied into the new collection. If the
No-Passthrough header is used, then the direct references, and not their
targets, MUST be copied into the new collection.
These semantics yield intuitively correct results when a COPY request is
sent to an individual reference. It is less clear that the results are
intuitive when a COPY request is sent to a collection containing direct
references, but consistency dictates that we follow the same semantics
for this case. A design principle that is followed throughout this
specification is that a method behaves the same when it is sent to the
URI of a reference as it does when it is sent to a the URI of a
collection and encounters a reference inside that collection.
4.5.2 COPY for Redirect References
For redirect references, the normal behavior would be to respond to a
request with a 302 (Moved Temporarily) status code, allowing the client
to resubmit the request to the target resource identified in the
Location header. This would also yield intuitively correct behavior for
COPY. However, it seems undesirable to respond to a COPY request on a
collection with a Multi-Status including a 302 response for each
redirect reference. To avoid this sort of response, the following rules
apply when COPY is sent to redirect references:
A COPY on a redirect reference MUST be applied to the reference itself,
whether or not the No-Passthrough header is present.
The same is true when a COPY request is sent to a collection, and
redirect references are encountered inside the collection. Whether or
not the No-Passthrough header is present on the request, the redirect
references themselves are copied into the new collection, and 302 status
codes are not returned for them.
4.5.3 Example: COPY on a Direct Reference
Request:
COPY /MyCollection/tuva HTTP/1.1
Host: www.svr.com
Destination: http://www.svr.com/OtherCollection/tuva.html
Response: For a COPY request on an individual reference, the response MUST be a
302 (Moved Temporarily) status code, with the URI of the target resource
in the Location header, and "Resource-Type: DAV:redirectref" to
distinguish the response from an ordinary HTTP redirect. This is the
normal behavior for redirect references, allowing the client to resubmit
the request to the target resource identified in the Location header.
This also yields intuitively correct behavior for a COPY request to an
individual reference. Reference-aware clients can use the Passthrough
header with the value "F" to copy the redirect reference itself.
HTTP/1.1 204 No Content For COPY on a collection containing redirect references, different
Ref-Type: direct
Ref-Target: /Asia/History/tuva.html
In this example, the request-URI identifies a direct reference whose semantics may be desirable in different scenarios. Consequently, this
target resource is identified by specification makes a fairly arbitrary choice to take the simplest path.
http://www.svr.com/Asia/History/tuva.html. This target resource was When a COPY request is submitted to a collection containing redirect
copied to the destination location in the Destination header, references, the server MUST copy the redirect references to the new
http://www.svr.com/OtherCollection/tuva.html. The headers included with collection rather than returning 302 status codes for them. This will
the response insure that the client knows that it was operating on a result in a new collection that behaves like the old one, and avoids
direct reference, and that the client knows which resource was copied. responding with multiple 302 status codes, each of which the client
would have to process separately. Reference-aware clients can force the
server to respond with 302 status codes rather than copying the
references by using the Passthrough header with the value "T".
4.5.4 Example: COPY on a Redirect Reference 4.3.3.1 Example: COPY on a Redirect Reference
Request: >> Request:
COPY /MyCollection/tuva HTTP/1.1 COPY /MyCollection/tuva HTTP/1.1
Host: www.svr.com Host: www.svr.com
Destination: http://www.svr.com/OtherCollection/tuva.html Destination: http://www.svr.com/OtherCollection/tuva.html
Response: >> Response:
HTTP/1.1 204 No Content HTTP/1.1 302 Moved Temporarily
Ref-Type: redirect Location: http://www.svr.com/Asia/History/tuva.html
Ref-Target: /Asia/History/tuva.html Resource-Type: DAV:redirectref
In this example, the request-URI identifies a redirect reference whose In this example, the request-URI identifies a redirect reference whose
target resource is identified by target resource is identified by
http://www.svr.com/Asia/History/tuva.html. In this case, the reference http://www.svr.com/Asia/History/tuva.html. In this case, the server
was copied to the destination location in the Destination header, responded with a 302, and provided the URL of the target resource in the
http://www.svr.com/OtherCollection/tuva.html. The Ref-Type header Location header. The Resource-Type header indicates to a reference-
included with the response informs the client that it was operating on a aware client that this is not an HTTP 1.1 redirect, but a reference to
redirect reference. The Ref-Target header provides the information the the resource identified by the Location header. The client can now
client needs to copy the target resource, should it wish to do so. resubmit the COPY request to the target resource, producing the desired
result: a duplicate of the original target resource that can be modified
independently of the original.
The result would have been exactly the same, and the response would have 4.3.3.2 Example: COPY on a Collection That Contains a Redirect Reference
been exactly the same (except that the Ref-Target header would be
OPTIONAL), had the No-Passthrough header been used in the request.
4.5.5 Example: COPY on a Collection That Contains a Direct Reference and Suppose a COPY request is submitted to the following collection, with
a Redirect Reference the members shown:
/MyCollection/ /MyCollection/
(ordinary resource) diary.html (ordinary resource) diary.html
(direct reference) tuva (redirect reference) nunavut with target /Someplace/nunavut.map
(redirect reference) nunavut
Request: >> Request:
COPY /MyCollection/ HTTP/1.1 COPY /MyCollection/ HTTP/1.1
Host: www.svr.com Host: www.svr.com
Destination: http://www.svr.com/OtherCollection/ Destination: http://www.svr.com/OtherCollection/
Response: >> Response:
HTTP/1.1 207 Multi-Status HTTP/1.1 201 Created
Content-Type: text/xml
Content-Length: nnnn
<?xml version="1.0" ?> In this case, since /MyCollection/nunavut is a redirect reference, the
<D:multistatus xmlns:D="DAV:"> reference itself, and not its target, was copied into the new
<D:response> collection. So the resulting collection is as follows:
<D:href>tuva</D:href>
<D:status>HTTP/1.1 201 Created</D:status>
<D:prop>
<D:reftype>direct</D:reftype>
<D:reftarget>
<D:href>http://www.feynman.com/tuva/</D:href>
</D:reftarget>
</D:prop>
</D:response>
<D:response>
<D:href>nunavut</D:href>
<D:status>HTTP/1.1 201 Created</D:status>
<D:prop>
<D:reftype>redirect</D:reftype>
<D:reftarget>
<D:href>http://www.inac.gc.ca/art/inuit/</D:href>
</D:reftarget>
</D:prop>
</D:response>
</D:multistatus>
When references are involved, it is not possible to follow the rules in /OtherCollection/
[WebDAV] Section 8.8.3 for reducing the length of responses to COPY (ordinary resource) diary.html
requests. Although the entire COPY operation in the example was (redirect reference) nunavut with target /Someplace/nunavut.map
successful, a Multi-Status response is still REQUIRED, so that the
DAV:reftype and DAV:reftarget properties can be returned for the
references in the collection. The results for each reference MUST be
reported in a separate DAV:response element so that it is clear which
reference is associated with which values of DAV:reftype and
DAV:reftarget. In this case, since /MyCollection/tuva is a direct
reference, its target resource was copied into the new collection.
Since /MyCollection/nunavut is a redirect reference, the reference
itself, and not its target, was copied into the new collection. There
are no response elements for the collection /MyCollection/ or for the
ordinary resource /MyCollection/diary.html, since they were successfully
copied and no special information needs to be returned for them.
4.6 Deleting and Moving Referential Resources 4.3.4 Deleting and Moving Redirect References
The DELETE method is used to delete referential resources. For both The DELETE method is used to delete bindings to redirect references.
direct and redirect references, DELETE MUST affect the reference itself, DELETE MUST affect bindings to the reference itself, unless
and not its target. Similarly, when a DELETE on a collection encounters "Passthrough: T" is used, in which case it generates a 302 (Moved
a reference in the subtree under that collection, it MUST delete the Temporarily) response. Similarly, when a DELETE on a collection
reference, and not its target. encounters a redirect reference in the subtree under that collection, it
MUST delete bindings to the reference, unless "Passthrough: T" is used,
in which case it generates a 302 (Moved Temporarily) response. Whether
deleting an individual resource or a collection, DELETE on a redirect
reference does not affect the target of the reference.
A MOVE operation on a referential resource MUST move the referential A MOVE operation on a redirect reference MUST move the reference to a
resource to a different location, and MUST NOT change the location of different location, and MUST NOT change the location of its target,
its target. The DAV:reftarget property is unchanged after a MOVE. unless "Passthrough: T" is used, in which case a 302 (Moved Temporarily)
Similarly, when a MOVE on a collection encounters a reference in the response is generated. The DAV:reftarget property is unchanged after a
subtree under that collection, it MUST move the reference, and not its MOVE. Similarly, when a MOVE on a collection encounters a redirect
target. reference in the subtree under that collection, it MUST move the
reference, and not its target, unless "Passthrough: T" is used, in which
case a 302 (Moved Temporarily) response is generated.
DELETE and MOVE differ from other methods in that they do not alter the DELETE and MOVE differ from other methods in that they do not alter the
resource that is being deleted or moved, but rather the collection that resource that is being deleted or moved, but rather the collection that
contains its URI. They change the membership of that collection. contains its binding. They change the membership of that collection.
When a reference is added to a collection, the aim is to make it look as
if the target resource were a member of that collection. When the
reference is removed from that collection, the aim is to change the
membership of that collection. Membership of the target in any other
collections, either internally or by reference, should not be affected.
Consequently, DELETE and MOVE do not follow the normal rules of behavior
for references. Instead, they are always applied to the reference
itself, not to its target, and they never result in 302 status codes.
Although clients MAY use the No-Passthrough header with DELETE and MOVE
requests, the header has no effect on their behavior. Whether the No-
Passthrough header is present or not, they are always applied to the
reference.
[WebDAV] defines MOVE to be logically equivalent to COPY followed by When a redirect reference is added to a collection, the aim is to make
DELETE. For direct references, MOVE is logically equivalent to COPY it look as if the target resource were a member of that collection.
with the No-Passthrough header followed by DELETE. When the reference is removed from that collection, the aim is to change
the membership of that collection. Membership of the target in any
other collections, either internally or by reference, should not be
affected. Consequently, DELETE and MOVE do not follow the normal rules
of behavior for references. Instead, they are applied by default to the
reference itself, not to its target, and by default do not result in 302
status codes.
4.7 Locking Referential Resources 4.3.5 Locking Redirect References
The semantics of LOCK described here resulted from balancing a set of The semantics of LOCK described here resulted from balancing a set of
incompatible considerations: incompatible considerations:
o Ideally, a LOCK on a reference should lock both the reference and its o Ideally, a LOCK on a redirect reference should lock both the
target resource. The owner of an exclusive write lock, for example, reference and its target resource. The owner of an exclusive write
would be surprised if anyone else could modify the content of the lock, for example, would be surprised if anyone else could modify the
target resource while he held the lock. He would also be surprised content of the target resource while he held the lock. He would also
if anyone else could delete the reference to it, or replace the be surprised if anyone else could delete the reference to it, or
reference with one pointing to a different target. replace the reference with one pointing to a different target.
o Non-referencing clients should be able to use redirect references
o Non-referencing clients should be able to use both direct and without encountering surprising results.
redirect references without encountering surprising results. o The basic characteristics of redirect references should be honored.
Redirect references should be simple for servers to implement. In
o Preserve the clear distinction between redirect and direct particular, a server should never have to resolve a redirect
references. Redirect references should be simple for servers to reference. A server should not have to provide proxy capabilities in
implement. In particular, a server should never have to resolve a order to implement redirect references.
redirect reference. A server should not have to provide proxy
capabilities in order to implement redirect references. Direct
references rely on more sophisticated server capabilities to give
clients the illusion of operating directly on the target resource.
o There should be consistency between the behavior of LOCK on a single o There should be consistency between the behavior of LOCK on a single
referential resource and the behavior of LOCK on a collection that redirect reference and the behavior of LOCK on a collection that
contains referential resources. contains redirect references.
o The behavior of all requests to redirect references should be as
o Keep the behavior of all requests to references as consistent as consistent as possible. In the absence of a Passthrough header, all
possible. Try to adhere to the general rule that in the absence of a methods should return a 302 when sent to a redirect reference.
No-Passthrough header, all methods return a 302 when sent to a o LOCK semantics for redirect references should be consistent with the
redirect reference and are applied to the target when sent to a LOCK semantics defined in [WebDAV].
direct reference.
o Be consistent with the LOCK semantics defined in [WebDAV].
We have compromised the intuitive locking behavior and support for non- We have compromised the intuitive locking behavior and support for non-
referencing clients in order to preserve various sorts of consistency. referencing clients in order to preserve various sorts of consistency.
4.7.1 LOCK on Direct References 4.3.6 LOCK on Redirect References
LOCK follows the general principle that operations on direct references
are applied to the target resource unless the No-Passthrough header is
used. When a LOCK request is sent to a direct reference without the No-
Passthrough header, the target resource MUST be locked. When a LOCK
request with the No-Passthrough header is sent to a direct reference,
the reference itself MUST be locked.
A principle followed throughout this specification is that behavior when
a reference is encountered during an operation on a collection must be
the same as behavior when operating on an individual reference. When a
LOCK request with Depth > 0 is sent to a collection, the targets of any
direct references encountered MUST be locked, unless the No-Passthrough
header is used. If the No-Passthrough header is present on a LOCK
request with Depth > 0 to a collection, then any direct references
encountered MUST themselves be locked.
As was noted above, more intuitive results would have been obtained by
requiring that both the reference and its target to be locked in
response to a LOCK request. Reference-aware clients can obtain this
result by performing two LOCK operations, one with the No-Passthrough
header and one without. Non-referencing clients cannot do so. This
means that for non-referencing clients there is always the risk that a
referencing client may delete or replace the reference that was used to
lock a target resource while the non-referencing client has the target
locked. To insure intuitive results for non-referencing clients,
referencing clients SHOULD be designed to check whether the target
resource is locked before replacing, moving, or deleting a direct
reference.
UNLOCK behaves as specified in [WebDAV], unlocking all resources
included in the lock identified by the Lock-Token header.
4.7.2 LOCK on Redirect References
The behavior of LOCK for redirect references was determined by what is The behavior of LOCK for redirect references was determined by what is
possible for the case of locking collections that contain redirect possible for the case of locking collections that contain redirect
references. references.
The expected behavior for any operation on a redirect reference is that The default behavior for any operation on a redirect reference is that a
a 302 (Moved Temporarily) response will be returned, unless the No- 302 (Moved Temporarily) response will be returned, unless the
Passthrough header is used. However, this policy would have Passthrough header with a value of "F" is used. However, this policy
unacceptable consequences when locking a collection that contains has unacceptable consequences when locking a collection that contains
redirect references. Since [WebDAV} requires LOCK on a collection to be redirect references. Since [WebDAV] requires LOCK on a collection to be
an atomic operation, if a 302 response is received for any member of the an atomic operation, if a 302 response is received for any member of the
collection, the entire LOCK must fail. This would make it impossible to collection, the entire LOCK must fail. This would make it impossible to
lock any collection that contained a redirect reference. lock any collection that contained a redirect reference.
To avoid this result, a LOCK on a collection with Depth > 0 MUST lock To avoid this result, a LOCK with Depth > 0 on a collection MUST lock
any redirect references it encounters, and not return 302 responses for any redirect references it encounters, and not return 302 responses for
them, whether or not the No-Passthrough header is used. them, unless the Passthrough header with a value of "T" is used. Use of
the Passthrough header with a value of "T" in a LOCK request on a
This gives part of the expected lock behavior without forcing the server collection will cause the entire lock to fail if a redirect reference is
to resolve the redirect reference or become a proxy server in cases encountered.
where the target resides on a different server.
Each DAV:response element for a redirect reference MUST include the This gives part of the expected default lock behavior without forcing
DAV:reftype and DAV:reftarget properties so that a referencing client the server to resolve the redirect reference or become a proxy server in
can lock the targets if it wishes. (There will be no hint in any cases where the target resides on a different server.
response code that there are redirect references whose targets need to
be locked. The client will most likely not lock any targets until it
attempts an operation on the target and gets a 302 response.) Non-
referencing clients cannot lock the targets of the redirect references There will be no hint in any response code that there are redirect
and may never realize that the targets have not been locked. references whose targets need to be locked. The client will most likely
not lock any targets until it attempts an operation on the target and
gets a 302 response. It is possible that a non-referencing client may
never realize that the reference's target has not been locked.
Clearly, a LOCK with Depth = infinity on a collection MUST NOT follow Clearly, a LOCK with Depth = infinity on a collection MUST NOT follow
any redirect references whose targets are collections into the target any redirect references whose targets are collections into the target
collections; it MUST NOT cause any members of those target collections collections; it MUST NOT cause any resources in those target collections
to be locked. to be locked.
The behavior of LOCK for individual redirect references is designed to The behavior of LOCK for individual redirect references is designed to
be consistent with LOCK behavior for collections that contain redirect be consistent with LOCK behavior for collections that contain redirect
references. Whether or not a No-Passthrough header is present, a LOCK references. By default a LOCK on a redirect reference MUST lock only
on a redirect reference MUST lock only the reference, not its target, the reference, not its target, and it MUST NOT return a 302 response. A
and it MUST NOT return a 302 response. The response MUST include the reference-aware client can use the Passthrough header with a value of
Ref-Type and Ref-Target headers, so that a referencing client can lock "T" to get a 302 response with the URI of the target resource in the
the target resource if it wishes. Location header.
UNLOCK behaves as specified in [WebDAV], unlocking all resources UNLOCK behaves as specified in [WebDAV], unlocking all resources
included in the lock identified by the Lock-Token header. included in the lock identified by the Lock-Token header.
4.7.3 Example: LOCK on a Direct Reference 4.3.6.1 Example: LOCK on a Redirect Reference
Request: >> Request:
LOCK /MyCollection/tuva HTTP/1.1 LOCK /MyCollection/tuva HTTP/1.1
Host: www.svr.com Host: www.svr.com
Content-Type: text/xml Content-Type: text/xml
Content-Length: nnnn Content-Length: nnnn
Authorizaton: Digest username="jas", Authorizaton: Digest username="jas",
realm=jas@webdav.sb.aol.com, nonce=". . .", realm=jas@webdav.sb.aol.com, nonce=". . .",
uri="/MyCollection/tuva", uri="/MyCollection/tuva",
response=". . .", opaque=". . ." response=". . .", opaque=". . ."
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:lockinfo xmlns:D="DAV:"> <D:lockinfo xmlns:D="DAV:">
<D:lockscope><D:exclusive/></D:lockscope> <D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype> <D:locktype><D:write/></D:locktype>
<D:owner> <D:owner>
<D:href>http://www.svr.com/~jas/contact.html</D:href> <D:href>http://www.svr.com/~jas/contact.html</D:href>
</D:owner> </D:owner>
</D:lockinfo> </D:lockinfo>
Response: >> Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Ref-Type: direct
Ref-Target: /Asia/History/tuva.html
Content-Type: text/xml Content-Type: text/xml
Content-Length: nnnn Content-Length: nnnn
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:prop xmlns:D="DAV:"> <D:prop xmlns:D="DAV:">
<D:lockdiscovery> <D:lockdiscovery>
<D:activelock> <D:activelock>
<D:lockscope><D:exclusive/></D:lockscope> <D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype> <D:locktype><D:write/></D:locktype>
<D:depth>0</D:depth> <D:depth>0</D:depth>
<D:owner> <D:owner>
<D:href>http://www.svr.com/~jas/contact.html</D:href> <D:href>http://www.svr.com/~jas/contact.html</D:href>
</D:owner> </D:owner>
<D:locktoken> <D:locktoken>
opaquelocktoken:e71dfae-5dec-22d6-fea5-00a0c91e6be4 opaquelocktoken:e71dfae-5dec-22d6-fea5-00a0c91e6be4
</D:locktoken> </D:locktoken>
</D:activelock> </D:activelock>
</D:lockdiscovery> </D:lockdiscovery>
</D:prop> </D:prop>
In this example, the request-URI identifies a direct reference whose The request and response look exactly as specified in [WebDAV]. In this
target resource is identified by example, the request-URI, http://www.svr.com/MyCollection/tuva,
http://www.svr.com/Asia/History/tuva.html. This target resource was identifies a redirect reference, which was successfully locked. The
locked. The Ref-Type and Ref-Target headers included with the response target resource of the redirect reference is not locked.
insure that the client knows that it was operating on a direct
reference, and that the client knows which resource was locked.
4.7.4 Example: LOCK on a Redirect Reference 4.3.6.2 Example: LOCK on a Collection That Contains a Redirect
Reference, with Passthrough: T
4.7.5 Example: LOCK on a Collection That Contains a Direct Reference and Suppose a LOCK request is submitted to the following collection, with
a Redirect Reference the members shown:
/MyCollection/ /MyCollection/
(ordinary resource) diary.html (ordinary resource) diary.html
(direct reference) tuva
(redirect reference) nunavut (redirect reference) nunavut
Request: >> Request:
LOCK /MyCollection/ HTTP/1.1 LOCK /MyCollection/ HTTP/1.1
Host: www.svr.com Host: www.svr.com
Passthrough: T
Content-Type: text/xml Content-Type: text/xml
Content-Length: nnnn Content-Length: nnnn
Authorizaton: Digest username="jas", Authorizaton: Digest username="jas",
realm=jas@webdav.sb.aol.com, nonce=". . .", realm=jas@webdav.sb.aol.com, nonce=". . .",
uri="/MyCollection/tuva", uri="/MyCollection/tuva",
response=". . .", opaque=". . ." response=". . .", opaque=". . ."
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:lockinfo xmlns:D="DAV:"> <D:lockinfo xmlns:D="DAV:">
<D:lockscope><D:exclusive/></D:lockscope> <D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype> <D:locktype><D:write/></D:locktype>
<D:owner> <D:owner>
<D:href>http://www.svr.com/~jas/contact.html</D:href> <D:href>http://www.svr.com/~jas/contact.html</D:href>
</D:owner> </D:owner>
</D:lockinfo> </D:lockinfo>
Response: >> Response:
HTTP/1.1 207 Multi-Status HTTP/1.1 207 Multi-Status
Content-Type: text/xml Content-Type: text/xml
Content-Length: nnnn Content-Length: nnnn
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:multistatus xmlns:D="Dav:">
<D:multistatus xmlns:D="DAV:">
<D:response> <D:response>
<D:href>/MyCollection/</D:href> <D:href>http://www.svr.com/MyCollection/</D:href>
<D:status>HTTP/1.1 200 OK</D:status> <D:propstat>
<D:prop> <D:prop><D:lockdiscovery/></D:prop>
<D:lockdiscovery> <D:status>HTTP/1.1 424 Failed Dependency</D:status>
<D:activelock> </D:propstat>
<D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype>
<D:depth>0</D:depth>
<D:owner>
<D:href>http://www.svr.com/~jas/contact.html</D:href>
</D:owner>
<D:locktoken>
opaquelocktoken:e71dfae-5dec-22d6-fea5-00a0c91e6be4
</D:locktoken>
</D:activelock>
</D:lockdiscovery>
</D:prop>
</D:response> </D:response>
<D:response> <D:response>
<D:href>/MyCollection/tuva</D:href> <D:href>http://www.svr.com/MyCollection/diary.html</D:href>
<D:status>HTTP/1.1 200 OK</D:status> <D:status>HTTP/1.1 424 Failed Dependency</D:status>
<D:prop>
<D:reftype>direct</D:reftype>
<D:reftarget>
<D:href>http://www.feynman.com/tuva/</D:href>
</D:reftarget>
</D:prop>
</D:response> </D:response>
<D:response> <D:response>
<D:href>/MyCollection/nunavut</D:href> <D:href>http://www.svr.com/MyCollection/nunavut</D:href>
<D:status>HTTP/1.1 200 OK</D:status> <D:status>HTTP/1.1 302 Moved Temporarily</D:status>
<D:prop> <D:prop>
<D:reftype>redirect</D:reftype> <D:location>
<D:reftarget>
<D:href>http://www.inac.gc.ca/art/inuit/</D:href> <D:href>http://www.inac.gc.ca/art/inuit/</D:href>
</D:reftarget> </D:location>
<D:resourcetype><D:redirectref/></D:resourcetype>
</D:prop> </D:prop>
</D:response> </D:response>
</D:multistatus> </D:multistatus>
Although the entire LOCK operation was successful, a Multi-Status The "Passthrough: T" header caused the server to return a 302 response
response is still REQUIRED, so that the DAV:reftype and DAV:reftarget code for the redirect reference in the collection. Consequently,
properties can be returned for the references in the collection. The neither the collection nor any of the resources identified by its
results for each reference MUST be reported in a separate DAV:response internal member URIs were locked. A referencing-aware client can submit
element so that it is clear which reference is associated with which a separate LOCK request to the URI in the DAV:location property returned
values of DAV:reftype and DAV:reftarget. In this case, since for the redirect reference, and can resubmit the LOCK request with
/MyCollection/tuva is a direct reference, its target resource was "Passthrough: F" to the collection. At that point both the reference
locked. Since /MyCollection/nunavut is a redirect reference, the and its target will be locked (as well as the collection and all the
reference itself, and not its target, was locked. There is no response resources identified by its other members).
element for the ordinary resource /MyCollection/diary.html, since it was
successfully locked and no special information needs to be returned for
it.
4.8 Other WebDAV Operations on Redirect Referential Resources 4.3.7 Other Operations on Redirect References
Although non-referencing WebDAV clients cannot create referential Although non-referencing-aware clients cannot create referential
resources, they should be able to use the references created by resources, they should be able to use the references created by
reference-aware WebDAV clients. They should be able to follow any reference-aware WebDAV clients. They should be able to follow any
references to their targets. To make this possible, a server that references to their targets. To make this possible, a server that
receives a PROPFIND, PROPPATCH, MKCOL, or MKREF request made via a receives a GET, HEAD, PUT, POST, OPTIONS, PROPFIND, PROPPATCH, MKCOL,
redirect reference MUST return a 302 (Moved Temporarily) status code. MKREF, BIND, or ORDERPATCH request made via a redirect reference MUST
The client and server MUST follow [HTTP] Section 10.3.3 "302 Moved return a 302 (Moved Temporarily) status code. The client and server MUST
Temporarily," but with these additional rules: follow [HTTP] Section 10.3.3 "302 Moved Temporarily," but with these
additional rules:
o The Location response header MUST contain the target URI of the o The Location response header MUST contain the absolute target URI of
reference. the reference.
o The response MUST include the Ref-Type header. This header allows o The response MUST include the Resource-Type header. This header
reference-aware WebDAV clients to recognize the resource as a allows reference-aware WebDAV clients to recognize the resource as a
reference and understand the reason for the redirection. reference and understand the reason for the redirection.
A reference-aware WebDAV client can act on this response in one of two A reference-aware WebDAV client can act on this response in one of two
ways. It can, like a non-referencing client, resubmit the request to ways. It can, like a non-referencing client, resubmit the request to
the URI in the Location header in order to operate on the target the URI in the Location header in order to operate on the target
resource. Alternatively, it can resubmit the request to the URI of the resource. Alternatively, it can resubmit the request to the URI of the
redirect reference with the No-Passthrough header in order to operate on redirect reference with the Passthrough header set to "F" in order to
the reference itself. If the No-Passthrough header is present, the operate on the reference itself. If the Passthrough header is present
request MUST be applied to the reference itself, and a 302 response MUST with a value of "F", the request MUST be applied to the reference
NOT be returned. itself, and a 302 response MUST NOT be returned.
If a reference-aware client knows before submitting its request that the If a reference-aware client knows before submitting its request that the
request-URI identifies a redirect reference, it can save the round trip request-URI identifies a redirect reference, and if the client wants to
caused by the 302 response by using No-Passthrough in its initial apply the method to the reference, it can save the round trip caused by
request to the URI. the 302 response by using "Passthrough: F" in its initial request to the
Since MKCOL and MKREF fail when applied to existing resources, if the
client attempts to resubmit the request to the target resource, the
request MUST fail (unless the reference is a dangling reference).
Similarly, if the client attempts to resubmit the request to the
reference with a No-Passthrough header, the request MUST fail.
4.8.1 Example: PROPPATCH on a Redirect Reference
4.9 Other WebDAV Operations on Direct Referential Resources
With the exception of DELETE and MOVE, which were discussed above,
operations on direct references affect the target resource, not the
reference, unless the No-Passthrough header is used.
Unless the No-Passthrough header is used, a PROPPATCH on a direct
reference MUST modify the properties of its target resource, not the
properties of the reference itself.
Unless the No-Passthrough header is used, a PROPFIND on a direct
reference MUST return the properties of its target resource, not the
properties of the reference itself.
If the No-Passthrough header is used with a PROPPATCH or PROPFIND URI.
request on a direct reference, the operation MUST be applied to the "Passthrough: F" can be used with GET or HEAD to retrieve the entity
reference itself rather than to its target resource. headers of a redirect reference. When "Passthrough: F" is used with GET
or HEAD, the referencing entity headers (Ref-Type and Ref-Target) MUST
be returned, along with all HTTP headers that make sense for references
(at a minimum, Cache-Control, Age, ETag, Expires, and Last-Modified).
MKCOL and MKREF fail if their request-URI identifies an existing "Passthrough: F" can be used with PUT to replace the redirect reference
resource of any kind. Consequently, when submitted to a target resource with an ordinary resource. It can be used with OPTIONS to retrieve the
via a direct reference, they MUST fail unless the reference is a capabilities of a redirect reference.
dangling reference. If they are submitted to an existing direct
reference with the No-Passthrough header, they MUST also fail.
4.9.1 Example: PROPPATCH on a Direct Reference Clients MUST NOT, however, use "Passthrough: F" with POST. Since a
reference cannot accept another entity as its subordinate, an attempt to
POST to a reference with "Passthrough: F" will also fail. If a server
receives a POST request with "Passthrough: F" on a redirect reference,
it MUST fail the request with a 400 (Bad Request) status code.
4.10 HTTP Operations on Redirect Referential Resources Since MKCOL fails when applied to existing resources, if the client
attempts to resubmit the request to the target resource, the request
MUST fail (unless the reference is a dangling reference). Similarly, if
the client attempts to resubmit the request to the reference with
"Passthrough: F", the request MUST fail.
Although existing HTTP clients cannot create referential resources, they Since ORDERPATCH applies only to collections, an ORDERPATCH request with
should be able to use collections created by reference-aware WebDAV a Passthrough header with the value "F" on a redirect reference MUST
clients. They should be able to follow any references identified by fail.
URIs in those collections to their targets. To enable existing HTTP
clients to use GET, HEAD, PUT, POST, or OPTIONS via redirect references,
a server that receives any of these requests on a redirect reference
MUST return a 302 (Moved Temporarily). The client and server MUST
follow [HTTP] Section 10.3.3 "302 Moved Temporarily," but with these
additional rules:
o The Location response header MUST contain the target URI of the 4.3.7.1 Example: GET on a Redirect Reference
reference.
o The response MUST include the Ref-Type header. This header allows >> Request:
reference-aware WebDAV clients to recognize the resource as a
reference and understand the reason for the redirection.
Reference-aware clients can act on a 302 response in either of two ways. GET /bar.html HTTP/1.1
Like plain HTTP clients, they can resubmit the request to the URI in the Host: www.foo.com
Location header (the URI of the target resource). They may, however,
want to operate on the reference rather than on its target. In this
case, they may resubmit the request to the URI of the reference and
include the No-Passthrough header with the request. If the No-
Passthrough header is present, the request MUST be applied to the
reference itself, and a 302 response MUST NOT be returned.
If a reference-aware client knows before submitting its request that the >> Response:
request-URI identifies a redirect reference, it can save the round trip
caused by the 302 response by using No-Passthrough in its initial
request to the URI.
The No-Passthrough header can be used with GET or HEAD to retrieve the HTTP/1.1 302 Moved Temporarily
entity headers of a redirect reference. When No-Passthrough is used Location: http://www.svr.com/Internet/xxspec08.html
with GET or HEAD, the referencing entity headers (Ref-Type and Ref- Resource-Type: DAV:redirectref
Target) MUST be returned, along with all HTTP headers that make sense
for references (at a minimum, Cache-Control, Age, ETag, Expires, and
Last-Modified).
The No-Passthrough header can be used with PUT to replace the redirect Since /bar.html is a redirect reference and the Passthrough header is
reference with an ordinary resource. It can be used with OPTIONS to not included in the request, the response is a 302 (Moved Temporarily).
retrieve the capabilities of a redirect reference. The Resource-Type header informs a reference-aware client that this is
not an ordinary HTTP 1.1 redirect, but is a redirect reference. The URI
of the target resource is provided in the Location header so that the
client can resubmit the request to the target resource.
Clients MUST NOT, however, use the No-Passthrough header with POST. 4.3.7.2 Example: PUT on a Redirect Reference with "Passthrough: F"
Since a reference cannot accept another entity as its subordinate, an
attempt to POST to a reference with No-Passthrough will also fail. If a
server receives a POST request with the No-Passthrough header on a
redirect reference, it MUST fail the request with a 400 (Bad Request)
status code.
4.10.1 Example: GET on a Redirect Reference >> Request:
4.10.2 Example: GET on a Redirect Reference with No-Passthrough PUT /bar.html HTTP/1.1
Host: www.foo.com
Passthrough: F
4.11 HTTP Operations on Direct Referential Resources Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
GET, HEAD, PUT, POST, and OPTIONS on direct references are automatically . . . some content . . .
passed through to their target resources. GET MUST return the content
and headers of the target resource, HEAD MUST return the headers of the
target resource, PUT MUST replace the content of the target resource,
POST MUST perform the expected function at the target resource, and
OPTIONS MUST report the communication options available at the target
resource.
The No-Passthrough request header MAY be used with GET, HEAD, PUT, or >> Response:
OPTIONS to view the headers or capabilities of the reference, rather
than its target.
The No-Passthrough request header MUST NOT be used with POST, which HTTP/1.1 200 OK
cannot be applied to references. If a server receives a POST request on
a direct reference with the No-Passthrough header, it MUST fail the
request with a 400 (Bad Request) status code.
4.11.1 Example: GET on a Direct Reference Although /bar.html is a redirect reference, the presence of the
"Passthrough: F" header prevents a 302 response, and instead causes the
request to be applied to the reference. The result in this case is that
the reference is replaced by an ordinary resource having the content
submitted with the request.
4.11.2 Example: GET on a Direct Reference with No-Passthrough 4.3.7.3 Example: PROPPATCH on a Redirect Reference
4.12 Operations on Targets of Referential Resources Request:
In general, operations on targets of weak referential resources have no PROPPATCH /bar.html HTTP/1.1
effect on the referential resource. However, servers that choose to Host: www.foo.com
maintain the integrity of references are free to make changes to the Content-Type: text/xml; charset="utf-8"
state of references when moving or deleting their targets. Content-Length: xxxx
When moving a target resource, a server MAY insert an optional step into <?xml version="1.0" encoding="utf-8" ?>
the semantics of MOVE as defined in [WebDAV] for the purpose of <D:propertyupdate xmlns:D="DAV:"
maintaining referential integrity. Between the copy step and the delete xmlns:Z="http://www.w3.com/standards/z39.50/">
step of a MOVE, the server MAY perform an update step, which changes the <D:set>
DAV:reftarget property of any references to the target to reflect its <D:prop>
new location. <Z:authors>
<Z:Author>Jim Whitehead</Z:Author>
<Z:Author>Roy Fielding</Z:Author>
</Z:authors>
</D:prop>
</D:set>
<D:remove>
<D:prop><Z:Copyright-Owner/></D:prop>
</D:remove>
</D:propertyupdate>
When deleting a target resource, a server MAY perform any internal Response:
operations necessary to implement its policy on preserving referential
integrity. For example, it might delete any references to the deleted
target, or it might flag them as having a deleted target, or it might
replace references with copies of the target.
4.13 Discovering a Target’s References HTTP/1.1 302 Moved Temporarily
Location: http://www.svr.com/Internet/xxspec08.html
Resource-Type: DAV:redirectref
An OPTIONAL DAV:references property on the target resource provides a Since /bar.html is a redirect reference and the Passthrough header is
list of referential resources whose DAV:reftarget property points to not included in the request, the response is a 302 (Moved Temporarily).
that target resource. If present, DAV:references is a read-only The Resource-Type header informs a reference-aware client that this is
property, maintained by the server. By retrieving this property, a not an ordinary HTTP 1.1 redirect, but is a redirect reference. The URI
client can discover the URIs of the references that point to the target, of the target resource is provided in the Location header so that the
and so can also discover the collections that contain those URIs as client can resubmit the request to the target resource.
members. As for all DAV: properties, this specification is silent as to
how the DAV:references property is implemented on the server.
The DAV:references property is expected to be supported mainly by 4.3.8 Operations on Targets of Redirect References
Document Management Systems (DMSs) and other servers that will maintain
the property only for references within their own domain. It is not in
general possible for a server to maintain the property for references on
other servers. If a reference on a different server points to the
target, the server where the target is located is unlikely to know about
that reference. This protocol provides no mechanism for one server to
notify another of the creation of a reference to one of its resources.
Consequently, the list of references in DAV:reftarget may be incomplete.
Rationale: A number of scenarios require clients to navigate from a Operations on targets of redirect references have no effect on the
target resource to the references that point to it, and to the reference.
collections that contain the URIs of those references. This capability
is particularly important for DMSs, which may populate their collections
entirely by reference. Their clients may need to determine, for any
object in the DMS, what collections contain URIs that identify
references to that object. It is also important in other contexts. For
example, some servers enforce referential integrity by refusing to
delete any resource that is referenced by other resources. In such an
environment, the client must be able to discover the references in order
to delete them before attempting to delete the target.
Risks: When deciding whether to support the DAV:references property, 4.3.9 Relative URIs in Ref-Target and DAV:reftarget
server implementers / administrators should balance the benefits it
provides against the cost of maintaining the property and the security
risks enumerated in Sections 12.4 and 12.5.
4.14 Behavior of Dangling Direct References The URI in a Ref-Target header MAY be a relative URI. Similarly, the
href in a DAV:reftarget property MAY be a relative URI. In both cases,
the base URI to be used for resolving the relative URI to absolute form
is the URI used in the HTTP message to identify the redirect reference
to which the Ref-Target entity header or DAV:reftarget property belongs.
Whenever the No-Passthrough header accompanies a request on a dangling In the case of a Ref-Target header, the base URI is constructed as
direct reference, the request succeeds. Since No-Passthrough causes the follows: Its scheme component is "http", its authority component is the
request to be applied to the reference rather than to its target, it value of the Host header in the request, and its path component is the
does not matter that the target resource does not exist. The client request-URI in the request. See Section 5 of [URI] for a discussion of
will not be informed that the reference points to a nonexistent target. relative URI references and how to resolve them.
In the absence of the No-Passthrough header, the responses MUST be as The DAV:reftarget property appears in the protocol in the context of a
follows: Multi-Status response, in a DAV:response element that contains a single
DAV:href element. The value of this DAV:href element serves as the base
URI for resolving a relative URI in DAV:reftarget. The value of
DAV:href may itself be relative, in which case it must be resolved first
in order to serve as the base URI for the relative URI in DAV:reftarget.
If the DAV:href element is relative, its base URI is constructed from
the scheme component "http", the value of the Host header in the
request, and the request-URI.
GET, HEAD, OPTIONS, POST, PROPFIND, PROPPATCH, LOCK, UNLOCK, and COPY 4.3.9.1 Example: Resolving a Relative URI in Ref-Target
respond with 404 (Not Found), but the Ref-Type and Ref-Target headers
are included in the response, so that the client can tell that it is the
target, and not the reference, that was not found.
If, however, a PROPFIND, LOCK, UNLOCK, or COPY with Depth header greater >> Request:
than 0 on a collection encounters a dangling direct reference inside the
collection, the response is a 207 (Multi-Status). The DAV:response MKREF /north/inuvik HTTP/1.1
element for the dangling reference will have a status of 404 (Not Host: www.somehost.edu
Found). The DAV:reftype and DAV:reftarget properties of the references Ref-Target: mapcollection/inuvik.gif
are included in the response. Their presence informs the client that it
is the target, not the reference, that was not found. Including these
two properties requires an extension to the DAV:response element as
defined in {WEBDAV]. This extension is defined in Section 9 below.
PUT succeeds, creating a new resource at the location specified by the >> Response:
reference’s DAV:reftarget property.
MKREF and MKCOL succeed, since there is no existing resource at the HTTP/1.1 201 Created
target URI.
MOVE and DELETE succeed, since they always affect the reference rather In this example, the base URI is http://www.somehost.edu/north/inuvik.
than its target. For MOVE, the reference at the destination will be Then, following the rules in [URI] Section 5, the relative URI in Ref-
broken, just as the reference at the source was. Target resolves to the absolute URI
http://www.somehost.edu/north/mapcollection/inuvik.gif.
4.14.1 Example: PROPFIND on a Collection with a Dangling Direct 4.3.9.2 Example: Resolving a Relative URI in DAV:reftarget
Reference
Request: >> Request:
PROPFIND /collection1/ HTTP/1.1 PROPFIND /geog/ HTTP/1.1
Host: www.somehost.com Host: www.xxsvr.com
Passthrough: F
Depth: 1 Depth: 1
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxxx Content-Length: nnn
<?xml version="1.0" ?> <?xml version="1.0" ?>
<D:propfind xmlns:D="DAV:"> <D:propfind xmlns:D="DAV:">
<D:prop xmlns:X="http://www.somehost.com/schemas/x"> <D:prop>
<X:author/> <D:resourcetype/>
<X:title/> <D:reftarget/>
</D:prop> </D:prop>
</D:propfind> </D:propfind>
Response: >> Response:
HTTP/1.1 207 Multi-Status HTTP/1.1 207 Multi-Status
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxxx Content-Length: nnn
<?xml version="1.0" ?> <?xml version="1/0" ?>
<D:multistatus xmlns:D="DAV:"> <D:multistatus xmlns:D="DAV:">
<D:response> <D:response>
<D:href>http://www.somehost.com/collection1/</D:href> <D:href>/geog/</D:href>
<D:propstat> <D:propstat>
<D:prop xmlns:X=http://www.somehost.com/schemas/x> <D:prop>
<X:author>Smith, J.H.</X:author> <D:resourcetype><D:collection/></D:resourcetype>
<X:title>My Working Collection</X:title>
</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:prop><D:reftarget/></D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response> </D:response>
<D:response> <D:response>
<D:href>http://www.somehost.com/collection1/directref7</D:href> <D:href>/geog/stats.html</D:href>
<D:status>HTTP/1.1 404 Not Found</D:status> <D:propstat>
<D:prop> <D:prop>
<D:reftype><D:direct/></D:reftype> <D:resourcetype><D:redirectref/></D:resourcetype>
<D:reftarget> <D:reftarget>statistics/population/1997.html</D:reftarget>
<D:href>/collection2/file19</D:href>
</D:reftarget>
</D:prop> </D:prop>
<D:responsedescription>Target resource not found. <D:status>HTTP/1.1 200 OK</D:status>
</D:responsedescription> </D:propstat>
</D:response> </D:response>
</D:multistatus> </D:multistatus>
4.15 Chains of Direct References In this example, the relative URI statistics/population/1997.html is
returned as the value of reftarget for the reference identified by href
Unless a No-Passthrough header is present, any operation on a direct /geog/stats.html. The href is itself a relative URI, which resolves to
reference that is part of a chain of direct references MUST get passed http://www.xxsrv.com/geog/stats.html. This is the base URI for
through to the target of the last reference in the chain. resolving the relative URI in reftarget. The absolute URI of reftarget
is http://www.xxsrv.com/geog/statistics/population/1997.html.
Whenever a response is required to include the Ref-Target header, for a
chain of direct references, there MUST be a Ref-Target header for each
reference in the chain. In order for the client to know which reference
in the chain each Ref-Target belongs to, the value of each Ref-Target
header MUST include a hop-number of the reference as well as the URL of
its target resource. For example,
Request:
HEAD /math/ref1 HTTP/1.1
Host: www.somehost.edu
Response:
HTTP/1.1 200 ok
Ref-Type: direct
Ref-Target: 0; /logic/ref2
Ref-Target: 1; /library/ref3
Ref-Target: 2; /library/frege/grundgesetze.html
.
.
A server cannot tell whether a dangling reference once pointed to an 4.3.10 Redirect References to Collections
ordinary resource or to another reference in a chain of direct
references. When a break occurs before the end of a chain of direct
references, the server’s behavior will be the same as for any other
dangling direct reference, as described in Section 4.13. For example, a
PUT will create the new resource at the location specified by the
DAV:reftarget property of the broken reference, even if that is in the
middle of what was once a chain of direct references.
4.16 URIs and References In a Request-URI /segment1/segment2/segment3, any of the three segments
may identify a redirect reference. (See [URI], Section 3.3, for
definitions of "path" and "segment".) If any segment in a Request-URI
identifies a redirect reference, the response is a 302. The value of
the Location header in the 302 response is as follows:
In a request-URI /segment1/segment2/segment3, any of the three segments The leftmost path segment of the request-URI that identifies a redirect
may identify a reference. (See [URI], Section 3.3, for definitions of reference, together with all path segments and separators to the left of
it, is replaced by the value of the redirect reference's
DAV:reftarget property (resolved to an absolute URI). The remainder of
the request-URI is concatenated to this path.
"path" and "segment".) Servers will be unable to resolve such URIs Note: If the DAV:reftarget property ends with a "/" and the remainder of
unless certain constraints hold. If any segment of the path identifies the Request-URI is non-empty (and therefore must begin with a "/"), the
a reference, that reference MUST ultimately resolve to a resource that final "/" in the DAV:reftarget property is dropped before the remainder
behaves as a container. (Examples are WebDAV collections, tar files, of the Request-URI is appended.
and some CGI scripts.) The succeeding segment of the path MUST resolve
to a resource that is immediately contained in that container.
Consider request-URI /x/y/z.html. Suppose that /x/ is a reference whose Consider Request-URI /x/y/z.html. Suppose that /x/ is a redirect
target is collection /a/, which contains reference y whose target is reference whose target is collection /a/, which contains redirect
collection /b/, which contains reference z.html whose target is reference y whose target is collection /b/, which contains redirect
/c/d.html. reference z.html whose target is /c/d.html.
/x/ -----> /a/ /x/ -----> /a/
/a/y/ -----> /b/ /a/y/ -----> /b/
/b/z.html -----> /c/d.html /b/z.html -----> /c/d.html
The server is able to resolve the request-URI because each segment of In this case the client must follow up three separate 302 responses
the URI's path satisfies the constraints stated above. Except for the before finally reaching the target resource. The server responds to the
final segment, each segment that is a reference resolves to a collection initial request with a 302 with Location: /a/y/z.html, and the client
that contains the next segment as an internal member. The final resubmits the request to /a/y/z.html. The server responds to this
segment, which is a reference, does have a target resource. request with a 302 with Location: /b/z.html, and the client resubmits
the request to /b/z.html. The server responds to this request with a
If the references are direct references, the server automatically 302 with Location: /c/d.html, and the client resubmits the request to
applies the request to the ultimate target, /c/d.html. /c/d.html. This final request succeeds.
If the references are redirect references, the client must follow up
three separate 302 responses before finally reaching the target
resource. The server responds to the initial request with a 302 with
Location: /a/y/z.html, and the client resubmits the request to
/a/y/z.html. The server responds to this request with a 302 with
Location: /b/z.html, and the client resubmits the request to /b/z.html.
The server responds to this request with a 302 with Location: /c/d.html,
and the client resubmits the request to /c/d.html. This final request
succeeds.
5 Ordered Collections 5 Ordered Collections
5.1 Overview 5.1 Overview
Collections on a compliant server may be ordered, but need not be. It Collections on a compliant server may be ordered, but need not be. It
is up to the client to decide whether a given collection is ordered and, is up to the client to decide whether a given collection is ordered and,
if so, to specify the semantics to be used for ordering its members. If if so, to specify the semantics to be used for ordering its bindings.
a collection is ordered, each of its members must be in the ordering If a collection is ordered, each of its bindings, and hence internal
exactly once, and the ordering must not include any resource that is not member URIs, MUST be in the ordering exactly once, and the ordering MUST
a member of the collection. Only one ordering can be attached to any NOT include any binding that is not contained by the collection. Only
collection. Multiple orderings of the same resources can be achieved by one ordering can be attached to any collection. An ordering is
creating multiple collections referencing those resources, and attaching considered to be part of the state of a collection resource, and hence
a different ordering to each collection. 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. The server is responsible for enforcing these constraints on orderings.
The server MUST remove a member URI from the ordering when it is removed The server MUST remove a binding (and its derived internal member URI)
from the collection. The server MUST add a member URI to the ordering from the ordering when it is removed from the collection. The server
MUST add a binding (and its derived internal member URI) to the ordering
when it is added to the collection. when it is added to the collection.
When responding to a PROPFIND on a collection, the server MUST order the When responding to a PROPFIND on a collection, the server MUST order the
response elements according to the ordering defined on the collection. response elements according to the ordering defined on the collection.
If the collection is unordered, the client cannot depend on the
repeatability of the ordering of results from a PROPFIND request.
Orderings may be client-maintained or server-maintained. This protocol
provides support for both types of orderings.
5.2 Creating an Ordered Collection 5.2 Creating an Ordered Collection
5.2.1 Overview 5.2.1 Overview
When a collection is created, the client can 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 in the MKCOL request, setting its value to the URI of the header (defined in Section 6.5) with a MKCOL request.
semantics to be used or setting its value to DAV:custom if the semantics
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".
Every collection MUST have the new DAV:orderingtype property, which
indicates whether the collection is ordered and, if so, identifies the
semantics of the ordering. A value of DAV:unordered indicates that that
collection is not ordered. That is, the client cannot depend on the
repeatability of the ordering of results from a PROPFIND request. For
collections that are ordered, DAV:orderingtype SHOULD be set to an href
that identifies the semantics of the ordering, allowing a human user or
software package to insert new collection members into the ordering
intelligently. Although the href 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 DAV:orderingtype property MAY be set to DAV:custom to
indicate that the collection is to be ordered, but the semantics of the
ordering is not being advertised.
If the Ordered header is present on a MKCOL request, the server MUST set For collections that are ordered, the client SHOULD identify the
the collection's DAV:orderingtype property to the value of the Ordered semantics of the ordering with a URI in the Ordered header. This URI
header. If the Ordered header is not present, the server MUST treat the may identify a server-maintained ordering. Clients can discover the
request as if it had an Ordered header with the value "DAV:unordered", available server-maintained orderings using the mechanism defined in
meaning that the collection is not ordered. If the collection is Section 11.3. The URI may identify a semantics for a client-maintained
ordered, the server MUST respond to PROPFIND requests on the collection ordering, providing the information a human user or software package
using the specified ordering. 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.
5.2.2 Status Codes 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.
Servers MUST use the HTTP/1.1 status codes as defined in [HTTP]. Every collection MUST have a DAV:orderingtype property (defined in
Section 7.5), 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 the collection is unordered, the
DAV:orderingtype property MUST have the value 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.3 Example: Creating an Ordered Collection 5.2.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:
HTTP/1.1 201 Created HTTP/1.1 201 Created
In this example, a new, ordered collection was created. Its In this example a new, ordered collection was created. Its
DAV:orderingtype property has as its value the URI from the Ordered DAV:orderingtype property has as its value the URI from the Ordered
header, http://www.server.org/orderings/compass.html. In this case, the
header. In this case, the URI identifies the semantics governing the URI identifies the semantics governing a client-maintained ordering. As
ordering. As new members are added to the collection, clients or end new members are added to the collection, clients or end users can use
users can use the semantics to determine where to position the new the semantics to determine where to position the new members in the
members in the ordering. ordering.
5.3 Setting the Position of a Collection Member 5.3 Setting the Position of a Collection Member
5.3.1 Overview 5.3.1 Overview
When a new member is added to a collection (for example, with PUT, When a new member is added to a collection with a client-maintained
MKREF, or MKCOL), its position in the ordering can be set with the new ordering (for example, with PUT, MKREF, or MKCOL), its position in the
Position header. The Position header allows the client to specify that ordering can be set with the new Position header (defined in Section
the member should be first in the collection's ordering, last in the 6.6). The Position header allows the client to specify that the member
collection's ordering, before some other collection member in the should be first in the collection's ordering, last in the collection's
collection's ordering, or after some other collection member in the ordering, immediately before some other binding in the collection's
collection's ordering. ordering, or immediately after some other binding in the collection's
ordering.
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
collection is ordered); otherwise, it MUST append the new member to the
end of the ordering (if the collection is ordered). If a PUT causes an
existing resource to be replaced, and if the Position header is absent,
the server MUST leave the member at its previous position in thee
collection ordering. If the Position header is present, the server MUST
remove the member from its previous position, and then insert it at the
requested position.
5.3.2 Status Codes 5.3.2 Status Codes
Servers MUST use the HTTP/1.1 status codes as defined in [HTTP]. Some 409 (Conflict): The request specifies a position that is before or after
likely client errors for when setting the position of a collection a URI that is not an internal member URI of the collection, or before or
member include: after itself.
409 (Conflict): The request may be attempting to position the collection 425 (Unordered Collection): The request specifies a collection position
member before or after a URI that is not in the collection, or before or in an unordered collection or in a collection with a server-maintained
after itself, or it may be attempting to position the collection member ordering.
in an unordered collection.
5.3.3 Examples: Setting the Position of a Collection Member 5.3.3 Examples: Setting the Position of a Collection Member
Request: >>Request:
MKREF /~whitehead/dav/spec08.ref HTTP/1.1 MKREF /~whitehead/dav/spec08.ref 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> Ref-Target: http://www.ics.uci.edu/i-d/draft-webdav-protocol-08.txt
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 referential resource at
www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource
identified by the Ref-Target header. 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. /~whitehead/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: </~whitehead/dav/draft-webdav-protocol-08.txt> Destination: http://www.ics.uci.edu/~whitehead/dav/draft-webdav-
protocol-08.txt
Position: First Position: First
Response: >>Response:
HTTP/1.1 409 Conflict HTTP/1.1 425 Unordered Collection
In this case, the server returned a 409 Conflict status code because the In this case, the server returned a 425 (Unordered Collection) status
/~whitehead/dav/ collection is an unordered collection. Consequently, code because the /~whitehead/dav/ collection is an unordered collection.
the server was unable to satisfy the Position header. Consequently, the server was unable to satisfy the Position header.
5.4 Changing the Semantics of a Collection Ordering 5.4 Changing the Semantics of a Collection Ordering
After a collection has been created, a client can change its ordering After a collection has been created, a client can change its ordering
semantics, or change an ordered collection to an unordered collection or semantics, or change an ordered collection to an unordered collection or
vice versa, by using PROPPATCH to change the value of its vice versa, by using PROPPATCH to change the value of its
DAV:orderingtype property. The client is then responsible for updating DAV:orderingtype property (defined in Section 7.5). If the new value
the ordering of the collection members according to the new semantics. identifies a client-maintained ordering, the client is then responsible
PROPPATCH is defined in [WebDAV], Section 7.2. 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. PROPPATCH is defined in
[WebDAV], Section 7.2.
5.5 Changing the Position of a Collection Member 5.5 Changing the Position of a Collection Member
5.5.1 The ORDERPATCH Method 5.5.1 ORDERPATCH Method
To change the positions of collection members in the collection's The ORDERPATCH method alters the ordering of bindings in the collection
ordering, the client MUST use an ORDERPATCH request with a request body identified by the Request-URI, based on instructions in the order XML
containing an order XML element. The request-URI of an ORDERPATCH element. The order XML element identifies the bindings whose positions
request is the URI of the collection whose ordering is to be updated. are to be changed, and describes their new positions in the ordering.
The order XML element identifies the member URIs whose positions are to Each new position can be specified as first in the ordering, last in the
be changed, and describes their new positions in the ordering. Each new ordering, immediately before some other binding, or immediately after
position can be specified as first in the ordering, last in the some other binding.
ordering, before some other collection member in the ordering, or after
some other collection member in the ordering. The server MUST apply the The server MUST apply the changes in the order they appear in the order
changes in the order they appear in the order element. XML element. The server MUST either apply all the changes or apply none
of them. If any error occurs during processing, all executed changes
MUST be undone and a proper error result returned.
5.5.2 Status Codes 5.5.2 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 the server MUST return a 207 (Multi-Status) response, as defined in
[WebDAV]. [WebDAV].
Within the 207 Multi-Status response, the following status codes are The following are examples of response codes one would expect to be used
possible: 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): An attempt was made to position the collection member 409 (Conflict): The request specifies a position that is before or after
before or after a URI that is not in the collection, or before or after a URI that is not an internal member URI of the collection, or before or
itself, or an attempt was made to position the collection member in an after itself.
unordered collection. 425 (Unordered Collection): The request specifies a collection position
in an unordered collection or in a collection with a server-maintained
ordering.
A request to reposition a collection member to the same place in the A request to reposition a binding at the same place in the ordering is
ordering is not an error. not an error.
5.5.3 Example: Changing the Positions of Collection Members in the 5.5.3 Example: Changing Positions in an Ordered Collection
Ordering
Consider a collection /coll-1/ with members ordered as follows: Consider a collection /coll-1/ with bindings 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
Request: >> Request:
ORDERPATCH /coll-1/ HTTP/1.1 ORDERPATCH /coll-1/ HTTP/1.1
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>
skipping to change at line 1881 skipping to change at line 2048
</d:position> </d:position>
</d:ordermember> </d:ordermember>
<d:ordermember> <d:ordermember>
<d:href>iqaluit.img</d:href> <d:href>iqaluit.img</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 207 Multi-Status
Content-Type: text/xml Content-Type: text/xml
Content-Length: xxx Content-Length: xxx
<?xml version="1.0" ?> <?xml version="1.0" ?>
<d:multistatus xmlns:d="DAV:"> <d:multistatus xmlns:d="DAV:">
<d:response> <d:response>
<d:href>http://www.nunanet.com/coll-1/nunavut.desc</d:href> <d:href>http://www.nunanet.com/coll-1/nunavut.desc</d:href>
<d:status>HTTP/1.1 200 OK</d:status> <d:status>HTTP/1.1 200 OK</d:status>
</d:response> </d:response>
<d:response> <d:response>
<d:href>http://www.nunanet.com/coll-1/iqaluit.img</d:href> <d:href>http://www.nunanet.com/coll-1/iqaluit.img</d:href>
skipping to change at line 1899 skipping to change at line 2067
<d:response> <d:response>
<d:href>http://www.nunanet.com/coll-1/nunavut.desc</d:href> <d:href>http://www.nunanet.com/coll-1/nunavut.desc</d:href>
<d:status>HTTP/1.1 200 OK</d:status> <d:status>HTTP/1.1 200 OK</d:status>
</d:response> </d:response>
<d:response> <d:response>
<d:href>http://www.nunanet.com/coll-1/iqaluit.img</d:href> <d:href>http://www.nunanet.com/coll-1/iqaluit.img</d:href>
<d:status>HTTP/1.1 200 OK</d:status> <d:status>HTTP/1.1 200 OK</d:status>
</d:response> </d:response>
</d:multistatus> </d:multistatus>
In this example, after the request has been processed, the collection's If the href elements are relative URIs, as in this example, they are
ordering is as follows: interpreted relative to the collection that is being reordered. In this
example, after the request has been processed, the collection's ordering
is as follows:
nunavut.map nunavut.map
nunavut.desc nunavut.desc
nunavut.img nunavut.img
baffin.map baffin.map
baffin.desc baffin.desc
baffin.img baffin.img
iqaluit.map iqaluit.map
iqaluit.desc iqaluit.desc
iqaluit.img iqaluit.img
5.5.4 Design Rationale 5.5.4 Example: Failure of an ORDERPATCH Request
The decision to introduce the new ORDERPATCH method was made after
investigating the possibility of using the existing MOVE method with a
Position header. The use of MOVE initially looked appealingly simple:
MOVE /root/coll-1/foo HTTP/1.1
Host: www.somehost.com
Destination: </root/coll-1/foo>
Position: First
Unfortunately, several features of the semantics of MOVE make it
unsuitable for changing the position of a collection member in the
collection's ordering. First, [WebDAV] defines MOVE as logically
equivalent to a copy followed by a delete of the source resource. This
definition makes it impossible to MOVE a resource to a destination URL
that is the same as the source URL. The resource would be deleted
rather than moved. Second, [WebDAV] states that when moving a resource
to a destination where a resource already exists, the Overwrite header
must be "T", and in this case the server must DELETE the resource at the
destination before performing the MOVE. Again, this makes it impossible
to MOVE a resource to the same location. Finally, [WebDAV] states that
locks are lost on a MOVE, an outcome that seems undesirable in this
case.
6 Headers
6.1 Ref-Target Entity Header
Ref-Target = "Ref-Target" ":" 1#([hop-count ";"] Coded-url)
hop-count = 1*DIGIT
Coded-url is defined in [WebDAV], Section 8.4.
In general, the Ref-Target header has the simpler form:
Ref-Target = "Ref-Target" ":" Coded-url
The more complicated syntax is provided only for use in responses
involving chains of direct references.
The Ref-Target header is used with MKREF requests to identify the target
resource of the new referential resource being created. It is a
REQUIRED header in MKREF requests. When used with a MKREF request, its
value is simply a Coded-url, and only a single value is allowed. For an
example, see Section 4.3.3.
Servers MUST include the Ref-Target header in responses to the following
types of requests:
Reference Type | No-Passthrough | Method
direct or redirect | Present | GET, HEAD
direct | Absent | All except MKREF, UNLOCK
redirect | Absent | COPY, LOCK, DELETE, MOVE
The only case where multiple values of Ref-Target are allowed is when it
is included in a response for a reference that is part of a chain of
direct references. In this case, the response MUST include a value of
Ref-Target for each reference in the chain. Each value MUST include a
hop-count, starting with 0, indicating which reference in the chain that
Ref-Target belongs to. For an example, see Section 4.14.
The Coded-url in a Ref-Target header MAY be a relative URI. If it is a
relative URI, the base URI to be used for resolving it to absolute form
has as its scheme component "http", as its authority component the value
of the Host: header from the request, and as its path component the
request-URI from the request. See [URI] Section 5 for a discussion of
relative URI references and how to resolve them.
6.1.1 Example: Resolving a Relative URI in Ref-Target
Request:
PUT /north/inuvik HTTP/1.1
Host: www.somehost.edu
Content-Type: image/gif
Content-Length: nnnnnn
<body> Consider a collection /coll-1/ with bindings ordered as follows:
Response: nunavut.map
nunavut.img
baffin.map
baffin.desc
baffin.img
iqaluit.map
nunavut.desc
iqaluit.img
iqaluit.desc
HTTP/1.1 200 ok >> Request:
Ref-Type: direct
Ref-Target: mapcollection/inuvik.gif
In this example, the base URI is http://www.somehost.edu/north/inuvik. ORDERPATCH /coll-1/ HTTP/1.1
Host: www.nunanet.com
Content-Type: text/xml
Content-Length: xxx
The relative URI in Ref-Target resolves to the absolute URI <?xml version="1.0" ?>
http://www.somehost.edu/north/mapcollection/inuvik.gif. <d:order xmlns:d="DAV:">
<d:ordermember>
<d:href>nunavut.desc</d:href>
<d:position>
<d:after>
<d:href>nunavut.map</d:href>
</d:after>
</d:position>
</d:ordermember>
<d:ordermember>
<d:href>iqaluit.map</d:href>
<d:position>
<d:after>
<d:href>pangnirtung.img</d:href>
</d:after>
</d:position>
</d:ordermember>
</d:order>
6.2 Ref-Type Entity Header >> Response:
Ref-Type = "Ref-Type" ":" ("DAV:direct" | "DAV:redirect") HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxx
The Ref-Type header is defined to distinguish between direct and <?xml version="1.0" ?>
redirect references. The possible values of this header are DAV:direct <d:multistatus xmlns:d="DAV:">
and DAV:redirect. If the header is not present on a MKREF request, the <d:response>
server MUST treat the request as if it has a Ref-Type header with the <d:href>http://www.nunanet.com/coll-1/nunavut.desc</d:href>
value DAV:redirect. <d:status>HTTP/1.1 424 Failed Dependency</d:status>
</d:response>
<d:response>
<d:href>http://www.nunanet.com/coll-1/iqaluit.map</d:href>
<d:status>HTTP/1.1 409 Conflict</d:status>
<d:responsedescription>pangnirtung.img is not a collection
member.</d:responsedescription>
</d:response>
</d:multistatus>
Servers MUST include the Ref-Target header in every response to a In this example, the client attempted to position iqaluit.map after a
request whose request-URI identifies a reference, with the exception of binding that is not contained in the collection /coll-1/. The server
responses to MKREF requests. responded to this client error with a 409 (Conflict) status code.
Because ORDERPATCH is an atomic method, the request to reposition
nunavut.desc (which would otherwise have succeeded) failed with a 424
(Failed Dependency) status code.
6.3 Ref-Integrity Request Header 6 Headers
Ref-Integrity = "Ref-Integrity" ":" ("do-not-enforce" | "enforce" | 6.1 All-Bindings Request Header
extend)
extend = 1#CHAR
The Ref-Integrity header is defined primarily to allow future support All-Bindings = "All-Bindings" ":"
for strong references. It specifies whether the server should enforce
referential integrity for a referential resource being created with
MKREF.
The value "do-not-enforce" means that the server MUST NOT enforce The All-Bindings request header may be used with DELETE requests to
referential integrity for the newly created reference. A client might instruct the server to remove all bindings to the resource identified by
use this value if, for example, it wanted to populate a collection with the Request-URI.
references before their content was made available on the Web.
The value "enforce" means that the server MUST enforce referential 6.2 Ref-Target Entity Header
integrity for the newly created reference, but does not constrain the
server to use any particular policy for enforcing referential integrity.
It is beyond the scope of this specification to define precisely the
meaning of referential integrity or to enumerate any set of policies
that might be considered compliant.
Clients and servers may use other values of the Ref-Integrity header by Ref-Target = "Ref-Target" ":" (absoluteURI | relativeURI)
private agreement, to specify more precisely the desired policy for
enforcing referential integrity. If a server receives an extension
value that it does not understand, it MUST fail the request.
If the Ref-Integrity header is not present on a MKREF request, the The Ref-Target header is defined primarily for use with MKREF requests
server MAY enforce referential integrity or not, and if it does enforce to identify the target resource of the new redirect reference being
referential integrity, it MAY follow any policy it chooses. created.
6.4 No-Passthrough Request Header 6.3 Resource-Type Entity Header
No-Passthrough = "No-Passthrough" ":" Resource-Type = "Resource-Type" ":" ("DAV:redirectref" |
ext-resource-type)
ext-resource-type = coded-URL
The optional No-Passthrough header can be used on any request to a The Resource-Type header is defined primarily for use in 302 responses,
reference except POST. For a direct reference, if the No-Passthrough to allow reference-aware clients to distinguish between HTTP 1.1
redirects and 302 responses for redirect references (see Sections 4.1,
and 4.3.7). The possible values of this header are DAV:redirectref, and
ext-resource-type. The ext-resource-type production is provided for
extensibility.
header is present, the request MUST be applied to the reference itself 6.4 Passthrough Request Header
rather than to its target. For a redirect reference, if the No-
Passthrough header is present, the request MUST be applied to the
reference itself, and a 302 response MUST NOT be returned. If the No-
Passthrough header is used on a request to any other sort of resource
besides a reference, the server SHOULD ignore it. If the No-Passthrough
header is used with a POST request to a reference, the server MUST
respond with a 400 (Bad Request).
The No-Passthrough header can be used with PROPFIND requests on Passthrough = "Passthrough" ":" ("T" | "F")
collections with Depth = infinity. When it is used in this way, the
server MUST return the properties of any redirect references in the
collection, and not return 302 (Moved Temporarily) status codes for
them. It MUST also return the properties of any direct references in
the collection (not the properties of their targets), and it MUST NOT
follow any direct references to collections into their target
collections.
The No-Passthrough header can be used with LOCK requests on collections The optional Passthrough header can be used on any request to a redirect
with Depth = infinity. When it is used in this way, the server MUST reference. If the Passthrough header has the value "F", the request
lock any redirect references in the collection, just as it would if the MUST be applied to the reference itself, and a 302 response MUST NOT be
No-Passthrough header were absent. It MUST also lock any direct returned. If the Passthrough header has the value "T", a 302 response
references in the collection (not their target resources), and it MUST MUST be returned, with the URI of the target resource in the Location
NOT follow any direct references to collections into their target header and the Resource-Type header with a value "DAV:redirectref".
collections.
The No-Passthrough header can be used with COPY requests on collections If the Passthrough header is used on a request to any other sort of
with Depth > 0. When it is used in this way, the server MUST copy any resource besides a reference, the server SHOULD ignore it. If the
redirect references in the collection, just as it would if the No- Passthrough header with the value "F" appears in a POST or ORDERPATCH
Passthrough header were absent. It MUST also copy any direct references request to a reference, the server MUST respond with a 400 (Bad
in the collection (not their target resources), and it MUST NOT follow Request).
any direct references to collections into their target collections.
6.5 Ordered Entity Header 6.5 Ordered Entity Header
Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | absoluteURI)
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. That is, "DAV:unordered" indicates that the collection is not ordered. A value of
the client cannot depend on the repeatability of the ordering of results
from a PROPFIND request. A Coded-url value indicates that the collection
is ordered, and identifies the semantics of the ordering, allowing a
human user or software package to insert new collection members into the
ordering intelligently. The Coded-url MAY point to a resource that
contains a definition of the semantics of the ordering. 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. semantics of the ordering is not being advertised. Any other
absoluteURI value indicates that the collection is ordered, and
If the Ordered header is not present on a MKCOL request, the server MUST identifies the semantics of the ordering.
treat the request as if it had an Ordered header with the value
"DAV:unordered".
6.6 Position Request Header 6.6 Position Request Header
Position = "Position" ":" ("First" | "Last" | Position = "Position" ":" ("First" | "Last" |
(("Before" | "After") Coded-url)) (("Before" | "After") Generic-Coded-url))
Generic-Coded-url = "<" (absoluteURI | relativeURI) ">"
The Position header may be used with any method that adds a member to a absoluteURI and relativeURI are defined in [URI].
collection to tell the server where in the collection ordering to
position the new member being added to the collection. It may be used
for both ordinary and referential members.
If the Coded-url is a relative URL, it is interpreted relative to the
collection to which the new member is being added.
If the Position request header is not used, then:
If the request is replacing an existing resource, the server MUST
preserve the present ordering.
If the request is adding a new member to the collection, the server MUST
append the new member to the end of the ordering (if the collection is
ordered).
7 Properties
7.1 reftarget Property The Position header may be used with any method that adds a binding to a
Name: reftarget collection with a client-maintained ordering, to tell the server where
Namespace: DAV: in the collection ordering to position the new binding being added to
Purpose: A REQUIRED property of referential resources that provides the collection.
an efficient way for clients to discover the URI of the
target resource. This is a read-only property, whose value
can only be set by using the Ref-Target header with a MKREF
request.
Value: URI of the target resource. This value MAY be a relative
URI. The reftarget property can occur in the entity bodies
of responses to a variety of requests. It always occurs in
the context of a Multi-Status response, inside a
DAV:response element that has a single DAV:href element.
The value of this DAV:href element serves as the base URI
for resolving a relative URI in DAV:reftarget. (The value
of DAV:href may itself be relative, in which case it must be
resolved first in order to serve as the base URI for the
relative URI in DAV:reftarget.) See [URI] Section 5 for a
discussion of relative URI references and how to resolve
them.
<!ELEMENT reftarget href> If the Generic-Coded-url is a relative URL, it is interpreted relative
to the collection to which the new binding is being added.
7.1.1 Example: Resolving a Relative URI in the DAV:reftarget The server MUST insert the new binding into the ordering at the location
specified in the Position header, if one is present (and if the
collection has a client-maintained ordering).
Request: The "First" keyword indicates the new binding is put in the beginning
position in the collection's ordering, while "Last" indicates the new
binding is put in the final position in the collection's ordering. The
"Before" keyword indicates the new binding is added to the collection's
ordering immediately prior to the position of the binding identified in
the Generic-Coded-url. Likewise, the "After" keyword indicates the new
binding is added to the collection's ordering immediately following the
position of the binding identified in the Generic-Coded-url.
PROPFIND /geog/ HTTP/1.1 If the request is replacing an existing resource, and the Position
Host: www.xxsvr.com header is present, the server MUST remove the binding from its previous
No-Passthrough: position, and then insert it at the requested position.
Depth: 1
Content-Type: text/xml
Content-Length: nnn If the Position request header is not used when adding a binding to a
collection with a client-maintained ordering, then:
<?xml version="1.0" ?> o If the request is replacing an existing resource, the server MUST
<D:propfind xmlns:D="DAV:"> preserve the present ordering.
<D:prop>
<D:resourcetype/>
<D:reftype/>
<D:reftarget/>
</D:prop>
</D:propfind>
Response: 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.
HTTP/1.1 207 Multi-Status If an attempt is made to use the Position header on a collection that is
Content-Type: text/xml unordered or that has a server-maintained ordering, the server MUST fail
Content-Length: nnn the request with a 409 (Conflict) status code.
<?xml version="1/0" ?> 7 Status Codes
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/geog/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>collection</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 ok</D:status>
</D:propstat>
<D:propstat>
<D:prop><D:reftype/> <D:reftarget/>/D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/geog/stats.html</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>reference</D:resourcetype>
<D:reftype>direct</D:reftype>
<D:reftarget>statistics/population/1997.html</D:reftarget>
</D:prop>
<D:status>HTTP/1.1 200 ok</D:status>
</D:propstat>
</D:response>
</D:multistatus>
In this example, the relative URI statistics/population/1997.html is 7.1 506 Loop Detected
returned as the value of reftarget for the reference identified by href
/geog/stats.html. The href is itself a relative URI, which resolves to
http://www.xxsrv.com/geog/stats.html. This is the base URI for
resolving the relative URI in reftarget. The absolute URI of reftarget
is http://www.xxsrv.com/geog/statistics/population/1997.html.
7.2 refintegrity Property The 506 (Loop Detected) status code indicates that the server detected
an infinite loop while processing a request with "Depth: infinity".
Name: refintegrity 7.2 425 Unordered Collection
Namespace: DAV: The 425 (Unordered Collection) status code indicates that the client
Purpose: A REQUIRED property of a referential resource that indicates attempted to set the position of an internal collection member in an
whether the server enforces referential integrity for that unordered collection or in a collection with a server-maintained
reference. The refintegrity property is defined to allow ordering.
future support for strong references. The only value
currently defined for refintegrity is weak, which means that
the server does not enforce referential integrity for the
reference. Although a server may assign another value to
identify its policy for enforcing referential integrity for
the reference, it cannot count on clients understanding such
extension values. This is a readonly property.
Value: weak or an extension value
<!ELEMENT refintegrity (weak | ANY)> 8 Properties
7.3 reftype Property 8.1 reftarget Property
Name: reftype Name: reftarget
Namespace: DAV: Namespace: DAV:
Purpose: A required property of a referential resource that Purpose: A property of redirect references that provides an efficient
identifies the reference as direct or redirect. This is a way for clients to discover the URI of the target resource.
read-only property, whose value can only be set by using This is a read-only property, whose value can only be set by
the Ref-Type header with a MKREF request. using the Ref-Target header with a MKREF request.
Value: direct | redirect Value: URI of the target resource. This value MAY be a relative
URI. The reftarget property can occur in the entity bodies
of responses to PROPFIND requests.
<!ELEMENT reftype (direct | redirect)> <!ELEMENT reftarget (#PCDATA)>
7.4 location Property 8.2 location Property
Name: location Name: location
Namespace: DAV: Namespace: DAV:
Purpose: For use with 302 (Moved Temporarily) response codes in Purpose: For use with 302 (Moved Temporarily) response codes in
Multi-Status responses. It contains the absolute URI of the Multi-Status responses. It contains the absolute URI of the
temporary location of the resource. In the context of temporary location of the resource. In the context of
redirect references, this value is the absolute URI of the redirect references, this value is the absolute URI of the
target resource. It is analogous to the Location header in target resource. It is analogous to the Location header in
HTTP 302 responses defined in [HTTP] Section 10.3.3 "302 HTTP 302 responses defined in [HTTP] Section 10.3.3 "302
Moved Temporarily." Including the location property in a Moved Temporarily." Including the location property in a
Multi-Status response requires an extension to the syntax of Multi-Status response requires an extension to the syntax of
the DAV:response element defined in [WebDAV], which is the DAV:response element defined in [WebDAV], which is
defined in Section 9 below. This property is not expected defined in Section 9 below. This property is not expected
to be stored on the reference. It is modeled as a property to be stored on the reference. It is modeled as a property
only so that it can be returned inside a DAV:prop element in only so that it can be returned inside a DAV:prop element in
a Multi-Status response. a Multi-Status response.
Value: href containing the absolute URI of the target resource. Value: href containing the absolute URI of the target resource.
<!ELEMENT location href > <!ELEMENT location href >
7.5 references Property 8.3 bindings Property
Name: references Name: bindings
Namespace: DAV: Namespace: DAV:
Purpose: Enables clients to discover, for any target resource, what Purpose: Enables clients to discover, for any resource, what bindings
references point to it and what collections contain it by point to it and what collections contain those bindings.
reference. This is an optional property. If present, it is This is an optional property. If present, it is a read-only
a read-only property, maintained by the server. property, maintained by the server.
Value: List of the URIs of the references that point to the target Value: List of href / segment pairs for all of the bindings that
resource. associate URI segments with the resource. The href is an
absolute URI for one URI mapping of the collection
containing the binding. The segment is the URI segment that
identifies the binding within that collection. If a binding
belongs to a collection that has multiple URI mappings, only
one URI mapping for that collection should be reported.
<!ELEMENT references (href*)> <!ELEMENT bindings ((href, segment)*)>
7.6 orderingtype Property 8.4 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. understand where to position them in the ordering.
Value: unordered for an unordered collection, or a URI that Value: unordered for an unordered collection, or a URI that
uniquely identifies the semantics of the collection's uniquely identifies the semantics of the collection's
ordering. The URI MAY point to a definition of the ordering ordering. The value custom indicates that the collection is
semantics. The value custom may be used for a collection ordered, but the semantics are not being advertised.
that is to be ordered, but for which the semantics are not
being advertised.
<!ELEMENT orderingtype (arbitrary | custom | href) >
8 XML Elements
8.1 reference XML Element
Name: reference
Namespace: DAV:
Purpose: A new value of the DAV:resourcetype property that identifies
its resource as a referential resource. The
DAV:resourcetype property of a referential resource MUST
have this value.
Value: EMPTY
<!ELEMENT reference EMPTY >
8.2 direct XML Element
Name: direct <!ELEMENT orderingtype (unordered | custom | href) >
Namespace: DAV:
Purpose: A value for the DAV:reftype property that identifies its
resource as a direct reference.
Value: EMPTY
<!ELEMENT direct EMPTY > 9 XML Elements
8.3 redirect XML Element 9.1 redirectref XML Element
Name: redirect Name: redirectref
Namespace: DAV: Namespace: DAV:
Purpose: A value for the DAV:reftype property that identifies its Purpose: Used as the value of the DAV:resourcetype property to
resource as a redirect reference. specify that the resource type is a redirect reference.
Value: EMPTY
<!ELEMENT redirect EMPTY > <!ELEMENT redirectref EMPTY >
8.4 weak XML Element 9.2 segment XML Element
Name: weak Name: segment
Namespace: DAV: Namespace: DAV:
Purpose: A value of the DAV:refintegrity property. It means that the Purpose: The segment that names a binding, used in the DAV:bindings
server does not enforce referential integrity for the property.
reference to which the property belongs. Value: segment ; as defined in section 3.3 of [URI].
Value: EMPTY
<!ELEMENT weak EMPTY > <!ELEMENT segment (#PCDATA)>
8.5 unordered XML Element 9.3 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.
Value: EMPTY
<!ELEMENT unordered EMPTY > <!ELEMENT unordered EMPTY >
8.6 custom XML Element 9.4 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.
Value: EMPTY
<!ELEMENT custom EMPTY > <!ELEMENT custom EMPTY >
8.7 order XML Element 9.5 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 ordering. to be made in a collection ordering.
Value: A description of the new positions of collection members in Value: A description of the new positions of the bindings a
the collection's ordering. collection contains in its ordering.
<!ELEMENT order (ordermember+) > <!ELEMENT order (ordermember+) >
8.8 ordermember XML Element 9.6 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 collection member in the collection's position of a single binding in the collection's ordering.
ordering. Value: An href containing a binding's path segment, and a
Value: An href containing a relative URI, and a description of its description of its new position in the ordering. The href
new position in the ordering. The href XML element is XML element is defined in [WebDAV], Section 11.3.
defined in [WebDAV], Section 11.3.
<!ELEMENT ordermember (href, position) > <!ELEMENT ordermember (href, position) >
8.9 position XML Element 9.7 position XML Element
Name: position Name: position
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the member 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 position in a collection's ordering of one of the bindings
collection's members. it 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,
before some other member of the collection, or after some immediately before some other binding, or immediately after
other member of the collection. some other binding.
<!ELEMENT position (first | last | before | after)> <!ELEMENT position (first | last | before | after)>
8.10 first XML Element 9.8 first XML Element
Name: first Name: first
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the position XML element. Describes the Purpose: Occurs in the position XML element. Specifies that the
collection member's position as first in the collection's binding should be placed first in the collection's ordering.
ordering.
Value: EMPTY
<!ELEMENT first EMPTY > <!ELEMENT first EMPTY >
8.11 last XML Element 9.9 last XML Element
Name: last Name: last
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the position XML element. Describes the Purpose: Occurs in the position XML element. Specifies that the
collection member's position as last in the collection's binding should be placed last in the collection's ordering.
ordering.
Value: EMPTY
<!ELEMENT last EMPTY > <!ELEMENT last EMPTY >
8.12 before XML Element 9.10 before XML Element
Name: before Name: before
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the position XML element. Describes the Purpose: Occurs in the position XML element. Specifies that the
collection member's position as coming before some other binding should be placed immediately before the binding in
collection member in the collection's ordering. the enclosed href XML element in the collection's ordering.
Value: href of the member it precedes in the ordering Value: href of the member it precedes in the ordering
<!ELEMENT before href > <!ELEMENT before href >
8.13 after XML Element 9.11 after XML Element
Name: after Name: after
Namespace: DAV: Namespace: DAV:
Purpose: Occurs in the position XML element. Describes the Purpose: Occurs in the position XML element. Specifies that the
collection member's position as coming after some other binding should be placed immediately after the binding in
collection member in the collection's ordering. the enclosed href XML element in the collection's ordering.
Value: href of the member it follows in the ordering Value: href of the member it follows in the ordering
<!ELEMENT after href > <!ELEMENT after href >
9 Extensions to the DAV:response XML Element for Multi-Status Responses 9.12 options XML Element
As described in Sections 4.5 and 4.6, the DAV:location property and the 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)+ >
9.13 orderingoptions XML Element
Name: orderingoptions
Namespace: DAV:
Purpose: Used in OPTIONS requests to ask for the list of server-
maintained orderings that can be supported at the request-
URI. Used in OPTIONS responses to provide that information.
These values can be used in the Ordered header or the
DAV:orderingtype property to request that a particular
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) >
10 Extensions to the DAV:response XML Element for Multi-Status Responses
As described in Sections 4.6 and 4.9, the DAV:location property and the
DAV:reftype property may be returned in the DAV:response element of a DAV:reftype property may be returned in the DAV:response element of a
207 Multi-Status response, to allow clients to resubmit their requests 207 Multi-Status response, to allow clients to resubmit their requests
to the target resource of a redirect reference.
As described in Section 4.13, the DAV:reftype and DAV:reftarget to the target resource of a redirect reference.
properties may be returned in the DAV:response element of a 207 Multi-
Status response, to indicate that a problem is not with a direct
reference, but with its target resource.
Whenever these properties are included in a Multi-Status response, they Whenever these properties are included in a Multi-Status response, they
will be placed in a DAV:prop element associated with the href to which are placed in a DAV:prop element associated with the href to which they
they apply. This structure provides a framework for future extensions apply. This structure provides a framework for future extensions by
by other standards that may need to include additional properties in other standards that may need to include additional properties in their
their responses. responses.
Consequently, the definition of the DAV:response XML element changes to Consequently, the definition of the DAV:response XML element changes to
the following: the following:
<!ELEMENT response (href, ((href*, status, prop?) | (propstat+)), <!ELEMENT response (href, ((href*, status, prop?) | (propstat+)),
responsedescription?) > responsedescription?) >
10 Capability Discovery 11 Capability Discovery
10.1 Using OPTIONS 11.1 Compliance Classes
Since referencing and ordering are independent capabilities, a resource This specification defines OPTIONAL extensions to [WebDAV]. Since
MAY support either or both. A resource that provides referencing MUST resource sharing and ordering are independent capabilities, a resource
support redirect references, and MAY in addition support direct MAY support either, both, or neither of these capabilities. A resource
that provides resource sharing MUST support both bindings and redirect
references. A response to an OPTIONS request MUST indicate which of references. A response to an OPTIONS request MUST indicate which of
these capabilities the resource supports. these capabilities the resource supports.
This specification defines two new methods: MKREF in support of This specification defines three new methods: BIND and MKREF in support
referencing, and ORDERPATCH in support of ordering. The response MUST of shared resources, and ORDERPATCH in support of ordering. The
indicate which of these methods the resource allows. In addition, the response MUST indicate which of these methods the resource allows. In
response MUST include the DAV header, as described in Sections 9.1 and addition, the response MUST include the DAV header, as described in
15 of [WebDAV]. Three new compliance classes are defined here for use Sections 9.1 and 15 of [WebDAV]. Two new compliance classes are defined
with the DAV header: basicref, directref, and orderedcoll. here for use with the DAV header: sharing and orderedcoll.
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 immediate member including orderedcoll, the resource indicates that its bindings can be
URIs can be ordered. It implies nothing about whether any collections ordered. It implies nothing about whether any collections identified by
its internal member URIs can be ordered.
identified by its member URIs can be ordered.
When responding to an OPTIONS request, any type of resource can include When responding to an OPTIONS request, any type of resource can include
basicref or directref in the value of the DAV header. Including sharing in the value of the DAV header. Including sharing indicates
basicref indicates that the server permits a redirect reference at the that the server permits a redirect reference or a binding at the request
request URI. Including directref indicates that the server permits a URI.
direct reference at the request URI.
10.2 Example: Capability Discovery 11.2 Example: Discovery of Compliance Classes
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
Connection: close Connection: close
Accept-Ranges: none Accept-Ranges: none
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL,
PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, ORDERPATCH PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, ORDERPATCH
Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL,
PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, ORDERPATCH PROPFIND, PROPPATCH, LOCK, UNLOCK, BIND, MKREF, ORDERPATCH
DAV: 1, 2, basicref, directref, orderedcoll DAV: 1, 2, sharing, orderedcoll
This response indicates that the resource /somecollection/ is level 1 The DAV header in the response indicates that the resource
and level 2 compliant, as defined in [WebDAV]. In addition, /somecollection/ is level 1 and level 2 compliant, as defined in
/somecollection/ supports ordering and is in a part of the server [WebDAV]. In addition, /somecollection/ supports ordering and resource
namespace that allows creation of redirect and direct references. (In sharing. The Allow header indicates that BIND and ORDERPATCH requests
light of the semantics of MKREF, the resource currently at can be submitted to /somecollection/. Since a redirect reference is not
/somecollection/ would have to be deleted before a reference could be a collection, a MKREF request with /somecollection/ as its Request-URI
created at that URI.) would fail, but the Public header shows that other Request-URIs on the
server do support MKREF.
11 Dependencies on Other Specifications 11.3 Additional Advanced Collections Capabilities
TBD Clients may need detailed information about specific areas of advanced
collections 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 5.2, 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.
11.4 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, BIND, 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 and resource sharing. 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.
12 Security Considerations 12 Security Considerations
This section is provided to detail issues concerning security This section is provided to detail issues concerning security
implications of which WebDAV applications need to be aware. implications of which WebDAV applications need to be aware.
All of the security considerations of HTTP/1.1 and the base WebDAV All of the security considerations of HTTP/1.1 and the WebDAV
protocol also apply to WebDAV collections. In addition, referential Distributed Authoring Protocol specification also apply to WebDAV
resources and ordered collections introduce several new security collections. In addition, resource sharing and ordered collections
concerns and increase the risk of some existing threats. These issues introduce several new security concerns and increase the risk of some
are detailed below. existing threats. These issues are detailed below.
12.1 Privacy Concerns 12.1 Privacy Concerns
By creating references on a trusted server, it is possible for a hostile By creating redirect references on a trusted server, it is possible for
agent to induce users to send private information to a target on a a hostile agent to induce users to send private information to a target
different server. This risk is mitigated somewhat for redirect on a different server. This risk is mitigated somewhat, since clients
are required to notify the user of the redirection for any request other
than GET or HEAD. (See [HTTP], Section 10.3.3 Moved Temporarily.)
references, since clients are required to notify the user of the The same risk exists for bindings, although it is less likely that
redirection for any request other than GET or HEAD. (See [HTTP], Section servers will support cross-server bindings.
10.3.3 Moved Temporarily.) For direct references, clients can determine
the resource type, reference type, and target location before sending a
request, but are not required to notify users if the target is on
another server.
12.2 Redirect Loops 12.2 Redirect Loops
Although redirect loops were already possible in HTTP 1.1, the Although redirect loops were already possible in HTTP 1.1, the
introduction of referential resources creates a new avenue for clients introduction of the BIND and MKREF methods creates a new avenue for
to create loops accidentally or maliciously. If the referential clients to create loops accidentally or maliciously. If the binding or
resource and its target are on the same server, the server may be able reference and its target are on the same server, the server may be able
to detect MKREF requests that would create loops. See also [HTTP], to detect MKREF and BIND requests that would create loops. See also
Section 10.3 "Redirection 3xx." [HTTP], Section 10.3 "Redirection 3xx." Servers are required to detect
loops caused by bindings to collections during the processing of any
requests with "Depth: infinity".
12.3 References and Denial of Service 12.3 Redirect References, Bindings, and Denial of Service
Denial of service attacks were already possible by posting URLs that Denial of service attacks were already possible by posting URLs that
were intended for limited use at heavily used Web sites. The were intended for limited use at heavily used Web sites. The
introduction of referential resources creates a new avenue for similar
denial of service attacks. Clients can now create references at heavily
used sites to target locations that were not designed for heavy usage.
12.4 References May Reveal Private Locations introduction of BIND and MKREF creates a new avenue for similar denial
of service attacks. Clients can now create bindings and redirect
references at heavily used sites to target locations that were not
designed for heavy usage.
There are several ways that the referencing mechanisms described here 12.4 Private Locations May Be Revealed
may reveal information about directory structures. First, the
DAV:reftarget property of every reference contains the URI of the target There are several ways that redirect references may reveal information
resource. Anyone who has access to the reference can discover the about directory structures. First, the DAV:reftarget property of every
directory path that leads to the target resource. The owner of the redirect reference contains the URI of the target resource. Anyone who
target resource may have wanted to limit knowledge of this directory has access to the reference can discover the directory path that leads
structure. to the target resource. The owner of the target resource may have
wanted to limit knowledge of this directory structure.
Sufficiently powerful access control mechanisms can control this risk to Sufficiently powerful access control mechanisms can control this risk to
some extent. Property-level access control could prevent users from some extent. Property-level access control could prevent users from
examining the DAV:reftarget property. (The Ref-Target header, which is examining the DAV:reftarget property. (The Ref-Target and Location
returned in most responses to requests on direct references, reveals the headers, which are returned in some responses to requests on redirect
same information, however.) In some environments, the owner of a references, reveal the same information, however.) In some
resource might be able to use access control to prevent others from environments, the owner of a resource might be able to use access
creating references to that resource. control to prevent others from creating references to that resource.
Second, although this specification does not require servers to maintain
referential integrity, it does not prevent them from doing so. If a
server updates a reference’s DAV:reftarget property when its target
resource is moved, there is the risk that a private location will be
revealed in the new value of DAV:reftarget. Clients can avoid this risk
by doing a COPY followed by a DELETE rather than a MOVE.
Finally, if backpointers are maintained on the target resource, the In addition, if backpointers are maintained on the target resource, the
owners of references face these same risks. The directory structures owners of bindings face these same risks. The directory structures
where references are located are revealed to anyone who has access to where bindings are located are revealed to anyone who has access to the
the DAV:references property on a target resource. Moving a reference DAV:bindings property on a target resource. Moving a binding may reveal
may reveal its new location to anyone with access to DAV:references on its new location to anyone with access to DAV:bindings on its target
its target resource. resource.
12.5 DAV:references and Denial of Service 12.5 DAV:bindings and Denial of Service
If the server maintains the DAV:references property in response to If the server maintains the DAV:bindings property in response to
references created in other administrative domains, it is exposed to bindings created in other administrative domains, it is exposed to
hostile attempts to make it devote resources to adding references to the hostile attempts to make it devote resources to adding bindings to the
list. list.
12.6 DAV:references and Malicious Deletion of Resources 12.6 Denial of Service and DAV:orderingtype
Servers that support the DAV:references property should insure that
clients cannot create editable properties with the name DAV:references.
An editable DAV:references property would constitute a security risk on
servers that enforce referential integrity by deleting references when
their target is deleted. These servers could be tricked into deleting a
resource by listing it in the DAV:references property of some target
resource.
12.7 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. semantics at the location specified by DAV:orderingtype. In addition,
Section 5.2 discourages clients from looking up the semantics at that
location.
13 Internationalization Considerations 13 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 [Alvestrand].
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
skipping to change at line 2675 skipping to change at line 2746
implementors, see [WebDAV]. implementors, see [WebDAV].
14 IANA Considerations 14 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.
15 Copyright 15 Copyright
To be supplied. To be supplied by the RFC Editor.
16 Intellectual Property 16 Intellectual Property
To be supplied. To be supplied by the RFC Editor.
17 Acknowledgements 17 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, Rajiv Carter, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Mark Day,
Dulepet, David Durand, Roy Fielding, Yaron Goland, Fred Hitt, Alex Rajiv Dulepet, David Durand, Roy Fielding, Yaron Goland, Fred Hitt, Alex
Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare,
Daniel LaLiberte, Steve Martin, Surendra Koduru Reddy, Sam Ruby, Bradley Daniel LaLiberte, Steve Martin, Larry Masinter, Jeff McAffer, Surendra
Sergeant, Nick Shelness, John Stracke, John Tigue, John Turner, and Koduru Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness, John
others. Stracke, John Tigue, John Turner, and others.
18 References 18 References
18.1 Normative References 18.1 Normative References
[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
skipping to change at line 2734 skipping to change at line 2805
Internet Draft, work in progress. Xerox. February, 1999. Internet Draft, work in progress. Xerox. February, 1999.
19 Authors' Addresses 19 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
J. Davis E. J. Whitehead, Jr.
Xerox Corporation Dept. of Information and Computer Science
3333 Coyote Hill Road University of California, Irvine
Palo Alto, CA 94304 Irvine, CA 92697-3425
Email: jdavis@parc.xerox.com Email: ejw@ics.uci.edu
T. Chihaya J. Davis
DataChannel, Inc. CourseNet Systems
155 108th Ave. N.E., Suite 400 170 Capp Street
Bellevue, WA 98004 San Francisco, CA 94110
Email: Tyson@DataChannel.com Email: jrd3@alum.mit.edu
G. Clemm G. Clemm
Rational Software Corporation Rational Software Corporation
20 Maguire Road 20 Maguire Road
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
E.J. Whitehead Jr. J. Crawford
Dept. of Information and Computer Science
University of California, Irvine
Irvine, CA 92697-3425
Email: ejw@ics.uci.edu
A. Babich IBM
FileNet Corporation Email: ccjason@us.ibm.com
3565 Harbor Boulevard
Costa Mesa, CA 92626-1420 T. Chihaya
Email: ababich@filenet.com DataChannel, Inc.
155 108th Ave. N.E., Suite 400
Bellevue, WA 98004
Email: Tyson@DataChannel.com
20 Appendices 20 Appendices
20.1 Appendix 1: Extensions to the WebDAV Document Type Definition 20.1 Appendix 1: Extensions to the WebDAV Document Type Definition
<!--============= XML Elements from Section 8 =======================--> <!--============= XML Elements from Section 8 ================-->
<!ELEMENT reference EMPTY > <!ELEMENT redirectref EMPTY >
<!ELEMENT direct EMPTY > <!ELEMENT segment (#PCDATA)>
<!ELEMENT redirect EMPTY >
<!ELEMENT weak EMPTY >
<!ELEMENT location href>
<!ELEMENT unordered EMPTY > <!ELEMENT unordered EMPTY >
<!ELEMENT custom EMPTY > <!ELEMENT custom EMPTY >
<!ELEMENT order (ordermember+) > <!ELEMENT order (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 href >
<!ELEMENT after href > <!ELEMENT after href >
<!ELEMENT options (refintegrityoptions | orderingoptions)+ >
<!ELEMENT orderingoptions ( (#PCDATA)+ | EMPTY) >
<!--============= Property Elements from Section 7 ==================--> <!--============= Property Elements from Section 7 ==================-->
<!ELEMENT reftarget href> <!ELEMENT reftarget (#PCDATA)>
<!ELEMENT refintegrity (weak | ANY)> <!ELEMENT location href>
<!ELEMENT reftype (direct | redirect)> <!ELEMENT bindings ((href, segment)*)>
<!ELEMENT references (href*)>
<!ELEMENT orderingtype (arbitrary | custom | href) > <!ELEMENT orderingtype (arbitrary | custom | href) >
<!--====== Changes to the DAV:response Element from Section 9 ====--> <!--====== Changes to the DAV:response Element from Section 9 ====-->
<!ELEMENT response (href, ((href*, status, prop?) | (propstat+)), <!ELEMENT response (href, ((href*, status, prop?) | (propstat+)),
responsedescription?) > responsedescription?) >
20.2 Appendix 2: Summary of Referencing Headers Required in Responses Expires December 18, 1999
This section summarizes the rules that determine which referencing
headers are included in responses to requests on references. The
normative statements that are summarized here can be found in Sections
4.5 - 4.10, 4.13, 4.14, 6.1, and 6.2.
Reference Type | No-Passthrough | Method | Headers Included in
| | | Response
both |Present / Absent| All except | Ref-Type
| | MKREF, UNLOCK |
both |Present | GET, HEAD | Ref-Target
direct |Absent | All except | Ref-Target
| | MKREF, UNLOCK |
redirect |Absent | COPY, LOCK, | Ref-Target
| | DELETE, MOVE |
o Every response to a request on a reference includes the Ref-Type
header, so that the client knows that it was operating on a
reference, and can understand the behavior of the reference.
o Since [HTTP] requires responses to GET and HEAD to include all entity
headers, Ref-Target is included in all responses to GET and HEAD
requests on references with the No-Passthrough header.
o For all other requests with the No-Passthrough header, the client is
aware that it is operating on the reference rather than the target,
so the Ref-Target header is OPTIONAL.
o When the No-Passthrough header is absent from a request on a direct
reference, the target resource is affected. Consequently, the Ref-
Target header is required. This allows the client to tell what
resource was affected by the operation. The exceptions are MKREF,
since the client knows the value of Ref-Target that it sent in the
request, and UNLOCK, which affects just the resources that were
locked with the same lock token.
o When the No-Passthrough header is absent from a request on a direct
reference, in most cases the response is a 302 with the Location
header. The Location header contains the URI of the target resource.
Consequently, the Ref-Target header is OPTIONAL in the response.
COPY, LOCK, DELETE, and MOVE do not return a 302 response, but
instead operate on the reference. For these methods, a Ref-Target
header is REQUIRED in the response. This allows the client to locate
the target resource in case it wants to resubmit the request to the
target.
Requests on collections with Depth header greater than 0 typically get
Multi-Status responses. Consequently, information about any references
in the collection cannot be returned in headers. Instead, the
corresponding DAV properties are returned in the DAV:response elements
for the references.
20.3 Appendix 3: Summary of Method Semantics for References
This section summarizes the semantics of each HTTP and WebDAV method
when the request-URI identifies a reference. The normative statements
that are summarized here can be found in Sections 4.3 - 4.10.
For each method, there are four cases to consider:
o Request-URI identifies a redirect reference, and the No-Passthrough
header is not used
o Request-URI identifies a redirect reference, and the No-Passthrough
header is present
o Request-URI identifies a direct reference, and the No-Passthrough
header is not used
o Request-URI identifies a direct reference, and the No-Passthrough
header is present
When the No-Passthrough header is used, the situation is simple. For
all methods, the request is applied to the reference, not to its target
resource.
The following table summarizes behavior for the cases where the No-
Passthrough header is not used:
METHOD | REDIRECT REFERENCE | DIRECT REFERENCE
GET | Respond with 302 status code | Apply method to target
HEAD | Respond with 302 status code | Apply method to target
OPTIONS | Respond with 302 status code | Apply method to target
PUT | Respond with 302 status code | Apply method to target
POST | Respond with 302 status code | Apply method to target
MKCOL | Respond with 302 status code | Apply method to target
| | (fails unless dangling)
MKREF | Respond with 302 status code | Apply method to target
| | (fails unless dangling)
PROPPATCH | Respond with 302 status code | Apply method to target
PROPFIND | Respond with 302 status code | Apply method to target
=====================================================================
DELETE | Apply method to reference | Apply method to reference
MOVE | Apply method to reference | Apply method to reference
=====================================================================
COPY | Apply method to reference | Apply method to target
LOCK | Apply method to reference | Apply method to target
UNLOCK | Apply method to reference | Apply method to target
PROPFIND, DELETE, MOVE, COPY, LOCK, and UNLOCK can be applied to
collections. In cases where the collection contains references,
behavior for the references in the collection follows the same rules as
the table describes for individual references. So, for example, if a
PROPFIND encounters a redirect reference within a collection, it returns
a 302 status code for that redirect reference in the Multi-Status
response. If the PROPFIND encounters a direct reference, it returns the
properties of the direct reference’s target resource in the Multi-Status
response.
Expires August 26, 1999
 End of changes. 

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