draft-ietf-webdav-collection-protocol-02.txt   draft-ietf-webdav-collection-protocol-03.txt 
WEBDAV Working Group J. Slein, Xerox WEBDAV Working Group J. Slein, Xerox
INTERNET DRAFT J. Davis, Xerox INTERNET DRAFT J. Davis, Xerox
<draft-ietf-webdav-collection-protocol-02> A. Babich, FileNet <draft-ietf-webdav-collection-protocol-03> T. Chihaya, DataChannel
G. Clemm, Rational
C. Fay, FileNet
E.J. Whitehead Jr., UC Irvine E.J. Whitehead Jr., UC Irvine
November 10, 1998 A. Babich, FileNet
Expires May 10, 1999 February 26, 1999
Expires August 26, 1999
WebDAV Advanced Collections Protocol WebDAV Advanced Collections Protocol
Status of this Memo Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working This document is an Internet-Draft and is in full conformance with all
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 made obsolete 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 entire list of current Internet-Drafts, please check the To view the list Internet-Draft Shadow Directories, see
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow http://www.ietf.org/shadow.html.
Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe),
ftp.nis.garr.it (Southern Europe),munnari.oz.au (Pacific Rim),
ftp.ietf.org (US EastCoast), or ftp.isi.edu (US West Coast).
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://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth>.
Abstract Abstract
The base WebDAV protocol [WebDAV] provides basic support for The base WebDAV protocol [WebDAV] provides basic support for
collections. It defines a MKCOL method for creating collections and collections. It defines a MKCOL method for creating collections and
specifies how other HTTP and WebDAV methods interact with collections. specifies how other HTTP and WebDAV methods interact with collections.
It supports internal members of collections, which it defines as members It supports internal members of collections, which it defines as URIs
whose URIs are immediately relative to the URI of the collection. that are immediately relative to the URI of the collection.
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: referential resources and ordering. needed: referential resources and ordering.
This draft specifies extensions to the base WebDAV protocol to support This draft specifies extensions to the base WebDAV protocol to support
these more powerful collections. these more powerful collections.
Table of Contents Table of Contents
1 Terminology ............................................... 3 1 Notational Conventions........................................4
2 Introduction .............................................. 4 2 Terminology...................................................4
3 Referential Resources ..................................... 4 3 Introduction..................................................5
3.1 Scope ..................................................... 4 4 Referential Resources.........................................5
3.2 Overview .................................................. 5
3.3 Creating Referential Resources ............................ 7 4.1 Scope.........................................................5
3.3.1 The MKREF Method .......................................... 7 4.2 Overview......................................................6
3.3.2 Status Codes .............................................. 8 4.3 Creating Referential Resources................................8
3.3.3 Example ................................................... 8 4.3.1 The MKREF Method..............................................8
3.4 Deleting, Copying, and Moving Referential Resources ....... 9 4.3.2 Status Codes..................................................9
3.5 Listing Referential Members of a Collection ............... 9 4.3.3 Example: MKREF................................................9
3.6 Other WebDAV Operations on Redirect Referential Resources . 9 4.4 Listing Referential Members of a Collection...................9
3.7 Other WebDAV Operations on Direct Referential Resources .. 10 4.4.1 Example: PROPFIND on a Collection with References............10
3.8 HTTP Operations on Redirect Referential Resources ........ 10 4.4.2 Example: PROPFIND with No-Passthrough on a Collection with
3.9 HTTP Operations on Direct Referential Resources .......... 11 References...................................................12
3.10 Operations on Targets of Referential Resources ........... 12 4.5 Copying Referential Resources................................15
3.11 Discovering a Targetís References ........................ 12 4.5.1 COPY for Direct References...................................15
3.12 Behavior of Dangling Direct References ................... 13 4.5.2 COPY for Redirect References.................................16
3.13 Summary of Referencing Headers Required in Responses ..... 16 4.5.3 Example: COPY on a Direct Reference..........................16
4 Ordered Collections ...................................... 16 4.5.4 Example: COPY on a Redirect Reference........................16
4.1 Overview ................................................. 16 4.5.5 Example: COPY on a Collection That Contains a Direct
4.2 Creating an Ordered Collection ........................... 16 Reference and a Redirect Reference...........................17
4.2.1 Overview ................................................. 16 4.6 Deleting and Moving Referential Resources....................18
4.2.2 Status Codes ............................................. 17 4.7 Locking Referential Resources................................19
4.2.3 Example .................................................. 17 4.7.1 LOCK on Direct References....................................19
4.3 Setting the Position of a Collection Member .............. 17 4.7.2 LOCK on Redirect References..................................20
4.3.1 Overview ................................................. 18 4.7.3 Example: LOCK on a Direct Reference..........................21
4.3.2 Status Codes ............................................. 18 4.7.4 Example: LOCK on a Redirect Reference........................22
4.3.3 Examples ................................................. 18 4.7.5 Example: LOCK on a Collection That Contains a Direct
4.4 Changing the Semantics of a Collection Ordering .......... 19 Reference and a Redirect Reference...........................22
4.5 Changing the Position of a Collection Member ............. 19 4.8 Other WebDAV Operations on Redirect Referential Resources....24
4.5.1 The ORDERPATCH Method .................................... 19 4.8.1 Example: PROPPATCH on a Redirect Reference...................24
4.5.2 Status Codes ............................................. 19 4.9 Other WebDAV Operations on Direct Referential Resources......24
4.5.3 Example .................................................. 19 4.9.1 Example: PROPPATCH on a Direct Reference.....................25
4.5.4 Design Rationale ......................................... 21 4.10 HTTP Operations on Redirect Referential Resources............25
5 New Headers .............................................. 21 4.10.1 Example: GET on a Redirect Reference.........................26
5.1 Ref-Target Entity Header ................................. 21 4.10.2 Example: GET on a Redirect Reference with No-Passthrough.....26
5.2 Ref-Type Entity Header ................................... 22 4.11 HTTP Operations on Direct Referential Resources..............26
5.3 Ref-Integrity Entity Header .............................. 22 4.11.1 Example: GET on a Direct Reference...........................26
5.4 Re-Direct Request Header ................................. 23 4.11.2 Example: GET on a Direct Reference with No-Passthrough.......26
5.5 Hide-Target Entity Header ................................ 23 4.12 Operations on Targets of Referential Resources...............26
5.6 Resource-Type Entity Header .............................. 23 4.13 Discovering a Targetís References............................26
5.7 Ordered Entity Header .................................... 23 4.14 Behavior of Dangling Direct References.......................27
5.8 Position Request Header .................................. 24 4.14.1 Example: PROPFIND on a Collection with a Dangling Direct
5.9 DAV-Collections Entity Header ............................ 24 Reference....................................................28
6 New Properties ........................................... 24 4.15 Chains of Direct References..................................29
6.1 reftarget Property ....................................... 25 4.16 URIs and References..........................................29
6.2 refintegrity Property .................................... 25 5 Ordered Collections..........................................30
6.3 reftype Property ......................................... 25 5.1 Overview.....................................................30
6.4 references Property ...................................... 25 5.2 Creating an Ordered Collection...............................31
6.5 orderingtype Property .................................... 26 5.2.1 Overview.....................................................31
7 New XML Elements ......................................... 26 5.2.2 Status Codes.................................................31
7.1 reference XML Element .................................... 26 5.2.3 Example: Creating an Ordered Collection......................31
7.2 direct XML Element ....................................... 26 5.3 Setting the Position of a Collection Member..................32
7.3 redirect XML Element ..................................... 26 5.3.1 Overview.....................................................32
7.4 weak XML Element ......................................... 26 5.3.2 Status Codes.................................................32
7.5 unordered XML Element .................................... 27 5.3.3 Examples: Setting the Position of a Collection Member........32
7.6 custom XML Element ....................................... 27 5.4 Changing the Semantics of a Collection Ordering..............33
7.7 order XML Element ........................................ 27 5.5 Changing the Position of a Collection Member.................33
7.8 ordermember XML Element .................................. 27 5.5.1 The ORDERPATCH Method........................................33
7.9 position XML Element ..................................... 28 5.5.2 Status Codes.................................................33
7.10 first XML Element ........................................ 28 5.5.3 Example: Changing the Positions of Collection Members in
7.11 last XML Element ......................................... 28 the Ordering.................................................34
7.12 before XML Element ....................................... 28 5.5.4 Design Rationale.............................................35
7.13 after XML Element ........................................ 28 6 Headers......................................................35
8 Extensions to the DAV:multistatus XML Element ............ 29 6.1 Ref-Target Entity Header.....................................35
9 Capability Discovery ..................................... 29 6.1.1 Example: Resolving a Relative URI in Ref-Target..............36
9.1 Using OPTIONS ............................................ 29 6.2 Ref-Type Entity Header.......................................37
9.2 Example .................................................. 29 6.3 Ref-Integrity Request Header.................................37
10 Dependencies on Other Specifications ..................... 30 6.4 No-Passthrough Request Header................................37
11 Security Considerations .................................. 30 6.5 Ordered Entity Header........................................38
11.1 Redirect Loops ........................................... 30 6.6 Position Request Header......................................38
11.2 References and Denial of Service ......................... 30 7 Properties...................................................39
11.3 Maintaining Referential Integrity May Reveal Private Locations30 7.1 reftarget Property...........................................39
11.4 DAV:references and Denial of Service ..................... 30 7.1.1 Example: Resolving a Relative URI in the DAV:reftarget.......39
11.5 DAV:references and Malicious Deletion of Resources ....... 31 7.2 refintegrity Property........................................40
11.6 Malicious Modifications of Ordering ...................... 31 7.3 reftype Property.............................................41
11.7 Denial of Service and DAV:orderingtype ................... 31 7.4 location Property............................................41
12 Internationalization Considerations ...................... 31 7.5 references Property..........................................41
13 IANA Considerations ...................................... 31 7.6 orderingtype Property........................................42
14 Copyright ................................................ 32 8 XML Elements.................................................42
15 Intellectual Property .................................... 32 8.1 reference XML Element........................................42
16 Acknowledgements ......................................... 32 8.2 direct XML Element...........................................42
17 References ............................................... 32 8.3 redirect XML Element.........................................42
18 Authors' Addresses ....................................... 32 8.4 weak XML Element.............................................43
19 Appendices ............................................... 33 8.5 unordered XML Element........................................43
19.1 Appendix 1 - Extensions to the WebDAV Document Type Definition33 8.6 custom XML Element...........................................43
8.7 order XML Element............................................43
8.8 ordermember XML Element......................................43
8.9 position XML Element.........................................44
8.10 first XML Element............................................44
8.11 last XML Element.............................................44
8.12 before XML Element...........................................44
8.13 after XML Element............................................44
9 Extensions to the DAV:response XML Element for Multi-Status
Responses....................................................45
10 Capability Discovery.........................................45
10.1 Using OPTIONS................................................45
10.2 Example: Capability Discovery................................46
11 Dependencies on Other Specifications.........................46
12 Security Considerations......................................46
12.1 Privacy Concerns.............................................46
12.2 Redirect Loops...............................................47
12.3 References and Denial of Service.............................47
12.4 References May Reveal Private Locations......................47
12.5 DAV:references and Denial of Service.........................48
12.6 DAV:references and Malicious Deletion of Resources...........48
12.7 Denial of Service and DAV:orderingtype.......................48
13 Internationalization Considerations..........................48
14 IANA Considerations..........................................48
15 Copyright....................................................49
16 Intellectual Property........................................49
17 Acknowledgements.............................................49
18 References...................................................49
18.1 Normative References.........................................49
1 Terminology 18.2 Informational References.....................................49
19 Authors' Addresses...........................................50
20 Appendices...................................................50
20.1 Appendix 1: Extensions to the WebDAV Document Type
Definition...................................................50
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
Since this document describes a set of extensions to the HTTP/1.1
protocol, the augmented BNF used here to describe protocol elements is
exactly the same as described in Section 2.1 of [HTTP]. Since this
augmented BNF uses the basic production rules provided in Section 2.2 of
[HTTP], these rules apply to this document as well.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2 Terminology
The terminology used here follows and extends that in the base WebDAV The terminology used here follows and extends that in the base WebDAV
protocol specification [WebDAV]. protocol specification [WebDAV].
Collection Collection
A resource that contains member resources A resource that contains a set of URIs, termed member URIs, which
identify member resources
Member Resource Member URI
A resource contained by a collection A URI which is a member of the set of URIs contained by a
collection
Referential Resource (or Reference) Referential Resource (or Reference)
A resource that has no content of its own, but rather is a A resource that has no body of its own (though it does have
reference to another resource properties), but rather is a reference to another resource
Ordinary Resource Ordinary Resource
A resource that is not a reference to another resource A resource that is not a reference to another resource
Target Resource Target Resource
The resource referenced by a referential resource The resource referenced by a referential resource
Direct Reference Direct Reference
A reference that is resolved by the server, giving the client the A reference that is resolved by the server without any client
illusion that it is operating directly on the target resource action, giving the client the illusion that it is operating
directly on the target resource
Redirect Reference Redirect Reference
A reference that must be resolved by the client A reference that requires client action before it can be resolved,
so that the client is aware that a reference is mediating between
it and the target resource
Strong Reference Strong Reference
A reference whose referential integrity is guaranteed by the A reference whose referential integrity is enforced by the server
server
Weak Reference Weak Reference
A reference whose referential integrity is not guaranteed by the A reference whose referential integrity is not enforced by the
server server
Referential Integrity Referential Integrity
A server guarantees the integrity of a reference if it ensures The integrity of a reference is preserved as long as it points to
that the reference will not be broken, or enables the reference's the same resource it pointed to when it was created. Its
owner to ensure that the reference will not be broken. integrity may be destroyed if the target resource is moved without
updating the reference to reflect its new location, or if the
target resource is deleted.
2 Introduction 3 Introduction
The simple collections that the base WebDAV specification supports are The simple collections that the base WebDAV specification supports are
powerful enough to be widely useful. They provide for the hierarchical powerful enough to be widely useful. They provide for the hierarchical
organization of resources, with mechanisms for creating and deleting organization of resources, with mechanisms for creating and deleting
collections, copying and moving them, locking them, adding resources to collections, copying and moving them, locking them, adding members to
them and deleting resources from them, and getting listings of their them and removing members from them, and getting listings of their
members. Delete, copy, move, list, and lock operations can be applied members. Delete, copy, move, list, and lock operations can be applied
recursively, so that a client can operate on whole hierarchies with a recursively, so that a client can operate on whole hierarchies with a
single request. 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: references and ordering.
References make it possible for many collections, on the same or References make it possible for many collections, on the same or
different servers, to share the same resource. Because the collections different servers, to share the same resource. Because the collections
share the resource by referencing it, only one physical copy of the share the resource by referencing it, only one physical copy of the
resource need exist, and any changes made in the resource are visible resource need exist, and any changes made in the resource are visible
from all the collections that reference it. from all the collections that reference it.
It is useful for many applications to be able to impose an ordering on a It is useful for many applications to be able to impose an ordering on a
collection. Orderings may be based on property values, but they may be collection. Orderings may be based on property values, but they may be
completely independent of any properties on the collectionís member completely independent of any properties on the resources identified by
resources. Orderings based on properties can be obtained using a search the collectionís member URIs. Orderings based on properties can be
protocol [DASL], but orderings not based on properties need some other obtained using a search protocol [DASL], but orderings not based on
mechanism. properties need some other mechanism.
Since these two areas are independent of each other, servers may elect Since these two areas are independent of each other, servers may elect
to comply with the Referential Resources section of this specification to comply with the Referential Resources section of this specification
or with the Ordered Collections section or both. A server that supports or with the Ordered Collections section or both. A server that supports
referencing MUST support redirect references, and MAY support direct referencing MUST support redirect references, and MAY support direct
references. A server MUST advertise its compliance with particular references. A server MUST advertise its compliance with particular
parts of this specification through its response to an OPTIONS request, parts of this specification through its response to an OPTIONS request,
as specified in Section 9 below. as specified in Section 10 below.
3 Referential Resources 4 Referential Resources
3.1 Scope 4.1 Scope
[WebDAVReq] distinguishes between "weak" references and "strong" [CollReq] distinguishes between "weak" references and "strong"
references, and also between "redirect" references and "direct" references, and also between "redirect" references and "direct"
references. This specification supports weak references, direct references. This specification supports weak references, direct
references, and redirect references, and is designed so that it can be references, and redirect references, and is designed so that it can be
extended to support strong references in the future. extended to support strong references in the future.
Strong references are references whose integrity is guaranteed by the Strong references are references whose integrity is enforced by the
server; weak references are those whose integrity is not guaranteed. server; weak references are those whose integrity is not enforced by the
Strong references and weak references are both useful in different server. Strong references and weak references are both useful in
contexts. Some applications cannot tolerate broken links. A software different contexts. Some applications cannot tolerate broken links. A
development application, for example, must be able to rely on the software development application, for example, must be able to rely on
integrity of references to component modules. Such applications must be the integrity of references to component modules. Such applications must
able to request strong references. Other applications may want to be able to request strong references. Other applications may want to
reference target resources on multiple servers, where referential reference target resources on multiple servers, where referential
integrity cannot be guaranteed, and may be less concerned about possible integrity cannot be enforced, and may be less concerned about possible
broken references. broken references.
Several considerations led to the decision not to support strong Several considerations led to the decision not to support strong
references in the current specification. First, there are many possible references in the current specification. First, there are many possible
policies that applications and services might use to enforce referential policies that applications and services might use in enforcing
integrity. referential integrity. Some examples are:
o Delete strong references when their targets are deleted. o Delete strong references when their targets are deleted.
o Decline to delete targets of strong references. o Decline to delete targets of strong references.
o Notify strong references when their targets have been deleted. o Notify strong references when their targets have been deleted.
o Let owners of resources decide whether strong references to them are o Replace strong references with copies of their targets before
allowed. deleting the targets.
There appears to be no common practice in this area. Moreover, some of There appears to be no common practice in this area. Moreover, some of
the policies have significant security risks. the policies have significant security risks.
o Moving a target of strong references could be a security risk to the o Moving a target of strong references could be a security risk to the
owner of the target by revealing secret locations on the target's owner of the target by revealing secret locations on the target's
server. server.
o A strong reference could be a security risk to the owner of the o A strong reference could be a security risk to the owner of the
reference by revealing secret locations on his server. reference by revealing secret locations on his server.
o The presence of strong references to resources on a server could make 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 it impossible to reclaim space on that server by moving or deleting
those target resources. those target resources.
These considerations together led to the decision not to support strong These considerations together led to the decision not to support strong
references in the short term. references in the short term.
3.2 Overview 4.2 Overview
A referential resource is a resource that has no content of its own, but A referential resource is a resource that has no body of its own, but
instead references another resource. The resource it references may be instead references another resource. The resource it references may
in the same collection as the reference, or in any other collection. have a URI in the same collection as the reference, or in any other
This target resource may be a collection or a simple resource or another collection. This target resource may be a collection or a simple
reference, or any other sort of resource that may be defined in the resource or another reference, or any other sort of resource that may be
future. A resource may be the target of any number of referential defined in the future. A resource may be the target of any number of
resources. To make it possible to distinguish references from ordinary referential resources. To make it possible to distinguish references
resources, a new value of the DAV:resourcetype property is defined here. from ordinary resources, a new value of the DAV:resourcetype property is
The DAV:resourcetype property of all references MUST have the value defined here. The DAV:resourcetype property of all references MUST have
DAV:reference. the value DAV:reference.
Redirect references are references that must be resolved by the client. Redirect references are references that require action by the client
They are simple for servers to implement, straightforward for clients to
use, and have only limited security implications. Any server that
complies with WebDAV referencing MUST provide redirect references.
To resolve a redirect reference, the client retrieves the DAV:reftarget before they can be resolved. They are simple for servers to implement,
property, whose value is the URI of the target resource. Every straightforward for clients to use, and have only limited security
reference, direct or redirect, MUST have the DAV:reftarget property. If implications. Any server that complies with WebDAV referencing MUST
a client wishes to operate on the target resource of a redirect provide redirect references.
reference, it resolves the reference, and then invokes the operation on
the target resource.
The redirect reference appears to the client as an independent resource If the client is aware that it is operating on a redirect reference, it
with its own properties. Operations with the URI of the redirect can resolve the reference by retrieving the referenceís DAV:reftarget
reference as their request-URI affect the reference, not its target property, whose value is the URI of the target resource. It can then
resource. submit requests to the target resource.
Direct references, in contrast, are resolved by the server. They give Otherwise, the client submits a request to the redirect reference. For
the client the illusion that it is operating directly on the target most operations, the response is a 302 (Moved Temporarily), accompanied
resource. These references are more complex for the server to by the Ref-Type header with the value "DAV:redirect" and the Location
implement, and raise additional security issues. Consequently, servers header with the URI of the target resource. The client can then
are not required to provide direct references in order to be compliant resubmit the request to the URI of the target resource. A few
with WebDAV referencing. 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
server. They give the client the illusion that it is operating directly
on the target resource. These references are more complex for the
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.
The default behavior of a direct reference is to apply most operations The default behavior of a direct reference is to apply most operations
directly to its target, so that the client is not aware that a reference directly to its target, so that the client is not aware that a reference
is mediating between it and the target resource. The exceptions are is mediating between it and the target resource. The exceptions are
operations that affect membership in a collection rather than the state operations that affect membership in a collection rather than the state
of the target resource. At present, the operations that fall into this of the target resource. At present, the operations that fall into this
category are DELETE, MOVE, and COPY. These operations are applied to category are DELETE and MOVE. These operations are applied to the
the reference itself rather than to its target, so that only the reference itself rather than to its target, so that only the collection
collection containing the reference is affected. containing the reference is affected.
The Re-Direct request header is also provided, to force an operation to The No-Passthrough request header is also provided, to force an
be applied to the direct reference itself rather than its target. In operation to be applied to the reference itself rather than its target.
effect, it makes the reference behave like a redirect reference for that It can be used with most requests to direct or redirect references.
request. This header is particularly useful with PROPFIND, to allow This header is particularly useful with PROPFIND, to allow clients to
clients to view the referenceís own properties. view the referenceís own properties.
Ideally, non-referencing clients should be able to use both direct and
redirect references. This goal is more difficult to meet for redirect
references, since client action is required to resolve them. The
strategy of having redirect references respond to most requests with a
302 (Moved Temporarily), accompanied by the URI of the target resource
in the Location header, fulfills this goal in most cases.
To distinguish between direct and redirect references, a new DAV:reftype To distinguish between direct and redirect references, a new DAV:reftype
property is defined, with the values DAV:direct and DAV:redirect. Every property is defined, with the values DAV:direct and DAV:redirect. Every
reference MUST have the DAV:reftype property. The DAV:reftype property reference MUST have the DAV:reftype property. The DAV:reftype property
of a direct reference MUST have the value DAV:direct. The DAV:reftype of a direct reference MUST have the value DAV:direct. The DAV:reftype
property of a redirect reference MUST have the value DAV:redirect. property of a redirect reference MUST have the value DAV:redirect.
Every reference MUST have the DAV:reftarget property, whose value is the
URI of the referenceís target resource.
Although strong references are not currently supported, a new Although strong references are not currently supported, a new
DAV:refintegrity property is defined in anticipation of future support DAV:refintegrity property is defined in anticipation of future support
for strong references. DAV:refintegrity will allow clients to for strong references. DAV:refintegrity will allow clients to
distinguish between weak and strong references. All references MUST distinguish between weak and strong references. All references MUST
have this property. Although the only value currently defined for have this property. Although the only currently defined for
DAV:refintegrity is DAV:weak, other values may be defined in the future. DAV:refintegrity is DAV:weak, other values may be defined in the future,
and servers MAY use extension values to identify their policy for
***** If a server wants to enforce referential integrity outside this enforcing referential integrity for that resource.
protocol, a value of DAV:weak is misleading.
3.3 Creating Referential Resources 4.3 Creating Referential Resources
3.3.1 The MKREF Method 4.3.1 The MKREF Method
Referential resources are created using the MKREF method. The request- Referential resources are created using the MKREF method. The request-
URI of the MKREF request identifies the resource to be created. The URI of the MKREF request identifies the resource to be created. The
required Ref-Target header contains the URI of the target resource. REQUIRED Ref-Target header contains the URI of the target resource.
An optional Ref-Integrity general header is defined below, primarily for
future support for strong references. The only value currently defined
for this header is "DAV:weak", although other values may be used by
private agreement. "DAV:weak" is the default value if the header is not
present.
***** Does Ref-Integrity = DAV:weak mean that the server need not An OPTIONAL Ref-Integrity request header is defined below, primarily for
enforce referential integrity, or that it must not enforce referential future support for strong references. The only values currently defined
integrity for the new resource? We have a requirement that there be for this header are "do-not-enforce" and "enforce", although other
some way to request the server not to enforce referential integrity for values may be used by private agreement. If a server receives the value
a particular reference. You might also want to change from donít- "do-not-enforce", it MUST NOT enforce referential integrity for the
enforce to enforce at different times in the life of the reference. reference being created. If a server receives the value "enforce", it
MUST enforce referential integrity for the reference being created, but
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 An OPTIONAL Ref-Type general header is defined below, with values
"DAV:direct" and "DAV:redirect". The default value is "DAV:redirect" if "DAV:direct" and "DAV:redirect". The default value is "DAV:redirect" if
the header is not present. the header is not present.
The optional Hide-Target request header is defined below, to enable the An OPTIONAL Position request header supports ordered collections by
creator of a direct reference to specify that the DAV:reftarget property
be hidden from clients. If the Hide-Target header is not present, the
server MUST assume that the DAV:reftarget property is not to be hidden.
If the Hide-Target header is used with Ref-Type header set to
DAV:redirect, the server MUST ignore the Hide-Target header. The Ref-
Target header MUST never be returned in response to any request for a
direct reference created with the Hide-Target header.
***** How useful is this really? Isnít it the owner of the target (not
of the reference) who wants to control whether the location of the
target is hidden? True, we have a scenario where the person creating
the reference wants to hide the location of the target, but thatís
because the owner of the reference and the owner of the target are the
same person in that example.
An optional Position request header supports ordered collections by
allowing the client creating a reference to specify where the new member allowing the client creating a reference to specify where the new member
is to be placed in the collection's ordering. (This header can also be is to be placed in the collection's ordering. (This header can also be
used with PUT to create an ordinary resource at a specific position in used with any other method that adds a member to a collection, to
the collection ordering.) specify its position in the collection ordering.)
When a server processes a MKREF request, it MUST set the When a server processes a MKREF request, it MUST set the
DAV:resourcetype property (defined in [WebDAV]) of the new resource to DAV:resourcetype property (defined in [WebDAV]) of the new resource to
be DAV:reference. be DAV:reference.
When a server processes a MKREF request, it MUST set the DAV:reftarget When a server processes a MKREF request, it MUST set the DAV:reftarget
property to the URI of the target resource. property to the URI of the target resource.
When a server processes a MKREF request, it MUST set the DAV:reftype
property based on the value of the Ref-Type header.
When a server processes a MKREF request, it MUST set the When a server processes a MKREF request, it MUST set the
DAV:refintegrity property and the DAV:reftype property based on the
values of the Ref-Integrity and Ref-Type headers.
The client MUST NOT send any content with the MKREF request, and so MUST DAV:refintegrity property to "DAV:weak" if it is not enforcing
NOT use the Content-Length or Transfer-Encoding headers. (See [HTTP].) referential integrity for the newly-created reference. If it is
enforcing referential integrity for the new reference, it MAY set the
value of DAV:refintegrity to an extension value identifying its
enforcement policy.
If a MKREF request is submitted for an existing resource, the existing The client MUST NOT send any content with the MKREF request, and so MUST
resource's content and headers will be overwritten. This behavior is NOT use the Content-Length or Transfer-Encoding headers. (See [HTTP]
analogous to the behavior of the HTTP PUT method. Live properties may Section 4.3.)
get new values at the server's discretion; dead properties will retain
their existing values. If the Position header is absent in this case
and the collection is ordered, the server MUST leave the member at its
previous position in the collection ordering. If the Position header is
present and the collection is ordered, the server MUST remove the member
from its previous position, and then insert it at the requested
position.
3.3.2 Status Codes If a MKREF request has a request-URI that identifies an existing
resource, the request MUST fail. This behavior is analogous to the
behavior of the MKCOL method [WebDAV].
201 (Created): The reference was successfully created. 4.3.2 Status Codes
200 (OK): The reference was successfully created, replacing an existing Servers MUST use the HTTP/1.1 status codes as defined in [HTTP]. Some
resource at the same location. likely client errors for MKREF include:
400 (Bad Request): The client attempted to send content with the 400 (Bad Request): The client attempted to send content with the
request, or set an invalid value for the Ref-Target, Ref-Integrity, Ref- request, or set an invalid value for the Ref-Target, Ref-Integrity, Ref-
Type, or Position header. Type, or Position header.
405 (Method Not Allowed): A resource already exists at the request-URI.
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.
***** These are not conflicts with the state of the resource at the 4.3.3 Example: MKREF
request-URI, but conflicts with the state of the parent collection or
the target resource. Is it still appropriate to use 409?
507 (Insufficient Storage): There is not enough space on the server to
complete the request.
3.3.3 Example
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: </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 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. Its DAV:resourcetype property is identified by the Ref-Target header. Its DAV:resourcetype property is
set to DAV:reference. Its DAV:reftarget property is set to the URI of set to DAV:reference. Its DAV:reftarget property is set to the URI of
its target resource. Its DAV:refintegrity property is set to the its target resource. Its DAV:refintegrity property is set to the value
default value of DAV:weak. Its DAV:reftype property is set to the of DAV:weak, indicating that the server will not enforce referential
integrity for the new reference. Its DAV:reftype property is set to the
default value of DAV:redirect. default value of DAV:redirect.
3.4 Deleting, Copying, and Moving Referential Resources 4.4 Listing Referential Members of a Collection
The DELETE method should be used to delete referential resources. For A URI of a reference can be a member of a collection just as the URI of
both direct and redirect references, DELETE affects the reference an ordinary resource can. A listing of members of a collection shows
itself, and not its target. 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.
A MOVE operation on a referential resource moves the referential For each direct reference, the properties returned by the PROPFIND MUST
resource to a different location, but has no effect on the location of be the properties of the target resource unless the No-Passthrough
its target. The DAV:reftarget property is unchanged after a MOVE unless header is included with the PROPFIND request.
the Ref-Target header is used to change it.
A COPY operation on a referential resource copies the referential For each redirect reference, the response element MUST contain a 302
resource, not its target resource, to another location. The (Moved Temporarily) status code unless the No-Passthrough header is
DAV:reftarget property of the destination resource is the same as the included with the PROPFIND request. The DAV:location and DAV:reftype
DAV:reftarget of the source resource, unless the Ref-Target header is properties MUST be included with the 302 status code, extending the
used to change it. syntax of the DAV:response element that was defined in [WebDAV] as
described in Section 9 below. A referencing client can tell from the
DAV:reftype property that the collection contains a redirect reference.
The DAV:location property contains the absolute URI of the target
resource. A referencing client can either use the DAV:location property
to retrieve the properties of the target resource or can submit a
PROPFIND to the redirect reference with the No-Passthrough header to
retrieve its properties. The DAV:location property is expected to be
defined in a future revision of [WebDAV], at which time non-referencing
clients will also be able to use the response to retrieve the properties
of the target resource.
3.5 Listing Referential Members of a Collection If Depth = infinity in the PROPFIND request, the server MUST NOT follow
redirect references into any collections to which they may refer.
Since a referential member of a collection is just a resource in the If Depth = infinity in the PROPFIND request, the server MUST follow
collection, a listing of members of the collection shows referential direct references into any collections to which they may refer unless
members along with ordinary members. That is, a WebDAV PROPFIND request the No-Passthrough header is used with the request. That is, if the
on a collection resource with Depth = 1 or infinity MUST return a target resource is a collection, the server MUST list the members of
response XML element for each ordinary member and for each referential that collection.
member.
For a redirect reference, the properties returned by the PROPFIND are The No-Passthrough header MAY be used with a PROPFIND request on a
the properties of the reference itself. If Depth = infinity in the collection. If the No-Passthrough header is present, then the
PROPFIND request, the server MUST NOT follow redirect references into properties of the references in the collection MUST be returned, 302
any collections to which they may refer. (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.
For a direct reference, the properties returned by the PROPFIND are the 4.4.1 Example: PROPFIND on a Collection with References
properties of its target resource. If Depth = infinity in the PROPFIND
request, the server MUST follow direct references into any collections
to which they may refer. That is, if the target resource is a
collection, the server MUST list the members of that collection. If the
Re-Direct header is used with PROPFIND, the server MUST treat any direct
references like redirect references, as described in the previous
paragraph.
3.6 Other WebDAV Operations on Redirect Referential Resources http://www.svr.com/MyCollection/
(ordinary resource) diary.html
(direct reference) tuva
(redirect reference) nunavut
Operations on a redirect reference affect only the reference, and not The target of http://www.svr.com/MyCollection/tuva is a collection:
its target resource. http://www.feynman.com/tuva/
(ordinary resource) history.html
(ordinary resource) music.html
A LOCK operation on a redirect reference locks the reference, not its Request:
target. A LOCK on the collection with Depth = 1 or infinity locks any PROPFIND /MyCollection/ HTTP/1.1
redirect references that are members of the collection. It does not Host: www.svr.com
lock the targets of those redirect references. Depth: infinity
Content-Type: text/xml
Content-Length: xxxx
A PROPPATCH on a redirect reference modifies the properties of the <?xml version="1.0" ?>
reference, not the properties of its target resource. <D:propfind xmlns:D="DAV: ">
<D:prop xmlns:J="http://www.svr.com/jsprops/">
<D:resourcetype/>
<J:keywords/>
</D:prop>
</D:propfind>
A PROPFIND on a redirect reference returns the properties of the Response:
reference, not the properties of its target resource.
3.7 Other WebDAV Operations on Direct Referential Resources HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxx
With the exception of DELETE, MOVE, and COPY, which were discussed <?xml version="1.0" ?>
above, operations on direct references affect the target resource, not <D:multistatus xmlns:D="DAV:"
the reference, unless the Re-Direct header is used. xmlns:J="http://www.svr.com/jsprops/">
<D:response>
<D:href>http://www.svr.com/MyCollection/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>collection</D:resourcetype>
<J:keywords>diary, interests, hobbies</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/diary.html</D:href>
<D:propstat>
<D:prop>
<D:resourcetype></D:resourcetype>
<J:keywords>diary, travel, family, history</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</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:status>HTTP/1.1 302 Moved Temporarily</D:status>
<D:prop>
<D:location>
<D:href>http://www.inac.gc.ca/art/inuit/</D:href>
</D:location>
<D:reftype>redirect</D:reftype>
</D:prop>
</D:response>
</D:multistatus>
Unless the Re-Direct header is used, a LOCK operation on a direct In this example, Depth = infinity and the No-Passthrough header is not
reference locks the target. A lock on a direct reference to a used. The collection contains one URI that identifies a redirect
collection locks the target collection. A lock on a collection with reference. The response element for the redirect reference has a status
Depth = 1 or infinity locks the targets of the direct references in the of 302 (Moved Temporarily), and includes a DAV:prop element with the
collection. DAV:location and DAV:reftype properties to allow clients to retrieve the
properties of its target resource. The collection also contains one URI
that identifies a direct reference. The response element for the direct
reference contains the properties of its target collection. There are
also response elements for each member of its target collection.
Unless the Re-Direct header is used, a PROPPATCH on a direct reference 4.4.2 Example: PROPFIND with No-Passthrough on a Collection with
modifies the properties of its target resource, not the properties of References
the reference itself.
Unless the Re-Direct header is used, a PROPFIND on a direct reference /MyCollection/
returns the properties of its target resource, not the properties of the (collection) photos/
reference itself. (ordinary resource) family.gif
(ordinary resource) trip.gif
(ordinary resource) diary.html
(direct reference) tuva
(redirect reference) nunavut
If the Re-Direct header is used with a LOCK, PROPPATCH, or PROPFIND Request:
request on a direct reference, it behaves as if it were being applied to
a redirect reference, as specified in Section 3.6.
3.8 HTTP Operations on Redirect Referential Resources PROPFIND /MyCollection/ HTTP/1.1
Host: www.svr.com
Depth: infinity
No-Passthrough:
Content-Type: text/xml
Content-Length: xxxx
Although existing HTTP clients cannot create referential resources, they <?xml version="1.0" ?>
should be able to read collections created by reference-aware WebDAV <D:propfind xmlns:D="DAV:">
clients. They should be able to follow any references in those <D:prop>
collections to their targets. To make this possible, a server that <D:resourcetype/>
receives a GET or HEAD on a redirect reference MUST return a 302(Moved <D:reftype/>
Temporarily) status code. The server MUST follow [HTTP] Section 10.3.3 <D:reftarget/>
"302 Moved Temporarily," but with these additional rules: </D:prop>
</D:propfind>
o The Location header MUST contain the target URI of the reference. Response:
o The response MUST include all referencing entity headers that make HTTP/1.1 207 Multi-Status
sense for redirect references: Ref-Type, Ref-Target, and Ref- Content-Type: text/xml
Integrity. Content-Length: xxxx
o The response MUST also include those HTTP headers that make sense for <?xml version="1.0" ?>
referential resources, at a minimum: Cache-Control, Age, ETag, <D:multistatus xmlns:D="DAV:">
Expires, and Last-Modified. <D:response>
<D:href>http://www.svr.com/MyCollection/</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/</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: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/diary.html</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/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:propstat>
<D:prop>
<D:resourcetype>reference</D:resourcetype>
<D:reftype>redirect</D:reftype>
<D:reftarget>
<D:href>http://www.inac.gc.ca/art/inuit/</D:href>
</D:reftarget>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
The second and third of these rules preserve normal GET and HEAD Since the No-Passthrough header is present, the response shows the
properties of the references in the collection rather than the
properties of their targets. Even though Depth = infinity, the No-
Passthrough header prevents the server from listing the members of the
collection that is the target of the direct reference. No-Passthrough
also prevents a 302 response from being returned for the redirect
reference.
behavior for reference-aware WebDAV clients. 4.5 Copying Referential Resources
POST cannot be applied to a redirect reference. A reference cannot In determining the semantics of COPY, the desire to provide intuitively
accept another entity as its subordinate. Depending upon the nature of correct behavior was weighed against consistency considerations.
the target resource, however, it might make sense to apply POST to the
target. A server that receives a POST request on a redirect reference
MUST return a 302 (Moved Temporarily). The rules for constructing and
using the response are the same as for GET and HEAD, except that there
is no requirement to return any headers other than Ref-Type. This header
allows reference-aware WebDAV clients to recognize the resource as a
reference and understand the reason for the redirection.
PUT cannot be applied to a redirect reference. To replace one redirect A clientís intent in performing a COPY operation is to create a new
reference with another, MKREF MUST be used. To replace a redirect resource that is similar to the original resource and behaves like the
reference with an ordinary resource, the reference MUST first be deleted original resource, and that can be modified without affecting the
with DELREF, after which a PUT MUST be used to create the ordinary original resource. For references to ordinary resources, the
resource. expectation would be that the target resource be copied. This would
yield an independent resource that could be modified without affecting
the original resource. For collections the situation is less clear.
There is tension between two expectations. On the one hand, the client
may expect the new copy of the collection to behave like the old one
(which implies having references where the old one had references). On
the other hand, the client may expect that it will be possible to modify
the members of the new collection without affecting the members of the
old collection (which implies having copies of the targets where the
original collection had references).
Existing HTTP clients that do not understand referential resources need 4.5.1 COPY for Direct References
to be accommodated, however. To enable these clients to operate
reasonably on redirect references, a server that receives a PUT request COPY follows the general principle that operations on direct references
on a redirect reference MUST return a 302 (Moved Temporarily). The are applied to the target resource unless the No-Passthrough header is
client and server MUST follow [HTTP] Section 10.3.3 "302 Moved 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:
HTTP/1.1 204 No Content
Ref-Type: direct
Ref-Target: /Asia/History/tuva.html
In this example, the request-URI identifies a direct reference whose
target resource is identified by
http://www.svr.com/Asia/History/tuva.html. This target resource was
copied to the destination location in the Destination header,
http://www.svr.com/OtherCollection/tuva.html. The headers included with
the response insure that the client knows that it was operating on a
direct reference, and that the client knows which resource was copied.
4.5.4 Example: COPY on a Redirect Reference
Request:
COPY /MyCollection/tuva HTTP/1.1
Host: www.svr.com
Destination: http://www.svr.com/OtherCollection/tuva.html
Response:
HTTP/1.1 204 No Content
Ref-Type: redirect
Ref-Target: /Asia/History/tuva.html
In this example, the request-URI identifies a redirect reference whose
target resource is identified by
http://www.svr.com/Asia/History/tuva.html. In this case, the reference
was copied to the destination location in the Destination header,
http://www.svr.com/OtherCollection/tuva.html. The Ref-Type header
included with the response informs the client that it was operating on a
redirect reference. The Ref-Target header provides the information the
client needs to copy the target resource, should it wish to do so.
The result would have been exactly the same, and the response would have
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
a Redirect Reference
/MyCollection/
(ordinary resource) diary.html
(direct reference) tuva
(redirect reference) nunavut
Request:
COPY /MyCollection/ HTTP/1.1
Host: www.svr.com
Destination: http://www.svr.com/OtherCollection/
Response:
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: nnnn
<?xml version="1.0" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<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
[WebDAV] Section 8.8.3 for reducing the length of responses to COPY
requests. Although the entire COPY operation in the example was
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
The DELETE method is used to delete referential resources. For both
direct and redirect references, DELETE MUST affect the reference itself,
and not its target. Similarly, when a DELETE on a collection encounters
a reference in the subtree under that collection, it MUST delete the
reference, and not its target.
A MOVE operation on a referential resource MUST move the referential
resource to a different location, and MUST NOT change the location of
its target. The DAV:reftarget property is unchanged after a MOVE.
Similarly, when a MOVE on a collection encounters a reference in the
subtree under that collection, it MUST move the reference, and not its
target.
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
contains its URI. 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
DELETE. For direct references, MOVE is logically equivalent to COPY
with the No-Passthrough header followed by DELETE.
4.7 Locking Referential Resources
The semantics of LOCK described here resulted from balancing a set of
incompatible considerations:
o Ideally, a LOCK on a reference should lock both the reference and its
target resource. The owner of an exclusive write lock, for example,
would be surprised if anyone else could modify the content of the
target resource while he held the lock. He would also be surprised
if anyone else could delete the reference to it, or replace the
reference with one pointing to a different target.
o Non-referencing clients should be able to use both direct and
redirect references without encountering surprising results.
o Preserve the clear distinction between redirect and direct
references. Redirect references should be simple for servers to
implement. In particular, a server should never have to resolve a
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
referential resource and the behavior of LOCK on a collection that
contains referential resources.
o Keep the behavior of all requests to references as consistent as
possible. Try to adhere to the general rule that in the absence of a
No-Passthrough header, all methods return a 302 when sent to a
redirect reference and are applied to the target when sent to a
direct reference.
o Be consistent with the LOCK semantics defined in [WebDAV].
We have compromised the intuitive locking behavior and support for non-
referencing clients in order to preserve various sorts of consistency.
4.7.1 LOCK on Direct 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
possible for the case of locking collections that contain redirect
references.
The expected behavior for any operation on a redirect reference is that
a 302 (Moved Temporarily) response will be returned, unless the No-
Passthrough header is used. However, this policy would have
unacceptable consequences when locking a collection that contains
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
collection, the entire LOCK must fail. This would make it impossible to
lock any collection that contained a redirect reference.
To avoid this result, a LOCK on a collection with Depth > 0 MUST lock
any redirect references it encounters, and not return 302 responses for
them, whether or not the No-Passthrough header is used.
This gives part of the expected lock behavior without forcing the server
to resolve the redirect reference or become a proxy server in cases
where the target resides on a different server.
Each DAV:response element for a redirect reference MUST include the
DAV:reftype and DAV:reftarget properties so that a referencing client
can lock the targets if it wishes. (There will be no hint in any
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
and may never realize that the targets have not been locked.
Clearly, a LOCK with Depth = infinity on a collection MUST NOT follow
any redirect references whose targets are collections into the target
collections; it MUST NOT cause any members of those target collections
to be locked.
The behavior of LOCK for individual redirect references is designed to
be consistent with LOCK behavior for collections that contain redirect
references. Whether or not a No-Passthrough header is present, a LOCK
on a redirect reference MUST lock only the reference, not its target,
and it MUST NOT return a 302 response. The response MUST include the
Ref-Type and Ref-Target headers, so that a referencing client can lock
the target resource if it wishes.
UNLOCK behaves as specified in [WebDAV], unlocking all resources
included in the lock identified by the Lock-Token header.
4.7.3 Example: LOCK on a Direct Reference
Request:
LOCK /MyCollection/tuva HTTP/1.1
Host: www.svr.com
Content-Type: text/xml
Content-Length: nnnn
Authorizaton: Digest username="jas",
realm=jas@webdav.sb.aol.com, nonce=". . .",
uri="/MyCollection/tuva",
response=". . .", opaque=". . ."
<?xml version="1.0" ?>
<D:lockinfo xmlns:D="DAV:">
<D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype>
<D:owner>
<D:href>http://www.svr.com/~jas/contact.html</D:href>
</D:owner>
</D:lockinfo>
Response:
HTTP/1.1 200 OK
Ref-Type: direct
Ref-Target: /Asia/History/tuva.html
Content-Type: text/xml
Content-Length: nnnn
<?xml version="1.0" ?>
<D:prop xmlns:D="DAV:">
<D:lockdiscovery>
<D:activelock>
<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>
In this example, the request-URI identifies a direct reference whose
target resource is identified by
http://www.svr.com/Asia/History/tuva.html. This target resource was
locked. The Ref-Type and Ref-Target headers included with the response
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.7.5 Example: LOCK on a Collection That Contains a Direct Reference and
a Redirect Reference
/MyCollection/
(ordinary resource) diary.html
(direct reference) tuva
(redirect reference) nunavut
Request:
LOCK /MyCollection/ HTTP/1.1
Host: www.svr.com
Content-Type: text/xml
Content-Length: nnnn
Authorizaton: Digest username="jas",
realm=jas@webdav.sb.aol.com, nonce=". . .",
uri="/MyCollection/tuva",
response=". . .", opaque=". . ."
<?xml version="1.0" ?>
<D:lockinfo xmlns:D="DAV:">
<D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype>
<D:owner>
<D:href>http://www.svr.com/~jas/contact.html</D:href>
</D:owner>
</D:lockinfo>
Response:
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: nnnn
<?xml version="1.0" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/MyCollection/</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
<D:prop>
<D:lockdiscovery>
<D:activelock>
<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:href>/MyCollection/tuva</D:href>
<D:status>HTTP/1.1 200 OK</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>/MyCollection/nunavut</D:href>
<D:status>HTTP/1.1 200 OK</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>
Although the entire LOCK operation was 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
locked. Since /MyCollection/nunavut is a redirect reference, the
reference itself, and not its target, was locked. There is no response
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
Although non-referencing WebDAV clients cannot create referential
resources, they should be able to use the references created by
reference-aware WebDAV clients. They should be able to follow any
references to their targets. To make this possible, a server that
receives a PROPFIND, PROPPATCH, MKCOL, or MKREF request made via a
redirect reference MUST return a 302 (Moved Temporarily) status code.
The client and server MUST follow [HTTP] Section 10.3.3 "302 Moved
Temporarily," but with these additional rules: 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 target URI of the
reference. reference.
o The response MUST include the Ref-Type header. This header allows o The response MUST include the Ref-Type header. This header allows
reference-aware WebDAV clients to recognize the resource as a 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.
o The response MUST include an entity body for display to users. The A reference-aware WebDAV client can act on this response in one of two
entity body explains that the requested resource is a reference to ways. It can, like a non-referencing client, resubmit the request to
another resource, and allows the user to choose whether to replace the URI in the Location header in order to operate on the target
the target resource or to replace the reference. resource. Alternatively, it can resubmit the request to the URI of the
redirect reference with the No-Passthrough header in order to operate on
the reference itself. If the No-Passthrough header is present, the
request MUST be applied to the reference itself, and a 302 response MUST
NOT be returned.
This last rule is needed for PUT, but not for GET, HEAD, or POST. Only If a reference-aware client knows before submitting its request that the
for PUT does it make sense for the user to confirm that the operation is request-URI identifies a redirect reference, it can save the round trip
to be performed at the request-URI. GET or HEAD will already have caused by the 302 response by using No-Passthrough in its initial
returned all useful information about the request-URI. POST makes no request to the URI.
sense for the redirect reference at the request-URI. But the user might
really want to replace the redirect reference with the entity in the PUT
request.
To enable existing HTTP clients to retrieve the capabilities of the Since MKCOL and MKREF fail when applied to existing resources, if the
target resource, a server that receives an OPTIONS request on a redirect client attempts to resubmit the request to the target resource, the
reference MUST return a 302 (Moved Temporarily). At the same time, request MUST fail (unless the reference is a dangling reference).
reference-aware WebDAV clients may need to retrieve the capabilities of Similarly, if the client attempts to resubmit the request to the
the reference itself. Consequently, the server MUST provide a choice as reference with a No-Passthrough header, the request MUST fail.
to whether the method should be applied to the reference or its target.
Consequently, the same rules apply for OPTIONS as for PUT above.
3.9 HTTP Operations on Direct Referential Resources 4.8.1 Example: PROPPATCH on a Redirect Reference
GET, HEAD, PUT, POST, and OPTIONS on direct references are passed 4.9 Other WebDAV Operations on Direct Referential Resources
through to their target resources. GET returns the content and headers
of the target resource, HEAD returns the headers of the target resource,
PUT replaces the content of the target resource, POST performs the
expected function at the target resource, and OPTIONS reports the
communication options available at the target resource.
The Re-Direct request header may be used with GET, HEAD, or OPTIONS to With the exception of DELETE and MOVE, which were discussed above,
view the headers or capabilities of the reference, rather than its operations on direct references affect the target resource, not the
target. If the Re-Direct header is used, the methodís behavior is as reference, unless the No-Passthrough header is used.
described in Section 3.8.
The Re-Direct request header must not be used with PUT or POST, which Unless the No-Passthrough header is used, a PROPPATCH on a direct
cannot be applied to references. If a server receives a PUT or POST reference MUST modify the properties of its target resource, not the
request on a direct reference with the Re-Direct header, it MUST respond properties of the reference itself.
with a 400 (Bad Request).
***** Confirm behavior for PUT / POST with Re-Direct. 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.
3.10 Operations on Targets of Referential Resources If the No-Passthrough header is used with a PROPPATCH or PROPFIND
request on a direct reference, the operation MUST be applied to the
reference itself rather than to its target resource.
MKCOL and MKREF fail if their request-URI identifies an existing
resource of any kind. Consequently, when submitted to a target resource
via a direct reference, they MUST fail unless the reference is a
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
4.10 HTTP Operations on Redirect Referential Resources
Although existing HTTP clients cannot create referential resources, they
should be able to use collections created by reference-aware WebDAV
clients. They should be able to follow any references identified by
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
reference.
o The response MUST include the Ref-Type header. This header allows
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.
Like plain HTTP clients, they can resubmit the request to the URI in the
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
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
entity headers of a redirect reference. When No-Passthrough 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).
The No-Passthrough header can be used with PUT to replace the redirect
reference with an ordinary resource. It can be used with OPTIONS to
retrieve the capabilities of a redirect reference.
Clients MUST NOT, however, use the No-Passthrough header with POST.
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
4.10.2 Example: GET on a Redirect Reference with No-Passthrough
4.11 HTTP Operations on Direct Referential Resources
GET, HEAD, PUT, POST, and OPTIONS on direct references are automatically
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
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
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
4.11.2 Example: GET on a Direct Reference with No-Passthrough
4.12 Operations on Targets of Referential Resources
In general, operations on targets of weak referential resources have no In general, operations on targets of weak referential resources have no
effect on the referential resource. However, servers that choose to effect on the referential resource. However, servers that choose to
maintain the integrity of references are free to make changes to the maintain the integrity of references are free to make changes to the
state of references when moving or deleting their targets. state of references when moving or deleting their targets.
When moving a target resource, a server MAY insert an optional step into When moving a target resource, a server MAY insert an optional step into
the semantics of MOVE as defined in [WebDAV] for the purpose of the semantics of MOVE as defined in [WebDAV] for the purpose of
maintaining referential integrity. Between the copy step and the delete maintaining referential integrity. Between the copy step and the delete
step of a MOVE, the server MAY perform an update step, which changes the step of a MOVE, the server MAY perform an update step, which changes the
DAV:reftarget property of any references to the target to reflect its DAV:reftarget property of any references to the target to reflect its
new location. new location.
When deleting a target resource, a server MAY perform any internal When deleting a target resource, a server MAY perform any internal
operations necessary to implement its policy on preserving referential operations necessary to implement its policy on preserving referential
integrity. For example, it might delete any references to the deleted 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 target, or it might flag them as having a deleted target, or it might
replace references with copies of the target. replace references with copies of the target.
3.11 Discovering a Targetís References 4.13 Discovering a Targetís References
An optional DAV:references property on the target resource provides a An OPTIONAL DAV:references property on the target resource provides a
list of referential resources whose DAV:reftarget property points to list of referential resources whose DAV:reftarget property points to
that target resource. If present, DAV:references is a read-only that target resource. If present, DAV:references is a read-only
property, maintained by the server. By retrieving this property, a property, maintained by the server. By retrieving this property, a
client can discover the URIs of the references that point to the target, client can discover the URIs of the references that point to the target,
and so can also discover the collections of which those URIs are and so can also discover the collections that contain those URIs as
members. As for all DAV: properties, this specification is silent as to members. As for all DAV: properties, this specification is silent as to
how the DAV:references property is implemented on the server. how the DAV:references property is implemented on the server.
The DAV:references property is expected to be supported mainly by The DAV:references property is expected to be supported mainly by
Document Management Systems (DMSs) and other servers that will maintain Document Management Systems (DMSs) and other servers that will maintain
the property only for references within their own domain. It is not in 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 general possible for a server to maintain the property for references on
other servers. If a reference on a different server points to the 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 target, the server where the target is located is unlikely to know about
that reference. This protocol provides no mechanism for one server to that reference. This protocol provides no mechanism for one server to
notify another of the creation of a reference to one of its resources. notify another of the creation of a reference to one of its resources.
Consequently, the list of references in DAV:reftarget may be incomplete. Consequently, the list of references in DAV:reftarget may be incomplete.
Rationale: A number of scenarios require clients to navigate from a Rationale: A number of scenarios require clients to navigate from a
target resource to the references that point to it, and to the target resource to the references that point to it, and to the
collections that contain those references. This capability is collections that contain the URIs of those references. This capability
particularly important for DMSs, which may populate their collections is particularly important for DMSs, which may populate their collections
entirely by reference. Their clients may need to determine, for any entirely by reference. Their clients may need to determine, for any
object in the DMS, what collections it belongs to. It is also important object in the DMS, what collections contain URIs that identify
in other contexts. For example, some servers enforce referential references to that object. It is also important in other contexts. For
integrity by refusing to delete any resource that is referenced by other example, some servers enforce referential integrity by refusing to
resources. In such an environment, the client must be able to discover delete any resource that is referenced by other resources. In such an
the references in order to delete them before attempting to delete the environment, the client must be able to discover the references in order
target. to delete them before attempting to delete the target.
Once a search capability [DASL] is available, it may be possible for a
client to discover the references that point to a given target by
searching for resources with DAV:reftarget equal to the URI of the
target resource. However, it will be much more efficient for the client
to retrieve a list of references from the target resource.
***** Only if DASL provides search of structured properties or we define
DAV:reftarget as a string value, not an href.
Risks: When deciding whether to support the DAV:references property, Risks: When deciding whether to support the DAV:references property,
server implementors / administrators should balance the efficiencies it server implementers / administrators should balance the benefits it
provides in discovering references against the cost of maintaining the provides against the cost of maintaining the property and the security
property and the security risks enumerated in Sections 11.4 and 11.5. risks enumerated in Sections 12.4 and 12.5.
3.12 Behavior of Dangling Direct References 4.14 Behavior of Dangling Direct References
***** Think about chains of direct references. Whenever the No-Passthrough header accompanies a request on a dangling
direct reference, the request succeeds. Since No-Passthrough causes the
request to be applied to the reference rather than to its target, it
does not matter that the target resource does not exist. The client
will not be informed that the reference points to a nonexistent target.
GET and HEAD respond with 404 (Not Found), but the Ref-Type and Ref- In the absence of the No-Passthrough header, the responses MUST be as
Target headers are included in the response, so that the client can tell follows:
that it is the target, and not the reference, that was not found. (If
the Hide-Target header was used when creating the reference, then Ref-
Target is not included.)
PUT, MKCOL, and MKREF succeed, creating a new resource at the location GET, HEAD, OPTIONS, POST, PROPFIND, PROPPATCH, LOCK, UNLOCK, and COPY
specified by the referenceís DAV:reftarget property. 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.
POST fails with 404 (Not Found), since a nonexistent resource cannot If, however, a PROPFIND, LOCK, UNLOCK, or COPY with Depth header greater
accept another resource as its subordinate. The Ref-Type and Ref-Target than 0 on a collection encounters a dangling direct reference inside the
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 the
Hide-Target header was used when creating the reference, then Ref-Target
is not included.)
OPTIONS fails with 404 (Not Found). The Ref-Type and Ref-Target headers collection, the response is a 207 (Multi-Status). The DAV:response
are included in the response, so that the client can tell that it is the element for the dangling reference will have a status of 404 (Not
target, and not the reference, that was not found. (If the Hide-Target Found). The DAV:reftype and DAV:reftarget properties of the references
header was used when creating the reference, then Ref-Target is not 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.
included.) PUT succeeds, creating a new resource at the location specified by the
referenceís DAV:reftarget property.
PROPFIND responds with a 207 Multistatus, including a 404 (Not Found) as MKREF and MKCOL succeed, since there is no existing resource at the
the status for the target resource. The DAV:reftype and DAV:reftarget target URI.
properties of the references are included in the response. (If the
Hide-Target header was used when creating the reference, then
DAV:reftarget is not included.) Their presence informs the client that
it is the target, not the reference, that was not found. These two
elements are extensions to the DAV:multistatus element as defined in
{WEBDAV].
For example, MOVE and DELETE succeed, since they always affect the reference rather
than its target. For MOVE, the reference at the destination will be
broken, just as the reference at the source was.
4.14.1 Example: PROPFIND on a Collection with a Dangling Direct
Reference
Request: Request:
PROPFIND /collection1/directref7 HTTP/1.1 PROPFIND /collection1/ HTTP/1.1
Host: www.somehost.com Host: www.somehost.com
Depth: 1
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:X="http://www.somehost.com/schemas/x"> <D:prop xmlns:X="http://www.somehost.com/schemas/x">
<X:author/> <X:author/>
<X:title/> <X:title/>
</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.somehost.com/collection1/</D:href>
<D:propstat>
<D:prop xmlns:X=http://www.somehost.com/schemas/x>
<X:author>Smith, J.H.</X:author>
<X:title>My Working Collection</X:title>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.somehost.com/collection1/directref7</D:href> <D:href>http://www.somehost.com/collection1/directref7</D:href>
<D:status>HTTP/1.1 404 Not Found</D:status> <D:status>HTTP/1.1 404 Not Found</D:status>
<D:prop>
<D:reftype><D:direct/></D:reftype> <D:reftype><D:direct/></D:reftype>
<D:reftarget> <D:reftarget>
<D:href>http://www.somehost.com/collection2/file19</D:href> <D:href>/collection2/file19</D:href>
</D:reftarget> </D:reftarget>
</D:prop>
<D:responsedescription>Target resource not found.
</D:responsedescription>
</D:response> </D:response>
<D:responsedescription>Target resource not
found.</D:responsedescription>
</D:multistatus> </D:multistatus>
PROPPATCH responds with a 207 Multistatus, including a 404 (Not Found) 4.15 Chains of Direct References
as the status for the target resource. The DAV:reftype and
DAV:reftarget properties of the references are included in the response.
(If the Hide-Target header was used when creating the reference, then
DAV:reftarget is not included.) Their presence informs the client that
it is the target, not the reference, that was not found. These two
elements are extensions to the DAV:multistatus element as defined in
{WEBDAV].
***** Is a response to a PROPPATCH required to be a 207 (Multi-Status), Unless a No-Passthrough header is present, any operation on a direct
or could it just be a 404 (Not Found)? reference that is part of a chain of direct references MUST get passed
through to the target of the last reference in the chain.
For example, 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: Request:
PROPPATCH /collection1/directref7 HTTP/1.1 HEAD /math/ref1 HTTP/1.1
Host: www.somehost.com Host: www.somehost.edu
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" ?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop xmlns:X="http://www.somehost.com/schemas/x">
<X:author>Pauloosie Padluq</X:author>
<X:title>South Baffin Carvers</X:title>
</D:prop>
</D:set>
</D:propertyupdate>
Response: Response:
HTTP/1.1 207 Multi-Status HTTP/1.1 200 ok
Content-Type: text/xml Ref-Type: direct
Content-Length: xxxx Ref-Target: 0; /logic/ref2
Ref-Target: 1; /library/ref3
<?xml version="1.0" ?> Ref-Target: 2; /library/frege/grundgesetze.html
<D:multistatus xmlns:D="DAV:"> .
<D:response> .
<D:href>http://www.somehost.com/collection1/directref7</D:href>
<D:status>HTTP/1.1 404 Not Found</D:status>
<D:reftype><D:direct/></D:reftype>
<D:reftarget>
<D:href>http://www.somehost.com/collection2/file19</D:href>
</D:reftarget>
</D:response>
<D:responsedescription>Target resource not
found.</D:responsedescription>
</D:multistatus>
MOVE, COPY, and DELETE succeed. For MOVE and COPY, the reference at the A server cannot tell whether a dangling reference once pointed to an
destination will be broken, just as the reference at the source was. 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.
If a single resource is being LOCKed or UNLOCKed, the response is a 404 4.16 URIs and References
(Not Found). The Ref-Type and Ref-Target headers are included in the
response. (If the Hide-Target header was used when creating the
reference, then Ref-Target is not included.) Their presence informs the
client that it is the target, not the reference, that was not found.
If the dangling reference is a member of a collection that is being In a request-URI /segment1/segment2/segment3, any of the three segments
LOCKed or UNLOCKed, the response is a 207 (Multi-Status). The may identify a reference. (See [URI], Section 3.3, for definitions of
DAV:status element for the dangling reference is a 404 (Not Found). The "path" and "segment".) Servers will be unable to resolve such URIs
DAV:reftype and DAV:reftarget properties of the references are included unless certain constraints hold. If any segment of the path identifies
in the response. (If the Hide-Target header was used when creating the a reference, that reference MUST ultimately resolve to a resource that
reference, then DAV:reftarget is not included.) Their presence informs behaves as a container. (Examples are WebDAV collections, tar files,
the client that it is the target, not the reference, that was not found. and some CGI scripts.) The succeeding segment of the path MUST resolve
These two elements are extensions to the DAV:multistatus element as to a resource that is immediately contained in that container.
defined in {WEBDAV].
3.13 Summary of Referencing Headers Required in Responses Consider request-URI /x/y/z.html. Suppose that /x/ is a reference whose
target is collection /a/, which contains reference y whose target is
collection /b/, which contains reference z.html whose target is
/c/d.html.
This section summarizes the rules that determine which referencing /x/ -----> /a/
headers must be included in responses to requests on references. /a/y/ -----> /b/
/b/z.html -----> /c/d.html
o Every response to a request on a reference MUST include the Ref-Type The server is able to resolve the request-URI because each segment of
header, so that the client knows that it was operating on a the URI's path satisfies the constraints stated above. Except for the
reference, and whether the operation was applied to the reference final segment, each segment that is a reference resolves to a collection
itself or to its target. that contains the next segment as an internal member. The final
segment, which is a reference, does have a target resource.
o Every response to a request on a direct reference MUST include the If the references are direct references, the server automatically
Ref-Target header, unless the reference was created with the Hide- applies the request to the ultimate target, /c/d.html.
Target header. This allows the client to tell what resource was
affected by the operation. A request that includes the Re-Direct
header is treated as if it were a request on a redirect reference,
and so the response NEED NOT include the Ref-Target header.
o Every response to a GET or HEAD request on a redirect reference (or If the references are redirect references, the client must follow up
on a direct reference with the Re-Direct header) MUST include all the three separate 302 responses before finally reaching the target
referencing entity headers that make sense for redirect references: resource. The server responds to the initial request with a 302 with
Ref-Type, Ref-Target, and Ref-Integrity. 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.
4 Ordered Collections 5 Ordered Collections
4.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 members. If
a collection is ordered, each of its members must be in the ordering a collection is ordered, each of its members must be in the ordering
exactly once, and the ordering must not include any resource that is not exactly once, and the ordering must not include any resource that is not
a member of the collection. Only one ordering can be attached to any a member of the collection. Only one ordering can be attached to any
collection. Multiple orderings of the same resources can be achieved by collection. Multiple orderings of the same resources can be achieved by
creating multiple collections referencing those resources, and attaching creating multiple collections referencing those resources, and attaching
a different ordering to each collection. 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 resource from the ordering when it is removed The server MUST remove a member URI from the ordering when it is removed
from the collection. The server MUST add a resource to the ordering when from the collection. The server MUST add a member URI to the ordering
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.
4.2 Creating an Ordered Collection 5.2 Creating an Ordered Collection
4.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 can 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 in the MKCOL request, setting its value to the URI of the
semantics to be used. If the client does not want the collection to be semantics to be used or setting its value to DAV:custom if the semantics
ordered, it may omit the Ordered header, or use it with the value 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". "DAV:unordered".
Every collection MUST have the new DAV:orderingtype property, which Every collection MUST have the new DAV:orderingtype property, which
indicates whether the collection is ordered and, if so, identifies the indicates whether the collection is ordered and, if so, identifies the
semantics of the ordering. A value of DAV:unordered indicates that that semantics of the ordering. A value of DAV:unordered indicates that that
collection is not ordered. That is, the client cannot depend on the collection is not ordered. That is, the client cannot depend on the
repeatability of the ordering of results from a PROPFIND request. For repeatability of the ordering of results from a PROPFIND request. For
collections that are ordered, DAV:orderingtype SHOULD be set to an href collections that are ordered, DAV:orderingtype SHOULD be set to an href
that identifies the semantics of the ordering, allowing a human user or that identifies the semantics of the ordering, allowing a human user or
software package to insert new collection members into the ordering software package to insert new collection members into the ordering
skipping to change at line 921 skipping to change at line 1705
ordering is not being advertised. ordering is not being advertised.
If the Ordered header is present on a MKCOL request, the server MUST set If the Ordered header is present on a MKCOL request, the server MUST set
the collection's DAV:orderingtype property to the value of the Ordered the collection's DAV:orderingtype property to the value of the Ordered
header. If the Ordered header is not present, the server MUST treat the header. If the Ordered header is not present, the server MUST treat the
request as if it had an Ordered header with the value "DAV:unordered", request as if it had an Ordered header with the value "DAV:unordered",
meaning that the collection is not ordered. If the collection is meaning that the collection is not ordered. If the collection is
ordered, the server MUST respond to PROPFIND requests on the collection ordered, the server MUST respond to PROPFIND requests on the collection
using the specified ordering. using the specified ordering.
4.2.2 Status Codes 5.2.2 Status Codes
No new error conditions are introduced. Servers MUST use the HTTP/1.1 status codes as defined in [HTTP].
4.2.3 Example 5.2.3 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. In this case, the URI points to a description of the semantics
governing the ordering. As new members are added to the collection,
clients or end users can use the semantics to determine where to
position the new members in the ordering.
4.3 Setting the Position of a Collection Member header. In this case, the URI identifies the semantics governing the
ordering. As new members are added to the collection, clients or end
users can use the semantics to determine where to position the new
members in the ordering.
4.3.1 Overview 5.3 Setting the Position of a Collection Member
When a new member is added to a collection with MKREF, PUT, COPY, MOVE, 5.3.1 Overview
or LOCK, its position in the ordering can be set with the new Position
header. The Position header allows the client to specify that the When a new member is added to a collection (for example, with PUT,
member should be first in the collection's ordering, last in the MKREF, or MKCOL), its position in the ordering can be set with the new
Position header. The Position header allows the client to specify that
the member should be first in the collection's ordering, last in the
collection's ordering, before some other collection member in the collection's ordering, before some other collection member in the
collection's ordering, or after some other collection member in the collection's ordering, or after some other collection member in the
collection's ordering. collection's ordering.
The server MUST insert the new member into the ordering at the location The server MUST insert the new member into the ordering at the location
specified in the Position header, if one is present (and if the specified in the Position header, if one is present (and if the
collection is ordered); otherwise, it MUST append the new member to 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 or MKREF end of the ordering (if the collection is ordered). If a PUT causes an
causes an existing resource to be replaced, and if the Position header existing resource to be replaced, and if the Position header is absent,
is absent, the server MUST leave the member at its previous position in the server MUST leave the member at its previous position in thee
thee collection ordering. If the Position header is present, the server collection ordering. If the Position header is present, the server MUST
MUST remove the member from its previous position, and then insert it at remove the member from its previous position, and then insert it at the
the requested position. requested position.
4.3.2 Status Codes 5.3.2 Status Codes
201 (Created): The resource was successfully created. Servers MUST use the HTTP/1.1 status codes as defined in [HTTP]. Some
likely client errors for when setting the position of a collection
member include:
409 (Conflict): The request may be attempting to position the resource 409 (Conflict): The request may be attempting to position the collection
before or after a resource that is not in the collection, or before or member before or after a URI that is not in the collection, or before or
after itself, or it may be attempting to position the resource in an after itself, or it may be attempting to position the collection member
unordered collection. in an unordered collection.
4.3.3 Examples 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 the requirements.html
resource. /~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: </~whitehead/dav/draft-webdav-protocol-08.txt>
Position: First Position: First
Response: Response:
HTTP/1.1 409 Conflict HTTP/1.1 409 Conflict
In this case, the server returned a 409 Conflict status code because the In this case, the server returned a 409 Conflict status code because the
/~whitehead/dav/ collection is an unordered collection. Consequently, /~whitehead/dav/ collection is an unordered collection. Consequently,
the server was unable to satisfy the Position header. the server was unable to satisfy the Position header.
skipping to change at line 1011 skipping to change at line 1797
Position: First Position: First
Response: Response:
HTTP/1.1 409 Conflict HTTP/1.1 409 Conflict
In this case, the server returned a 409 Conflict status code because the In this case, the server returned a 409 Conflict status code because the
/~whitehead/dav/ collection is an unordered collection. Consequently, /~whitehead/dav/ collection is an unordered collection. Consequently,
the server was unable to satisfy the Position header. the server was unable to satisfy the Position header.
4.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. The client is then responsible for updating
the ordering of the collection members according to the new semantics. the ordering of the collection members according to the new semantics.
PROPPATCH is defined in [WebDAV], Section 7.2. PROPPATCH is defined in [WebDAV], Section 7.2.
4.5 Changing the Position of a Collection Member 5.5 Changing the Position of a Collection Member
4.5.1 The ORDERPATCH Method 5.5.1 The ORDERPATCH Method
To change the positions of collection members in the collection's To change the positions of collection members in the collection's
ordering, the client MUST use an ORDERPATCH request with a request body ordering, the client MUST use an ORDERPATCH request with a request body
containing an order XML element. The request-URI of an ORDERPATCH containing an order XML element. The request-URI of an ORDERPATCH
request is the URI of the collection whose ordering is to be updated. request is the URI of the collection whose ordering is to be updated.
The order XML element identifies the member resources whose positions The order XML element identifies the member URIs whose positions are to
are to be changed, and describes their new positions in the ordering. be changed, and describes their new positions in the ordering. Each new
Each new position can be specified as first in the ordering, last in the position can be specified as first in the ordering, last in the
ordering, before some other collection member in the ordering, or after ordering, before some other collection member in the ordering, or after
some other collection member in the ordering. The server MUST apply the some other collection member in the ordering. The server MUST apply the
changes in the order they appear in the order element. changes in the order they appear in the order element.
4.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 Within the 207 Multi-Status response, the following status codes are
possible: possible:
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 resource before or 409 (Conflict): An attempt was made to position the collection member
after a resource that is not in the collection, or before or after before or after a URI that is not in the collection, or before or after
itself, or an attempt was made to position the resource in an unordered itself, or an attempt was made to position the collection member in an
collection.
unordered collection.
A request to reposition a collection member to the same place in the A request to reposition a collection member to the same place in the
ordering is not an error. ordering is not an error.
4.5.3 Example 5.5.3 Example: Changing the Positions of Collection Members in the
Ordering
Consider a collection /coll-1/ with members ordered as follows: Consider a collection /coll-1/ with members ordered as follows:
nunavut.map nunavut.map
nunavut.img nunavut.img
baffin.map baffin.map
baffin.desc baffin.desc
baffin.img baffin.img
iqaluit.map iqaluit.map
nunavut.desc nunavut.desc
skipping to change at line 1124 skipping to change at line 1912
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
4.5.4 Design Rationale 5.5.4 Design Rationale
The decision to introduce the new ORDERPATCH method was made after The decision to introduce the new ORDERPATCH method was made after
investigating the possibility of using the existing MOVE method with a investigating the possibility of using the existing MOVE method with a
Position header. The use of MOVE initially looked appealingly simple: Position header. The use of MOVE initially looked appealingly simple:
MOVE /root/coll-1/foo HTTP/1.1 MOVE /root/coll-1/foo HTTP/1.1
Host: www.somehost.com Host: www.somehost.com
Destination: </root/coll-1/foo> Destination: </root/coll-1/foo>
Position: First Position: First
skipping to change at line 1149 skipping to change at line 1937
definition makes it impossible to MOVE a resource to a destination URL 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 that is the same as the source URL. The resource would be deleted
rather than moved. Second, [WebDAV] states that when moving a resource rather than moved. Second, [WebDAV] states that when moving a resource
to a destination where a resource already exists, the Overwrite header 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 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 destination before performing the MOVE. Again, this makes it impossible
to MOVE a resource to the same location. Finally, [WebDAV] states that 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 locks are lost on a MOVE, an outcome that seems undesirable in this
case. case.
5 New Headers 6 Headers
***** Decide which headers intended for MKREF also can be used with 6.1 Ref-Target Entity Header
MOVE, COPY, LOCK. Is it possible to create a referential resource by
invoking LOCK? If so, Ref-Type, Ref-Target, and Ref-Integrity would all
have to be usable with LOCK. We might need a Resource-Type header to
say that it is a reference we are creating. What about MOVE and COPY?
At the moment, weíre saying you can change Ref-Type, Ref-Target, and
Ref-Integrity on a MOVE or COPY. It would be pretty weird to change
Resource-Type. What about Hide-Target?
5.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 Ref-Target = "Ref-Target" ":" Coded-url
Coded-url is defined in [WebDAV], Section 8.4. The more complicated syntax is provided only for use in responses
involving chains of direct references.
The Ref-Target header is used with the MKREF method to identify the The Ref-Target header is used with MKREF requests to identify the target
target resource of the new referential resource being created. It is a resource of the new referential resource being created. It is a
required header in MKREF requests. This header may also be used with REQUIRED header in MKREF requests. When used with a MKREF request, its
COPY and MOVE requests to change the target of the destination value is simply a Coded-url, and only a single value is allowed. For an
reference. example, see Section 4.3.3.
Servers MUST include the Ref-Target header in the following responses Servers MUST include the Ref-Target header in responses to the following
unless the Hide-Target header was used when the reference was created, types of requests:
in which case the Ref-Target header MUST NOT be included in responses:
o Responses to GET and HEAD requests on redirect references Reference Type | No-Passthrough | Method
--------------------------------------------------------------
direct or redirect | Present | GET, HEAD
--------------------------------------------------------------
direct | Absent | All except MKREF, UNLOCK
--------------------------------------------------------------
redirect | Absent | COPY, LOCK, DELETE, MOVE
o Responses to all requests on direct references, unless the request The only case where multiple values of Ref-Target are allowed is when it
included the Re-Direct header 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.
5.2 Ref-Type Entity Header 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.
Ref-Type = "Ref-Type" ":" ("DAV:direct" | "DAV:redirect") 6.1.1 Example: Resolving a Relative URI in Ref-Target
The Ref-Type header is defined to distinguish between direct and Request:
redirect references. The possible values of this header are DAV:direct
and DAV:redirect. If the header is not present on a MKREF request, the
server MUST treat the request as if it has a Ref-Type header with the
value DAV:redirect. This header may also be used with a COPY or MOVE
request on a reference. If this header is not present on a COPY or MOVE
request, the DAV:reftype property MUST be treated like any other live
property, as specified in [WebDAV] sections 7.8.2 and 7.9.1.
Servers MUST include the Ref-Target header in the following responses: PUT /north/inuvik HTTP/1.1
Host: www.somehost.edu
Content-Type: image/gif
Content-Length: nnnnnn
o Responses to all requests on both direct and redirect references <body>
5.3 Ref-Integrity Entity Header Response:
Ref-Integrity = "Ref-Integrity" ":" ("DAV:weak") HTTP/1.1 200 ok
Ref-Type: direct
Ref-Target: mapcollection/inuvik.gif
The Ref-Integrity header is defined to allow future support for strong In this example, the base URI is http://www.somehost.edu/north/inuvik.
references. It specifies whether the server should enforce referential
integrity for a referential resource being created with MKREF. The only
value currently defined for the Ref-Integrity header is "DAV:weak",
which means that the server need not enforce referential integrity for
the newly created reference. Other values may be used by private
agreement between the client and server. If the header is not present
on a MKREF request, the server MUST treat the request as if it has a
Ref-Integrity header set to "DAV:weak". This header may also be used
with COPY and MOVE requests. If this header is not present on a COPY or
MOVE request, the DAV:refintegrity property MUST be treated like any
other live property, as specified in [WebDAV] sections 7.8.2 and 7.9.1.
***** Again, does DAV:weak mean that the server need not maintain The relative URI in Ref-Target resolves to the absolute URI
referential integrity, or that it must not? http://www.somehost.edu/north/mapcollection/inuvik.gif.
Servers MUST include the Ref-Integrity header in the following 6.2 Ref-Type Entity Header
responses:
o Responses to GET and HEAD requests on redirect references (or on Ref-Type = "Ref-Type" ":" ("DAV:direct" | "DAV:redirect")
direct references if the request included the Re-Direct header)
5.4 Re-Direct Request Header The Ref-Type header is defined to distinguish between direct and
redirect references. The possible values of this header are DAV:direct
and DAV:redirect. If the header is not present on a MKREF request, the
server MUST treat the request as if it has a Ref-Type header with the
value DAV:redirect.
Re-Direct = "Re-Direct" ":" Servers MUST include the Ref-Target header in every response to a
request whose request-URI identifies a reference, with the exception of
responses to MKREF requests.
The optional Re-Direct header can be used on any request to a direct 6.3 Ref-Integrity Request Header
reference except PUT or POST. It forces the reference to behave like a
redirect reference for that request. The operation will be applied to
the reference itself, not to its target. If the Re-Direct header is
used on a request to any other sort of resource besides a direct
reference, the server SHOULD ignore it. If the Re-Direct header is used
with a PUT or POST request on a direct reference, the server MUST
respond with a 400 (Bad Request).
***** Confirm behavior for exception cases. Ref-Integrity = "Ref-Integrity" ":" ("do-not-enforce" | "enforce" |
extend)
extend = 1#CHAR
***** What if there is a chain of direct references? Suppose I want to The Ref-Integrity header is defined primarily to allow future support
see the properties of the second reference in the chain - how would I do for strong references. It specifies whether the server should enforce
that? referential integrity for a referential resource being created with
MKREF.
5.5 Hide-Target Entity Header The value "do-not-enforce" means that the server MUST NOT enforce
referential integrity for the newly created reference. A client might
use this value if, for example, it wanted to populate a collection with
references before their content was made available on the Web.
Hide-Target = "Hide-Target" ":" The value "enforce" means that the server MUST enforce referential
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.
The optional Hide-Target header is for use when creating a new direct Clients and servers may use other values of the Ref-Integrity header by
reference. It specifies that the URI of the target resource is to be private agreement, to specify more precisely the desired policy for
hidden. If this header is used when creating a direct reference, the enforcing referential integrity. If a server receives an extension
server MUST NOT include the Ref-Target header in any response to a value that it does not understand, it MUST fail the request.
request on the reference. If the Hide-Target header is not present, the
server MUST assume that the DAV:reftarget property is not to be hidden.
If the Hide-Target header is used in a request with Ref-Type =
DAV:redirect, the server MUST ignore the Hide-Target header.
***** If we want to let clients change their minds about Hide-Target If the Ref-Integrity header is not present on a MKREF request, the
after a reference has been created, we need a DAV:hidetarget property to server MAY enforce referential integrity or not, and if it does enforce
allow that. referential integrity, it MAY follow any policy it chooses.
5.6 Resource-Type Entity Header 6.4 No-Passthrough Request Header
Resource-Type = "Resource-Type" ":" ["DAV:collection" | "DAV:reference" No-Passthrough = "No-Passthrough" ":"
|""]
The Resource-Type header contains the value of the DAV:resourcetype The optional No-Passthrough header can be used on any request to a
property. It is used with LOCK, MOVE, or COPY to set or change the reference except POST. For a direct reference, if the No-Passthrough
resource type.
***** Not needed unless you can create a reference with LOCK, or change header is present, the request MUST be applied to the reference itself
resource type with MOVE or COPY. 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).
5.7 Ordered Entity Header The No-Passthrough header can be used with PROPFIND requests on
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
with Depth = infinity. When it is used in this way, the server MUST
lock any redirect references in the collection, just as it would if the
No-Passthrough header were absent. It MUST also lock any direct
references in the collection (not their target resources), and it MUST
NOT follow any direct references to collections into their target
collections.
The No-Passthrough header can be used with COPY requests on collections
with Depth > 0. When it is used in this way, the server MUST copy any
redirect references in the collection, just as it would if the No-
Passthrough header were absent. It MUST also copy any direct references
in the collection (not their target resources), and it MUST NOT follow
any direct references to collections into their target collections.
6.5 Ordered Entity Header
Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url)
The Ordered header may be used with MKCOL to request that the new The Ordered header may be used with MKCOL to request that the new
collection be ordered and to specify its ordering semantics. A value of collection be ordered and to specify its ordering semantics. A value of
"DAV:unordered" indicates that the collection is not ordered. That is, "DAV:unordered" indicates that the collection is not ordered. That is,
the client cannot depend on the repeatability of the ordering of results the client cannot depend on the repeatability of the ordering of results
from a PROPFIND request. A Coded-url value indicates that the collection from a PROPFIND request. A Coded-url value indicates that the collection
is ordered, and identifies the semantics of the ordering, allowing a is ordered, and identifies the semantics of the ordering, allowing a
human user or software package to insert new collection members into the human user or software package to insert new collection members into the
ordering intelligently. The Coded-url MAY point to a resource that ordering intelligently. The Coded-url MAY point to a resource that
contains a definition of the semantics of the ordering. A value of 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.
If the Ordered header is not present on a MKCOL request, the server MUST If the Ordered header is not present on a MKCOL request, the server MUST
treat the request as if it had an Ordered header with the value treat the request as if it had an Ordered header with the value
"DAV:unordered". "DAV:unordered".
5.8 Position Request Header 6.6 Position Request Header
Position = "Position" ":" ("First" | "Last" | Position = "Position" ":" ("First" | "Last" |
(("Before" | "After") Coded-url)) (("Before" | "After") Coded-url))
The Position header may be used with MKREF, PUT, COPY, MOVE, or LOCK to The Position header may be used with any method that adds a member to a
tell the server where in the collection ordering to position the collection to tell the server where in the collection ordering to
resource being added to the collection. It may be used for both position the new member being added to the collection. It may be used
ordinary and referential members. for both ordinary and referential members.
If the Coded-url is a relative URL, it is interpreted relative to the If the Coded-url is a relative URL, it is interpreted relative to the
collection in which the resource is being created. collection to which the new member is being added.
If the Position request header is not used, then: If the Position request header is not used, then:
If the request is replacing an existing resource, the server MUST If the request is replacing an existing resource, the server MUST
preserve the present ordering. preserve the present ordering.
If the request is adding a new member to the collection, the server MUST 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 append the new member to the end of the ordering (if the collection is
ordered). ordered).
5.9 DAV-Collections Entity Header 7 Properties
DAV-Collections = "DAV-Collections" ":" 1#collection-capability
collection-capability = "DAV:basicref" | "DAV:directref" |
"DAV:orderedcoll"
The DAV-Collections header is used in responses to OPTIONS requests, to
enumerate the collection-related capabilities of the resource. A value
of "DAV:basicref" indicates that the resource provides basic referencing
(redirect references). A value of "DAV:directref" indicates that the
resource provides direct references. If a resource provides direct
references, it MUST also provide redirect references. A value of
"DAV:orderedcoll" indicates that the resource provides ordered
collections.
6 New Properties
6.1 reftarget Property 7.1 reftarget Property
Name: reftarget Name: reftarget
Namespace: DAV: Namespace: DAV:
Purpose: A required property of referential resources that provides Purpose: A REQUIRED property of referential resources that provides
an efficient way for clients to discover the URI of the an efficient way for clients to discover the URI of the
target resource. This is a read-only property, whose value target resource. This is a read-only property, whose value
can only be set by using the Ref-Target header with a MKREF, can only be set by using the Ref-Target header with a MKREF
COPY, or MOVE request. request.
Value: URI of the target resource. 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> <!ELEMENT reftarget href>
6.2 refintegrity Property 7.1.1 Example: Resolving a Relative URI in the DAV:reftarget
Request:
PROPFIND /geog/ HTTP/1.1
Host: www.xxsvr.com
No-Passthrough:
Depth: 1
Content-Type: text/xml
Content-Length: nnn
<?xml version="1.0" ?>
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:resourcetype/>
<D:reftype/>
<D:reftarget/>
</D:prop>
</D:propfind>
Response:
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: nnn
<?xml version="1/0" ?>
<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
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
Name: refintegrity Name: refintegrity
Namespace: DAV: Namespace: DAV:
Purpose: A required property of a referential resource that indicates Purpose: A REQUIRED property of a referential resource that indicates
whether the server guarantees referential integrity for that whether the server enforces referential integrity for that
reference. The refintegrity property is defined to allow reference. The refintegrity property is defined to allow
future support for strong references. The only value future support for strong references. The only value
currently defined for refintegrity is weak, which means that currently defined for refintegrity is weak, which means that
the server need not [does not?] enforce referential the server does not enforce referential integrity for the
integrity for the reference. Other values may be used by reference. Although a server may assign another value to
private agreement between the client and server. This is a identify its policy for enforcing referential integrity for
readonly property, whose value can only be set by using the the reference, it cannot count on clients understanding such
Ref-Integrity header with a MKREF, COPY, or MOVE request. extension values. This is a readonly property.
Value: weak Value: weak or an extension value
<!ELEMENT refintegrity (weak)> <!ELEMENT refintegrity (weak | ANY)>
6.3 reftype Property 7.3 reftype Property
Name: reftype Name: reftype
Namespace: DAV Namespace: DAV:
Purpose: A required property of a referential resource that Purpose: A required property of a referential resource that
identifies the reference as direct or redirect. This is a identifies the reference as direct or redirect. This is a
read-only property, whose value can only be set by using read-only property, whose value can only be set by using
the Ref-Type header with a MKREF, COPY, or MOVE request. the Ref-Type header with a MKREF request.
Value: direct | redirect Value: direct | redirect
<!ELEMENT reftype (direct | redirect)> <!ELEMENT reftype (direct | redirect)>
6.4 references Property 7.4 location Property
Name: location
Namespace: DAV:
Purpose: For use with 302 (Moved Temporarily) response codes in
Multi-Status responses. It contains the absolute URI of the
temporary location of the resource. In the context of
redirect references, this value is the absolute URI of the
target resource. It is analogous to the Location header in
HTTP 302 responses defined in [HTTP] Section 10.3.3 "302
Moved Temporarily." Including the location property in a
Multi-Status response requires an extension to the syntax of
the DAV:response element defined in [WebDAV], which is
defined in Section 9 below. This property is not expected
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
a Multi-Status response.
Value: href containing the absolute URI of the target resource.
<!ELEMENT location href >
7.5 references Property
Name: references Name: references
Namespace: DAV: Namespace: DAV:
Purpose: Enables clients to discover, for any target resource, what Purpose: Enables clients to discover, for any target resource, what
references point to it and what collections contain it by references point to it and what collections contain it by
reference. This is an optional property. If present, it is reference. This is an optional property. If present, it is
a read-only property, maintained by the server. a read-only property, maintained by the server.
Value: List of the URIs of the references that point to the target Value: List of the URIs of the references that point to the target
resource. resource.
<!ELEMENT references (href*)> <!ELEMENT references (href*)>
6.5 orderingtype Property 7.6 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 URI MAY point to a definition of the ordering
semantics. The value custom may be used for a collection semantics. The value custom may be used for a collection
that is to be ordered, but for which the semantics are not that is to be ordered, but for which the semantics are not
being advertised. being advertised.
<!ELEMENT orderingtype (arbitrary | custom | href) > <!ELEMENT orderingtype (arbitrary | custom | href) >
7 New XML Elements 8 XML Elements
7.1 reference XML Element 8.1 reference XML Element
Name: reference Name: reference
Namespace: DAV: Namespace: DAV:
Purpose: A new value of the DAV:resourcetype property that identifies Purpose: A new value of the DAV:resourcetype property that identifies
its resource as a referential resource. The its resource as a referential resource. The
DAV:resourcetype property of a referential resource MUST DAV:resourcetype property of a referential resource MUST
have this value. have this value.
Value: EMPTY Value: EMPTY
<!ELEMENT reference EMPTY > <!ELEMENT reference EMPTY >
7.2 direct XML Element 8.2 direct XML Element
Name: direct Name: direct
Namespace: DAV: Namespace: DAV:
Purpose: A value for the DAV:reftype property that identifies its Purpose: A value for the DAV:reftype property that identifies its
resource as a direct reference. resource as a direct reference.
Value: EMPTY Value: EMPTY
<!ELEMENT direct EMPTY > <!ELEMENT direct EMPTY >
7.3 redirect XML Element 8.3 redirect XML Element
Name: redirect Name: redirect
Namespace: DAV: Namespace: DAV:
Purpose: A value for the DAV:reftype property that identifies its Purpose: A value for the DAV:reftype property that identifies its
resource as a redirect reference. resource as a redirect reference.
Value: EMPTY Value: EMPTY
<!ELEMENT redirect EMPTY > <!ELEMENT redirect EMPTY >
7.4 weak XML Element 8.4 weak XML Element
Name: weak Name: weak
Namespace: DAV: Namespace: DAV:
Purpose: The only value currently defined for the DAV:refintegrity Purpose: A value of the DAV:refintegrity property. It means that the
property. It means that the server need not [does not?] server does not enforce referential integrity for the
enforce referential integrity for the reference to which the reference to which the property belongs.
property belongs.
Value: EMPTY Value: EMPTY
<!ELEMENT weak EMPTY > <!ELEMENT weak EMPTY >
7.5 unordered XML Element 8.5 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 Value: EMPTY
<!ELEMENT unordered EMPTY > <!ELEMENT unordered EMPTY >
7.6 custom XML Element 8.6 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 Value: EMPTY
<!ELEMENT custom EMPTY > <!ELEMENT custom EMPTY >
7.7 order XML Element 8.7 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 collection members in
the collection's ordering. the collection's ordering.
<!ELEMENT order (member+) > <!ELEMENT order (ordermember+) >
7.8 ordermember XML Element 8.8 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 collection member in the collection's
ordering. ordering.
Value: An href containing the relative URI of the collection Value: An href containing a relative URI, and a description of its
member, and a description of its new position in the new position in the ordering. The href XML element is
ordering. The href XML element is defined in [WebDAV], defined in [WebDAV], Section 11.3.
Section 11.3.
<!ELEMENT ordermember (href, position) > <!ELEMENT ordermember (href, position) >
7.9 position XML Element 8.9 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 member 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
collection's members. collection's members.
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 before some other member of the collection, or after some
other member of the collection. other member of the collection.
<!ELEMENT position (first | last | before | after)> <!ELEMENT position (first | last | before | after)>
7.10 first XML Element 8.10 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. Describes the
collection member's position as first in the collection's collection member's position as first in the collection's
ordering. ordering.
Value: EMPTY Value: EMPTY
<!ELEMENT first EMPTY > <!ELEMENT first EMPTY >
7.11 last XML Element 8.11 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. Describes the
collection member's position as last in the collection's collection member's position as last in the collection's
ordering. ordering.
Value: EMPTY Value: EMPTY
<!ELEMENT last EMPTY > <!ELEMENT last EMPTY >
7.12 before XML Element 8.12 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. Describes the
collection member's position as coming before some other collection member's position as coming before some other
collection member in the collection's ordering. collection member 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 >
7.13 after XML Element 8.13 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. Describes the
collection member's position as coming after some other collection member's position as coming after some other
collection member in the collection's ordering. collection member 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 >
8 Extensions to the DAV:multistatus XML Element 9 Extensions to the DAV:response XML Element for Multi-Status Responses
As described in Section 3.12, the DAV:reftype property and the As described in Sections 4.5 and 4.6, the DAV:location property and the
DAV:reftarget 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 indicate that a problem is not with a 207 Multi-Status response, to allow clients to resubmit their requests
direct reference, but with its target resource. to the target resource of a redirect reference.
As described in Section 4.13, the DAV:reftype and DAV:reftarget
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
will be placed in a DAV:prop element associated with the href to which
they apply. This structure provides a framework for future extensions
by other standards that may need to include additional properties in
their 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, reftype?, reftarget?) | <!ELEMENT response (href, ((href*, status, prop?) | (propstat+)),
(propstat+)), responsedescription?) > responsedescription?) >
9 Capability Discovery 10 Capability Discovery
9.1 Using OPTIONS 10.1 Using OPTIONS
Since referencing and ordering are independent capabilities, a resource Since referencing and ordering are independent capabilities, a resource
MAY support either or both. A resource that provides referencing MUST MAY support either or both. A resource that provides referencing MUST
support redirect references, and MAY in addition support direct support redirect references, and MAY in addition support direct
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 two new methods: MKREF in support of
referencing, and ORDERPATCH in support of ordering. The response MUST referencing, and ORDERPATCH in support of ordering. The response MUST
indicate which of these methods the resource allows. In addition, the indicate which of these methods the resource allows. In addition, the
response MUST include the DAV-Collections header, listing those of the response MUST include the DAV header, as described in Sections 9.1 and
three collection-related capabilities the resource provides. Possible 15 of [WebDAV]. Three new compliance classes are defined here for use
values for the DAV-Collections header are DAV:basicref, DAV:directref, with the DAV header: basicref, directref, and orderedcoll.
and DAV:orderedcoll.
9.2 Example When responding to an OPTIONS request, only a collection or a null
resource can include orderedcoll in the value of the DAV header. By
including orderedcoll, the resource indicates that its immediate member
URIs can be ordered. It implies nothing about whether any collections
identified by its member URIs can be ordered.
When responding to an OPTIONS request, any type of resource can include
basicref or directref in the value of the DAV header. Including
basicref indicates that the server permits a redirect reference at the
request URI. Including directref indicates that the server permits a
direct reference at the request URI.
10.2 Example: Capability Discovery
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, MKREF, 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, MKREF, ORDERPATCH
DAV: 1, 2, basicref, directref, orderedcoll
DAV-Collections: DAV:basicref, DAV:directref, DAV:orderedcoll This response indicates that the resource /somecollection/ is level 1
and level 2 compliant, as defined in [WebDAV]. In addition,
This response indicates that the resource /somecollection/ provides /somecollection/ supports ordering and is in a part of the server
basic referencing, direct references, and ordered collections. namespace that allows creation of redirect and direct references. (In
light of the semantics of MKREF, the resource currently at
/somecollection/ would have to be deleted before a reference could be
created at that URI.)
10 Dependencies on Other Specifications 11 Dependencies on Other Specifications
TBD TBD
11 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 base WebDAV
protocol also apply to WebDAV collections. In addition, referential protocol also apply to WebDAV collections. In addition, referential
resources and ordered collections introduce several new security resources and ordered collections introduce several new security
concerns and increase the risk of some existing threats. These issues concerns and increase the risk of some existing threats. These issues
are detailed below. are detailed below.
11.1 Redirect Loops 12.1 Privacy Concerns
By creating references on a trusted server, it is possible for a hostile
agent to induce users to send private information to a target on a
different server. This risk is mitigated somewhat for redirect
references, 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.) 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
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 referential resources creates a new avenue for clients
to create loops accidentally or maliciously. If the referential to create loops accidentally or maliciously. If the referential
resource and its target are on the same server, the server may be able resource 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 requests that would create loops. See also [HTTP],
Section 10.3 "Redirection 3xx." Section 10.3 "Redirection 3xx."
11.2 References and Denial of Service 12.3 References and Denial of Service
The introduction of referential resources creates a new avenue for Denial of service attacks were already possible by posting URLs that
denial of service attacks. Clients can create heavily used references to were intended for limited use at heavily used Web sites. The
target locations that were not designed for heavy usage. 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.
11.3 Maintaining Referential Integrity May Reveal Private Locations 12.4 References May Reveal Private Locations
Although this specification does not require servers to maintain There are several ways that the referencing mechanisms described here
may reveal information about directory structures. First, the
DAV:reftarget property of every reference contains the URI of the target
resource. Anyone who has access to the reference can discover the
directory path that leads 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
some extent. Property-level access control could prevent users from
examining the DAV:reftarget property. (The Ref-Target header, which is
returned in most responses to requests on direct references, reveals the
same information, however.) In some environments, the owner of a
resource might be able to use access 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 referential integrity, it does not prevent them from doing so. If a
server updates a referenceís DAV:reftarget property when its target server updates a referenceís DAV:reftarget property when its target
resource is moved, there is the risk that a private location will be 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 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. by doing a COPY followed by a DELETE rather than a MOVE.
If the owner of the target also owns the direct reference to it, the Finally, if backpointers are maintained on the target resource, the
Hide-Target header can be used when creating the direct reference to owners of references face these same risks. The directory structures
prevent others from discovering the location of the target through that where references are located are revealed to anyone who has access to
reference. the DAV:references property on a target resource. Moving a reference
may reveal its new location to anyone with access to DAV:references on
its target resource.
11.4 DAV:references and Denial of Service 12.5 DAV:references and Denial of Service
If the server maintains the DAV:references property in response to If the server maintains the DAV:references property in response to
references created in other administrative domains, it is exposed to references 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 references to the
list. list.
11.5 DAV:references and Malicious Deletion of Resources 12.6 DAV:references and Malicious Deletion of Resources
Servers that support the DAV:references property should insure that Servers that support the DAV:references property should insure that
clients cannot create editable properties with the name DAV:references. clients cannot create editable properties with the name DAV:references.
An editable DAV:references property would constitute a security risk on An editable DAV:references property would constitute a security risk on
servers that enforce referential integrity by deleting references when servers that enforce referential integrity by deleting references when
their target is deleted. These servers could be tricked into deleting a 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 by listing it in the DAV:references property of some target
resource. resource.
11.6 Malicious Modifications of Ordering 12.7 Denial of Service and DAV:orderingtype
Particularly in large collections, moving a collection member to a
different position in the ordering can make it very difficult for users
to find.
11.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.
12 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
specification. This constraint ensures that the human-readable content specification. This constraint ensures that the human-readable content
of this specification complies with [Alvestrand]. of this specification complies with [Alvestrand].
skipping to change at line 1716 skipping to change at line 2667
For error reporting, [WebDAV] follows the convention of HTTP/1.1 status For error reporting, [WebDAV] follows the convention of HTTP/1.1 status
codes, including with each status code a short, English description of codes, including with each status code a short, English description of
the code (e.g., 423 Locked). Internationalized applications will ignore the code (e.g., 423 Locked). Internationalized applications will ignore
this message, and display an appropriate message in the user's language this message, and display an appropriate message in the user's language
and character set. and character set.
For rationales for these decisions and advice for application For rationales for these decisions and advice for application
implementors, see [WebDAV]. implementors, see [WebDAV].
13 IANA Considerations 14 IANA Considerations
TBD This document uses the namespaces defined by [WebDAV] for properties and
XML elements. All other IANA considerations mentioned in [WebDAV] also
apply to this document.
14 Copyright 15 Copyright
15 Intellectual Property To be supplied.
16 Acknowledgements 16 Intellectual Property
This draft has benefited from thoughtful discussion by Steve Carter, To be supplied.
Geoffrey Clemm, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Rajiv
Dulepet, David Durand, Chuck Fay, Roy Fielding, Yaron Goland, Fred Hitt,
Alex Hopmann, Marcus Jager, Chris Kaler, Rohit Khare, Daniel LaLiberte,
Steve Martin, Surendra Koduru Reddy, Sam Ruby, Bradley Sergeant, Nick
Shelness, John Stracke, John Tigue, John Turner, and others.
17 References 17 Acknowledgements
This draft has benefited from thoughtful discussion by Jim Amsden, Steve
Carter, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Rajiv
Dulepet, David Durand, Roy Fielding, Yaron Goland, Fred Hitt, Alex
Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare,
Daniel LaLiberte, Steve Martin, Surendra Koduru Reddy, Sam Ruby, Bradley
Sergeant, Nick Shelness, John Stracke, John Tigue, John Turner, and
others.
18 References
18.1 Normative References
[URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource
Identifiers (URI): Generic Syntax." RFC 2396. MIT/LCS, U.C. Irvine,
Xerox. August, 1998.
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement
Levels." RFC 2119, BCP 14. Harvard University. March, 1997.
[XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup
Language (XML)." World Wide Web Consortium Recommendation REC-xml-
19980210. http://www.w3.org/TR/1998/REC-xml-19980210.
[HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee,
"Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. UC Irvine, DEC,
MIT/LCS. January, 1997.
[WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D.
Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." Draft- Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." RFC 2518.
ietf-webdav-protocol-09. Internet Draft, work in progress. Microsoft, Microsoft, U.C. Irvine, Netscape, Novell. February, 1999.
U.C. Irvine, Netscape, Novell. November, 1998.
18.2 Informational References
[DASL] Saveen Reddy, D. Jensen, Surendra Reddy, R. Henderson, J. Davis, [DASL] Saveen Reddy, D. Jensen, Surendra Reddy, R. Henderson, J. Davis,
A. Babich, "DAV Searching & Locating." Draft-reddy-dasl-protocol-03. A. Babich, "DAV Searching & Locating." Draft-reddy-dasl-protocol-03.
Internet Draft, work in progress. Microsoft, Novell, Oracle, Netscape, Internet Draft, work in progress. Microsoft, Novell, Oracle, Netscape,
Xerox, Filenet. November, 1998. Xerox, Filenet. November, 1998.
[WebDAVReq] J. Slein, J. Davis, "Requirements for Advanced Collection [CollReq] J. Slein, J. Davis, "Requirements for Advanced Collection
Functionality in WebDAV." Draft-ietf-webdav-collection-reqts-02. Functionality in WebDAV." Draft-ietf-webdav-collection-reqts-02.
Internet Draft, work in progress. Xerox, 1998.
[HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee, Internet Draft, work in progress. Xerox. February, 1999.
"Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. UC Irvine, DEC,
MIT/LCS. January, 1997.
[XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup
Language (XML)." World Wide Web Consortium Recommendation REC-xml-
19980210. http://www.w3.org/TR/1998/REC-xml-19980210.
18 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 J. Davis
Xerox Corporation Xerox Corporation
3333 Coyote Hill Road 3333 Coyote Hill Road
Palo Alto, CA 94304 Palo Alto, CA 94304
Email: jdavis@parc.xerox.com Email: jdavis@parc.xerox.com
A. Babich T. Chihaya
FileNet Corporation DataChannel, Inc.
155 108th Ave. N.E., Suite 400
Bellevue, WA 98004
Email: Tyson@DataChannel.com
G. Clemm
Rational Software Corporation
20 Maguire Road
Lexington, MA 02173-3104
Email: gclemm@rational.com
C. Fay
FileNet Corporation
3565 Harbor Boulevard 3565 Harbor Boulevard
Costa Mesa, CA 92626-1420 Costa Mesa, CA 92626-1420
Email: ababich@filenet.com Email: cfay@filenet.com
E.J. Whitehead Jr. E.J. Whitehead Jr.
Dept. of Information and Computer Science Dept. of Information and Computer Science
University of California, Irvine University of California, Irvine
Irvine, CA 92697-3425 Irvine, CA 92697-3425
Email: ejw@ics.uci.edu Email: ejw@ics.uci.edu
19 Appendices A. Babich
FileNet Corporation
3565 Harbor Boulevard
Costa Mesa, CA 92626-1420
Email: ababich@filenet.com
19.1 Appendix 1 - Extensions to the WebDAV Document Type Definition 20 Appendices
<!--============= XML Elements from Section 7 =======================--> 20.1 Appendix 1: Extensions to the WebDAV Document Type Definition
<!--============= XML Elements from Section 8 =======================-->
<!ELEMENT reference EMPTY > <!ELEMENT reference EMPTY >
<!ELEMENT direct EMPTY > <!ELEMENT direct EMPTY >
<!ELEMENT redirect EMPTY > <!ELEMENT redirect EMPTY >
<!ELEMENT weak EMPTY > <!ELEMENT weak EMPTY >
<!ELEMENT location href>
<!ELEMENT unordered EMPTY > <!ELEMENT unordered EMPTY >
<!ELEMENT custom EMPTY > <!ELEMENT custom EMPTY >
<!ELEMENT order (member+) > <!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 >
<!--============= Property Elements from Section 6 ==================--> <!--============= Property Elements from Section 7 ==================-->
<!ELEMENT reftarget href> <!ELEMENT reftarget href>
<!ELEMENT refintegrity (weak)> <!ELEMENT refintegrity (weak | ANY)>
<!ELEMENT reftype (direct | redirect)> <!ELEMENT reftype (direct | redirect)>
<!ELEMENT references (href*)> <!ELEMENT references (href*)>
<!ELEMENT orderingtype (arbitrary | custom | href) > <!ELEMENT orderingtype (arbitrary | custom | href) >
<!--======== Changes to the DAV:multistatus Element from Section 8 ==--> <!--====== Changes to the DAV:response Element from Section 9 ====-->
<!ELEMENT response (href, ((href*, status, reftype?, reftarget?) | <!ELEMENT response (href, ((href*, status, prop?) | (propstat+)),
(propstat+)), responsedescription?) > responsedescription?) >
Expires May 10, 1999 20.2 Appendix 2: Summary of Referencing Headers Required in Responses
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/