--- 1/draft-ietf-webdav-collection-protocol-01.txt 2006-02-05 02:10:41.000000000 +0100 +++ 2/draft-ietf-webdav-collection-protocol-02.txt 2006-02-05 02:10:41.000000000 +0100 @@ -1,825 +1,1122 @@ - WEBDAV Working Group J. Slein, Xerox INTERNET DRAFT J. Davis, Xerox - A. Babich, FileNet + A. Babich, FileNet E.J. Whitehead Jr., UC Irvine - July 31, 1998 - Expires January 31, 1999 + November 10, 1998 +Expires May 10, 1999 WebDAV Advanced Collections Protocol Status of this Memo This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its - areas, and its working groups. Note that other groups may also - distribute working documents as Internet-Drafts. +documents of the Internet Engineering Task Force (IETF), its areas, and +its working groups. Note that other groups may also distribute working +documents as Internet-Drafts. - 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 time. It is inappropriate to use Internet-Drafts - as reference material or to cite them other than as "work in - progress". +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 +time. It is inappropriate to use Internet-Drafts as reference material +or to cite them other than as "work in progress". - To view the entire list of current Internet-Drafts, please check - the "1id-abstracts.txt" listing contained in the Internet-Drafts - Shadow 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). +To view the entire list of current Internet-Drafts, please check the +"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow +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 Distributed Authoring and Versioning (WebDAV) working group - at , which may be joined by sending a - message with subject "subscribe" to . +Distribution of this document is unlimited. Please send comments to the +Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject +"subscribe" to . Discussions of the WEBDAV working group are archived at URL: . Abstract The base WebDAV protocol [WebDAV] provides basic support for - collections. It defines a MKCOL method for creating collections - and specifies how other HTTP and WebDAV methods interact with - collections. It supports internal members of collections, which it - defines as members whose URIs are immediately relative to the URI - of the collection. +collections. It defines a MKCOL method for creating collections and +specifies how other HTTP and WebDAV methods interact with collections. +It supports internal members of collections, which it defines as members +whose URIs are immediately relative to the URI of the collection. - Many applications, however, need more powerful collections. There - are two areas in particular where more powerful functionality is - often needed: referential resources and ordering. +Many applications, however, need more powerful collections. There are +two areas in particular where more powerful functionality is often +needed: referential resources and ordering. - This draft specifies extensions to the base WebDAV protocol to - support these more powerful collections. +This draft specifies extensions to the base WebDAV protocol to support +these more powerful collections. Table of Contents - 1 Terminology 3 - 2 Introduction 4 - 3 Referential Resources 4 - 3.1 Scope 4 - 3.2 Overview 6 - 3.3 Creating Referential Resources 6 - 3.3.1 The MKREF Method 6 - 3.3.2 Status Codes 7 - 3.3.3 Example 8 - 3.4 Deleting Referential Resources 8 - 3.4.1 The DELREF Method 8 - 3.4.2 Status Codes 8 - 3.4.3 Example 8 - 3.4.4 Design Rationale 8 - 3.5 Listing Referential Members of a Collection 9 - 3.6 Other WebDAV Operations on Indirect References 9 - 3.7 HTTP Operations on Indirect References 10 - 3.8 Operations on Targets of References 11 - 4 Ordered Collections 11 - 4.1 Overview 11 - 4.2 Creating an Ordered Collection 11 - 4.2.1 Overview 11 - 4.2.2 Status Codes 12 - 4.2.3 Example 12 - 4.3 Setting the Position of a Collection Member 12 - 4.3.1 Overview 12 - 4.3.2 Status Codes 13 - 4.3.3 Examples 13 - 4.4 Changing the Semantics of a Collection Ordering 14 - 4.5 Changing the Position of a Collection Member 14 - 4.5.1 The ORDERPATCH Method 14 - 4.5.2 Status Codes 14 - 4.5.3 Example 14 - 4.5.4 Design Rationale 15 - 5 New Headers 16 - 5.1 Ref-Target Request Header 16 - 5.2 Ref-Integrity Request Header 16 - 5.3 Pass-Through Request Header 17 - 5.4 Resource-Type Response Header 17 - 5.5 Ordered Request Header 17 - 5.6 Position Request Header 18 - 6 New Properties 18 - 6.1 reftarget Property 18 - 6.2 refintegrity Property 18 - 6.3 passthrough Property 19 - 6.4 orderingtype Property 19 - 7 New XML Elements 20 - 7.1 reference XML Element 20 - 7.2 weak XML Element 20 - 7.3 arbitrary XML Element 20 - 7.4 order XML Element 20 - 7.5 member XML Element 20 - 7.6 position XML Element 21 - 7.7 first XML Element 21 - 7.8 last XML Element 21 - 7.9 before XML Element 21 - 7.10 after XML Element 22 - 8 Compliance 22 - 8.1 Class 3 22 - 8.2 Class 4 22 - 9 Dependencies on Other Specifications 22 - 10 Security Considerations 22 - 10.1 Redirect Loops 23 - 10.2 References and Denial of Service 23 - 10.3 Malicious Modifications of Ordering 23 - 10.4 Denial of Service and DAV:orderingtype 23 - 11 Internationalization Considerations 23 - 12 IANA Considerations 24 - 13 Copyright 24 - 14 Intellectual Property 24 - 15 Acknowledgements 24 - 16 References 24 - 17 Authors' Addresses 25 +1 Terminology ............................................... 3 +2 Introduction .............................................. 4 +3 Referential Resources ..................................... 4 +3.1 Scope ..................................................... 4 +3.2 Overview .................................................. 5 + +3.3 Creating Referential Resources ............................ 7 +3.3.1 The MKREF Method .......................................... 7 +3.3.2 Status Codes .............................................. 8 +3.3.3 Example ................................................... 8 +3.4 Deleting, Copying, and Moving Referential Resources ....... 9 +3.5 Listing Referential Members of a Collection ............... 9 +3.6 Other WebDAV Operations on Redirect Referential Resources . 9 +3.7 Other WebDAV Operations on Direct Referential Resources .. 10 +3.8 HTTP Operations on Redirect Referential Resources ........ 10 +3.9 HTTP Operations on Direct Referential Resources .......... 11 +3.10 Operations on Targets of Referential Resources ........... 12 +3.11 Discovering a Target’s References ........................ 12 +3.12 Behavior of Dangling Direct References ................... 13 +3.13 Summary of Referencing Headers Required in Responses ..... 16 +4 Ordered Collections ...................................... 16 +4.1 Overview ................................................. 16 +4.2 Creating an Ordered Collection ........................... 16 +4.2.1 Overview ................................................. 16 +4.2.2 Status Codes ............................................. 17 +4.2.3 Example .................................................. 17 +4.3 Setting the Position of a Collection Member .............. 17 +4.3.1 Overview ................................................. 18 +4.3.2 Status Codes ............................................. 18 +4.3.3 Examples ................................................. 18 +4.4 Changing the Semantics of a Collection Ordering .......... 19 +4.5 Changing the Position of a Collection Member ............. 19 +4.5.1 The ORDERPATCH Method .................................... 19 +4.5.2 Status Codes ............................................. 19 +4.5.3 Example .................................................. 19 +4.5.4 Design Rationale ......................................... 21 +5 New Headers .............................................. 21 +5.1 Ref-Target Entity Header ................................. 21 +5.2 Ref-Type Entity Header ................................... 22 +5.3 Ref-Integrity Entity Header .............................. 22 +5.4 Re-Direct Request Header ................................. 23 +5.5 Hide-Target Entity Header ................................ 23 +5.6 Resource-Type Entity Header .............................. 23 +5.7 Ordered Entity Header .................................... 23 +5.8 Position Request Header .................................. 24 +5.9 DAV-Collections Entity Header ............................ 24 +6 New Properties ........................................... 24 +6.1 reftarget Property ....................................... 25 +6.2 refintegrity Property .................................... 25 +6.3 reftype Property ......................................... 25 +6.4 references Property ...................................... 25 +6.5 orderingtype Property .................................... 26 +7 New XML Elements ......................................... 26 +7.1 reference XML Element .................................... 26 +7.2 direct XML Element ....................................... 26 +7.3 redirect XML Element ..................................... 26 +7.4 weak XML Element ......................................... 26 +7.5 unordered XML Element .................................... 27 +7.6 custom XML Element ....................................... 27 +7.7 order XML Element ........................................ 27 +7.8 ordermember XML Element .................................. 27 + +7.9 position XML Element ..................................... 28 +7.10 first XML Element ........................................ 28 +7.11 last XML Element ......................................... 28 +7.12 before XML Element ....................................... 28 +7.13 after XML Element ........................................ 28 +8 Extensions to the DAV:multistatus XML Element ............ 29 +9 Capability Discovery ..................................... 29 +9.1 Using OPTIONS ............................................ 29 +9.2 Example .................................................. 29 +10 Dependencies on Other Specifications ..................... 30 +11 Security Considerations .................................. 30 +11.1 Redirect Loops ........................................... 30 +11.2 References and Denial of Service ......................... 30 +11.3 Maintaining Referential Integrity May Reveal Private Locations30 +11.4 DAV:references and Denial of Service ..................... 30 +11.5 DAV:references and Malicious Deletion of Resources ....... 31 +11.6 Malicious Modifications of Ordering ...................... 31 +11.7 Denial of Service and DAV:orderingtype ................... 31 +12 Internationalization Considerations ...................... 31 +13 IANA Considerations ...................................... 31 +14 Copyright ................................................ 32 +15 Intellectual Property .................................... 32 +16 Acknowledgements ......................................... 32 +17 References ............................................... 32 +18 Authors' Addresses ....................................... 32 +19 Appendices ............................................... 33 +19.1 Appendix 1 - Extensions to the WebDAV Document Type Definition33 1 Terminology - The terminology used here follows and extends that in the base - WebDAV protocol specification [WebDAV]. +The terminology used here follows and extends that in the base WebDAV +protocol specification [WebDAV]. Collection A resource that contains member resources Member Resource A resource contained by a collection Referential Resource (or Reference) - A resource that has no content of its own, but rather is - a reference to another resource + A resource that has no content of its own, but rather is a + reference to another resource Ordinary Resource - A member resource that is not a reference to another resource + A resource that is not a reference to another resource Target Resource - The resource referenced by a referential member of a collection + The resource referenced by a referential resource Direct Reference - A reference that has the property that operations on it are - passed through to its target + A reference that is resolved by the server, giving the client the + illusion that it is operating directly on the target resource - Indirect Reference - A reference that has the property that operations on it do - not affect its target +Redirect Reference + A reference that must be resolved by the client Strong Reference A reference whose referential integrity is guaranteed by the server Weak Reference A reference whose referential integrity is not guaranteed by the server + Referential Integrity A server guarantees the integrity of a reference if it ensures - that the reference will not be broken, or enables the - reference's owner to ensure that the reference will not be - broken. + that the reference will not be broken, or enables the reference's + owner to ensure that the reference will not be broken. 2 Introduction - The simple collections that the base WebDAV specification supports - are powerful enough to be widely useful. They provide for the - hierarchical organization of resources, with mechanisms for - creating and deleting collections, copying and moving them, - locking them, adding resources to them and deleting resources from - them, and getting listings of their members. Delete, copy, move, - list, and lock operations can be applied recursively, so that a - client can operate on whole hierarchies with a single request. +The simple collections that the base WebDAV specification supports are +powerful enough to be widely useful. They provide for the hierarchical +organization of resources, with mechanisms for creating and deleting +collections, copying and moving them, locking them, adding resources to +them and deleting resources from them, and getting listings of their +members. Delete, copy, move, list, and lock operations can be applied +recursively, so that a client can operate on whole hierarchies with a +single request. - Many applications, however, need more powerful collections. There - are two areas in particular where more powerful functionality is - often needed: referential resources and ordering. +Many applications, however, need more powerful collections. There are +two areas in particular where more powerful functionality is often +needed: references and ordering. - Referential resources make it possible for many collections, on the - same or different servers, to share the same resource. Because - the collections share the resource by referencing it, only one - physical copy of the resource need exist, and any changes made in - the resource are visible from all the collections that reference - it. +References make it possible for many collections, on the same or +different servers, to share the same resource. Because the collections +share the resource by referencing it, only one physical copy of the +resource need exist, and any changes made in the resource are visible +from all the collections that reference it. - 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 completely independent of any properties - on the collection's member resources. Orderings based on - properties can be obtained using a search protocol [DASL], but - orderings not based on properties need some other mechanism. +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 +completely independent of any properties on the collection’s member +resources. Orderings based on properties can be obtained using a search +protocol [DASL], but orderings not based on properties need some other +mechanism. - Since these two areas are independent of each other, servers may - elect to comply with the Referential Resources section of this - specification or with the Ordered Collections section or both. - A server MUST advertise its compliance through its response to - an OPTIONS request, as specified in [WebDAV]. New values for the - DAV header are defined in Section 8 below to support this - requirement. +Since these two areas are independent of each other, servers may elect +to comply with the Referential Resources section of this specification +or with the Ordered Collections section or both. A server that supports +referencing MUST support redirect references, and MAY support direct +references. A server MUST advertise its compliance with particular +parts of this specification through its response to an OPTIONS request, +as specified in Section 9 below. 3 Referential Resources 3.1 Scope [WebDAVReq] distinguishes between "weak" references and "strong" - references, and also between "indirect" references and "direct" - references. This specification supports only weak references and - indirect references, but is designed so that it can be extended - to support strong references and direct references in the future. +references, and also between "redirect" references and "direct" +references. This specification supports weak references, direct +references, and redirect references, and is designed so that it can be +extended to support strong references in the future. - Strong references are references whose integrity is guaranteed by - the server; weak references are those whose integrity is not - guaranteed. Strong references and weak references are both useful - in different contexts. Some applications cannot tolerate broken - links. A software development application, for example, must be - able to rely on the integrity of references to component modules. - Such applications must be able to request strong references. Other - applications may want to reference target resources on multiple - servers, where referential integrity cannot be guaranteed, and may - be less concerned about possible broken references. +Strong references are references whose integrity is guaranteed by the +server; weak references are those whose integrity is not guaranteed. +Strong references and weak references are both useful in different +contexts. Some applications cannot tolerate broken links. A software +development application, for example, must be able to rely on the +integrity of references to component modules. Such applications must be +able to request strong references. Other applications may want to +reference target resources on multiple servers, where referential +integrity cannot be guaranteed, and may be less concerned about possible +broken references. Several considerations led to the decision not to support strong - references in the current specification. First, there are many - possible policies that applications and services might use to - enforce referential integrity. +references in the current specification. First, there are many possible +policies that applications and services might use to enforce referential +integrity. o Delete strong references when their targets are deleted. - o Decline to delete targets of strong references. +o Notify strong references when their targets have been deleted. +o Let owners of resources decide whether strong references to them are + allowed. - o Notify strong references when their targets have been - deleted. - - o Let owners of resources decide whether strong references to - them are allowed. +There appears to be no common practice in this area. Moreover, some of +the policies have significant security risks. - There appears to be no common practice in this area. Moreover, - some of the policies have significant security risks. +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 + server. +o A strong reference could be a security risk to the owner of the + reference by revealing secret locations on his server. +o The presence of strong references to resources on a server could make + it impossible to reclaim space on that server by moving or deleting + those target resources. - 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 server. +These considerations together led to the decision not to support strong +references in the short term. - o A strong reference could be a security risk to the owner of - the reference by revealing secret locations on his server. +3.2 Overview - o The presence of strong references to resources on a server - could make it impossible to reclaim space on that server - by moving or deleting those target resources. +A referential resource is a resource that has no content of its own, but +instead references another resource. The resource it references may be +in the same collection as the reference, or in any other collection. +This target resource may be a collection or a simple resource or another +reference, or any other sort of resource that may be defined in the +future. A resource may be the target of any number of referential +resources. To make it possible to distinguish references from ordinary +resources, a new value of the DAV:resourcetype property is defined here. +The DAV:resourcetype property of all references MUST have the value +DAV:reference. - These considerations together led to the decision not to support - strong references in the short term. +Redirect references are references that must be resolved 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. - Operations on indirect references do not affect their target - resources, whereas operations on direct references are passed - through to their targets. Both indirect and direct references may - be useful. Each of these types of references is implemented in - existing systems. Existing HTTP servers are capable of supporting - both types of references. In effect, indirect references give - clients access to the reference itself, and allow the reference to - bear properties. Direct references, once created, simplify access - to the target resource by hiding from clients the fact that there - is a reference mediating between the client and the target - resource. They also make access to the target more efficient, - eliminating a round trip required by indirect references to get the - URI of the target resource. +To resolve a redirect reference, the client retrieves the DAV:reftarget +property, whose value is the URI of the target resource. Every +reference, direct or redirect, MUST have the DAV:reftarget property. If +a client wishes to operate on the target resource of a redirect +reference, it resolves the reference, and then invokes the operation on +the target resource. - Again, it was believed that supporting direct references would be - too difficult in the short term. Although convenient, they add no - functionality beyond what is available through indirect references. - Existing systems often implement hybrids of direct and indirect - references, for which some operations are passed through to the - target while others are not. This fact muddies the issue of what - exactly WebDAV should support. It also suggests that the - definition of direct references as those for which operations are - passed through to their targets may not really capture a class of - references that are useful. [what else?] +The redirect reference appears to the client as an independent resource +with its own properties. Operations with the URI of the redirect +reference as their request-URI affect the reference, not its target +resource. - Consequently, it was decided not to support direct references in - the short term. +Direct references, in contrast, are resolved 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. -3.2 Overview +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 +is mediating between it and the target resource. The exceptions are +operations that affect membership in a collection rather than the state +of the target resource. At present, the operations that fall into this +category are DELETE, MOVE, and COPY. These operations are applied to +the reference itself rather than to its target, so that only the +collection containing the reference is affected. - A referential resource is a resource that has no content of its - own, but instead references another resource. The resource it - references may be in the same collection or anywhere else. This - target resource may be a collection or a simple resource or another - reference, or any other sort of resource that may be defined in the - future. A resource may be the target of any number of referential - resources. +The Re-Direct request header is also provided, to force an operation to +be applied to the direct reference itself rather than its target. In +effect, it makes the reference behave like a redirect reference for that +request. This header is particularly useful with PROPFIND, to allow +clients to view the reference’s own properties. - Since a referential resource is a resource, it can have properties - just like any other resource. These properties are completely - independent of the properties on its target resource. A new - DAV:reftarget property of referential resources has as its value - the URI of the target resource. +To distinguish between direct and redirect references, a new DAV:reftype +property is defined, with the values DAV:direct and DAV:redirect. Every +reference MUST have the DAV:reftype property. The DAV:reftype property +of a direct reference MUST have the value DAV:direct. The DAV:reftype +property of a redirect reference MUST have the value DAV:redirect. - To make it possible to distinguish referential resources from - ordinary resources, a new value of the DAV:resourcetype property - is defined here. The DAV:resourcetype property of all referential - resources MUST have the value reference. +Although strong references are not currently supported, a new +DAV:refintegrity property is defined in anticipation of future support +for strong references. DAV:refintegrity will allow clients to +distinguish between weak and strong references. All references MUST +have this property. Although the only value currently defined for +DAV:refintegrity is DAV:weak, other values may be defined in the future. - Although only weak, indirect references are currently supported, - two new DAV properties are defined in anticipation of future - support for strong references and direct references. These - properties, DAV:refintegrity and DAV:passthrough, will allow - clients to distinguish between weak and strong references, and - between indirect and direct references. All referential resources - MUST have these properties. Although the only value currently - defined for DAV:refintegrity is weak, other values may be defined - in the future. Although the only value currently defined for - DAV:passthrough is none, other values may be defined in the future. +***** If a server wants to enforce referential integrity outside this +protocol, a value of DAV:weak is misleading. 3.3 Creating Referential Resources 3.3.1 The MKREF Method - Referential resources are created using the MKREF method. The - request-URI of the MKREF request identifies the resource to be - created. The required Ref-Target header contains the URI of the - target resource. - - An optional Ref-Integrity request 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. +Referential resources are created using the MKREF method. The request- +URI of the MKREF request identifies the resource to be created. The +required Ref-Target header contains the URI of the target resource. - An optional Pass-Through request header is defined below, primarily - for future support for direct references. Currently, its value is - always empty, although other values may be used by private - agreement. The default value is empty if the header is not +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 +enforce referential integrity, or that it must not enforce referential +integrity for the new resource? We have a requirement that there be +some way to request the server not to enforce referential integrity for +a particular reference. You might also want to change from don’t- +enforce to enforce at different times in the life of the reference. + +An optional Ref-Type general header is defined below, with values +"DAV:direct" and "DAV:redirect". The default value is "DAV:redirect" if +the header is not present. + +The optional Hide-Target request header is defined below, to enable the +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 to specify where the new referential member is - to be placed in the collection's ordering. (This header can also - be used with PUT to create an ordinary collection member at a - specific position in the ordering.) +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 +used with PUT to create an ordinary resource at a specific position in +the collection ordering.) When a server processes a MKREF request, it MUST set the - DAV:resourcetype property (defined in [WebDAV]) of the new resource - to be DAV:reference. +DAV:resourcetype property (defined in [WebDAV]) of the new resource to +be DAV:reference. - When a server processes a MKREF request, it MUST set the - DAV:reftarget property to the URI of the target resource. +When a server processes a MKREF request, it MUST set the DAV:reftarget +property to the URI of the target resource. When a server processes a MKREF request, it MUST set the - DAV:refintegrity property and the DAV:passthrough property. +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 NOT use the Content-Length or Transfer-Encoding headers. (See - [HTTP].) +The client MUST NOT send any content with the MKREF request, and so MUST +NOT use the Content-Length or Transfer-Encoding headers. (See [HTTP].) - If a MKREF request is submitted for an existing resource, the - existing resource's content and headers will be overwritten. This - behavior is analogous to the behavior of the HTTP PUT method. Live - properties may 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 it from its previous - position, and then insert it at the requested position. +If a MKREF request is submitted for an existing resource, the existing +resource's content and headers will be overwritten. This behavior is +analogous to the behavior of the HTTP PUT method. Live properties may +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 - 201 Created - 200 OK: modified an existing resource - 409 Conflict: no resource at Ref-Target - unrecognized / unsupported value for Ref-Integrity - unrecognized / unsupported value for Pass-Through - 400 Bad Request: content not allowed - 409 Conflict: Position Before / After a URI that is not in this - collection - 400 Bad Request: Position Before / After self - 409 Conflict: Position header, but not an ordered collection - 425 Insufficient Space on Resource - 409 Conflict: Parent collection does not exist +201 (Created): The reference was successfully created. + +200 (OK): The reference was successfully created, replacing an existing +resource at the same location. + +400 (Bad Request): The client attempted to send content with the +request, or set an invalid value for the Ref-Target, Ref-Integrity, Ref- +Type, or Position header. + +409 (Conflict): Several conditions may produce this response. There may +be no resource at the location specified in Ref-Target, on a server that +prohibits dangling references. The request may be attempting to create +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 +not in the collection, or before or after itself. The request may be +attempting to position the reference in an unordered collection. + +***** These are not conflicts with the state of the resource at the +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: MKREF /~whitehead/dav/spec08.ref HTTP/1.1 HOST: www.ics.uci.edu Ref-Target: Response: HTTP/1.1 201 Created - 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 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 its target resource. Its DAV:refintegrity - property is set to the default value of DAV:weak. Its - DAV:passthrough property is set to the default value of EMPTY. +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 +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 +its target resource. Its DAV:refintegrity property is set to the +default value of DAV:weak. Its DAV:reftype property is set to the +default value of DAV:redirect. -3.4 Deleting Referential Resources +3.4 Deleting, Copying, and Moving Referential Resources -3.4.1 The DELREF Method +The DELETE method should be used to delete referential resources. For +both direct and redirect references, DELETE affects the reference +itself, and not its target. - The new DELREF method is used to delete referential resources. - DELREF on a referential resource has no effect on its target - resource. +A MOVE operation on a referential resource moves the referential +resource to a different location, but has no effect on the location of +its target. The DAV:reftarget property is unchanged after a MOVE unless +the Ref-Target header is used to change it. -3.4.2 Status Codes +A COPY operation on a referential resource copies the referential +resource, not its target resource, to another location. The +DAV:reftarget property of the destination resource is the same as the +DAV:reftarget of the source resource, unless the Ref-Target header is +used to change it. - 200 OK - 405 Method Not Allowed: Request-URI is not a reference - 404 Not Found: No resource at Request-URI +3.5 Listing Referential Members of a Collection -3.4.3 Example +Since a referential member of a collection is just a resource in the +collection, a listing of members of the collection shows referential +members along with ordinary members. That is, a WebDAV PROPFIND request +on a collection resource with Depth = 1 or infinity MUST return a +response XML element for each ordinary member and for each referential +member. - Request: +For a redirect reference, the properties returned by the PROPFIND are +the properties of the reference itself. If Depth = infinity in the +PROPFIND request, the server MUST NOT follow redirect references into +any collections to which they may refer. - DELREF /~whitehead/dav/spec08.ref HTTP/1.1 - HOST: www.ics.uci.edu +For a direct reference, the properties returned by the PROPFIND are the +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. - Response: +3.6 Other WebDAV Operations on Redirect Referential Resources - HTTP/1.1 200 OK +Operations on a redirect reference affect only the reference, and not +its target resource. - The referential resource /~whitehead/dav/spec08.ref has been - deleted, but its target resource still exists. +A LOCK operation on a redirect reference locks the reference, not its -3.4.4 Design Rationale +target. A LOCK on the collection with Depth = 1 or infinity locks any +redirect references that are members of the collection. It does not +lock the targets of those redirect references. - The HTTP DELETE method can be used to delete indirect references, - since by definition these references do not pass operations through - to their targets. +A PROPPATCH on a redirect reference modifies the properties of the +reference, not the properties of its target resource. - If direct references are supported in the future, however, a method - distinct from the HTTP DELETE method will be needed for deleting - the reference itself. Since direct references do pass operations - through to their targets, DELETE would delete the target resource - rather than the reference itself. +A PROPFIND on a redirect reference returns the properties of the +reference, not the properties of its target resource. - DELREF is being introduced now in anticipation of future needs, - and can be used in all cases where a reference is to be deleted. +3.7 Other WebDAV Operations on Direct Referential Resources -3.5 Listing Referential Members of a Collection +With the exception of DELETE, MOVE, and COPY, which were discussed +above, operations on direct references affect the target resource, not +the reference, unless the Re-Direct header is used. - Since a referential member of a collection is just a resource in - the collection, a listing of members of the collection shows - referential members along with ordinary members. That is, a WebDAV - PROPFIND request on a collection resource with Depth = 1 or - infinity MUST return a response XML element for each ordinary - member and for each referential member. +Unless the Re-Direct header is used, a LOCK operation on a direct +reference locks the target. A lock on a direct reference to a +collection locks the target collection. A lock on a collection with +Depth = 1 or infinity locks the targets of the direct references in the +collection. - If Depth = infinity in the PROPFIND request, the server MUST NOT - follow indirect references into any collections to which they may - refer. +Unless the Re-Direct header is used, a PROPPATCH on a direct reference +modifies the properties of its target resource, not the properties of +the reference itself. -3.6 Other WebDAV Operations on Indirect Referential Resources +Unless the Re-Direct header is used, a PROPFIND on a direct reference +returns the properties of its target resource, not the properties of the +reference itself. - By definition, operations on an indirect reference affect only the - reference, and not its target resource. Since only indirect - references are supported by this specification, WebDAV operations - that are applied to them affect only the referential resource, not - its target resource. +If the Re-Direct header is used with a LOCK, PROPPATCH, or PROPFIND +request on a direct reference, it behaves as if it were being applied to +a redirect reference, as specified in Section 3.6. - A LOCK operation on an indirect reference locks the referential - resource, not its target. A LOCK on the collection with - Depth = 1 or infinity locks the referential members along with all - the other members of the collection, but not the targets of the - indirect referential members. +3.8 HTTP Operations on Redirect Referential Resources - A PROPPATCH on an indirect referential resource modifies the - properties of the referential resource, not the properties of its - target resource. +Although existing HTTP clients cannot create referential resources, they +should be able to read collections created by reference-aware WebDAV +clients. They should be able to follow any references in those +collections to their targets. To make this possible, a server that +receives a GET or HEAD on a redirect reference MUST return a 302(Moved +Temporarily) status code. The server MUST follow [HTTP] Section 10.3.3 +"302 Moved Temporarily," but with these additional rules: - A PROPFIND on an indirect referential resource returns the - properties of the referential resource, not the properties of its - target resource. +o The Location header MUST contain the target URI of the reference. - A MOVE operation on an indirect referential resource moves the - referential resource to a different location, but has no effect on - the location of its target. The DAV:reftarget property is unchanged - after a MOVE unless the Ref-Target header is used to change it. +o The response MUST include all referencing entity headers that make + sense for redirect references: Ref-Type, Ref-Target, and Ref- + Integrity. - A COPY operation on an indirect referential resource copies the - referential resource, not its target resource, to another location. - The DAV:reftarget property of the destination resource is the same - as the DAV:reftarget of the source resource, unless the Ref-Target - header is used to change it. +o The response MUST also include those HTTP headers that make sense for + referential resources, at a minimum: Cache-Control, Age, ETag, + Expires, and Last-Modified. -3.7 HTTP Operations on Indirect Referential Resources +The second and third of these rules preserve normal GET and HEAD - Although existing HTTP clients cannot create referential resources, - they should be able to read collections created by Class 3 WebDAV - clients. They should be able to follow any references in those - collections to their targets. To make this possible, a server that - receives a GET or HEAD on an indirect reference MUST return a 302 - (Moved Temporarily) status code. The server MUST follow [HTTP] - Section 10.3.3 "302 Moved Temporarily," but with these additional - rules: +behavior for reference-aware WebDAV clients. - o The Location header MUST contain the target URI of the +POST cannot be applied to a redirect reference. A reference cannot +accept another entity as its subordinate. Depending upon the nature of +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 +reference with another, MKREF MUST be used. To replace a redirect +reference with an ordinary resource, the reference MUST first be deleted +with DELREF, after which a PUT MUST be used to create the ordinary +resource. + +Existing HTTP clients that do not understand referential resources need +to be accommodated, however. To enable these clients to operate +reasonably on redirect references, a server that receives a PUT request +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 a Resource-Type header with the - value "Reference". This header allows Class 3 WebDAV clients - to recognize the resource as a reference and understand the - reason for the redirection. +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. - o The response MUST also include those HTTP headers that make - sense for referential resources, at a minimum: Cache-Control, - Age, ETag, Expires, and Last-Modified. +o The response MUST include an entity body for display to users. The + entity body explains that the requested resource is a reference to + another resource, and allows the user to choose whether to replace + the target resource or to replace the reference. - POST cannot be applied to an indirect reference. A reference - cannot accept another entity as its subordinate. Depending upon - the nature of the target resource, however, it might make sense to - apply POST to the target. A server that receives a POST request - on an indirect 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 - Cache-Control, Age, ETag, Expires, or Last-Modified. +This last rule is needed for PUT, but not for GET, HEAD, or POST. Only +for PUT does it make sense for the user to confirm that the operation is +to be performed at the request-URI. GET or HEAD will already have +returned all useful information about the request-URI. POST makes no +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. - PUT cannot be applied to an indirect reference. To replace one - indirect reference with another, MKREF MUST be used. To replace an - indirect reference with an ordinary resource, the reference MUST - first be deleted with DELREF, after which a PUT MUST be used to - create the ordinary resource. +To enable existing HTTP clients to retrieve the capabilities of the +target resource, a server that receives an OPTIONS request on a redirect +reference MUST return a 302 (Moved Temporarily). At the same time, +reference-aware WebDAV clients may need to retrieve the capabilities of +the reference itself. Consequently, the server MUST provide a choice as +to whether the method should be applied to the reference or its target. +Consequently, the same rules apply for OPTIONS as for PUT above. - Existing HTTP clients that do not understand referential resources - need to be accommodated, however. To enable these clients to - operate reasonably on indirect references, a server that receives a - PUT request on an indirect 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: +3.9 HTTP Operations on Direct Referential Resources - o The Location response header MUST contain the target URI of - the reference. +GET, HEAD, PUT, POST, and OPTIONS on direct references are passed +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. - o The response MUST include a Resource-Type header, defined in - Section 5.n below, with the value "Reference". This header - allows Class 3 WebDAV clients to recognize the resource as a - reference and understand the reason for the redirection. +The Re-Direct request header may be used with GET, HEAD, or OPTIONS to +view the headers or capabilities of the reference, rather than its +target. If the Re-Direct header is used, the method’s behavior is as +described in Section 3.8. - o The response MUST include an entity body for display to users. - The entity body explains that the requested resource is a - reference to another resource, and allows the user to choose - whether to replace the target resource or to replace the - reference. +The Re-Direct request header must not be used with PUT or POST, which +cannot be applied to references. If a server receives a PUT or POST +request on a direct reference with the Re-Direct header, it MUST respond +with a 400 (Bad Request). - This last rule is needed for PUT, but not for GET, HEAD, or - POST. Only for PUT does it make sense for the user to confirm - that the operation is to be performed at the request-URI. GET or - HEAD will already have returned all useful information about the - request-URI. POST makes no sense for the indirect reference at the - request-URI. But the user might really want to replace the - indirect reference with the entity in the PUT request. +***** Confirm behavior for PUT / POST with Re-Direct. - Although the new DELREF method has been defined for deleting - references, DELETE can be used to delete an indirect reference. - Since by definition operations on an indirect reference affect the - reference, and not its target, DELETE will delete the indirect - reference and leave its target untouched. +3.10 Operations on Targets of Referential Resources -3.8 Operations on Targets of Referential Resources +In general, operations on targets of weak referential resources have no +effect on the referential resource. However, servers that choose to +maintain the integrity of references are free to make changes to the +state of references when moving or deleting their targets. - Operations on targets of weak, indirect referential resources have - no effect on the referential resource. +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 +maintaining referential integrity. Between the copy step and the delete +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 +new location. + +When deleting a target resource, a server MAY perform any internal +operations necessary to implement its policy on preserving referential +integrity. For example, it might delete any references to the deleted +target, or it might flag them as having a deleted target, or it might +replace references with copies of the target. + +3.11 Discovering a Target’s References + +An optional DAV:references property on the target resource provides a +list of referential resources whose DAV:reftarget property points to +that target resource. If present, DAV:references is a read-only +property, maintained by the server. By retrieving this property, a +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 +members. As for all DAV: properties, this specification is silent as to +how the DAV:references property is implemented on the server. + +The DAV:references property is expected to be supported mainly by +Document Management Systems (DMSs) and other servers that will maintain +the property only for references within their own domain. It is not in +general possible for a server to maintain the property for references on +other servers. If a reference on a different server points to the + +target, the server where the target is located is unlikely to know about +that reference. This protocol provides no mechanism for one server to +notify another of the creation of a reference to one of its resources. +Consequently, the list of references in DAV:reftarget may be incomplete. + +Rationale: A number of scenarios require clients to navigate from a +target resource to the references that point to it, and to the +collections that contain those references. This capability is +particularly important for DMSs, which may populate their collections +entirely by reference. Their clients may need to determine, for any +object in the DMS, what collections it belongs to. It is also important +in other contexts. For example, some servers enforce referential +integrity by refusing to delete any resource that is referenced by other +resources. In such an environment, the client must be able to discover +the references in order to delete them before attempting to delete the +target. + +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, +server implementors / administrators should balance the efficiencies it +provides in discovering references against the cost of maintaining the +property and the security risks enumerated in Sections 11.4 and 11.5. + +3.12 Behavior of Dangling Direct References + +***** Think about chains of direct references. + +GET and HEAD respond with 404 (Not Found), but the Ref-Type and Ref- +Target headers are included in the response, so that the client can tell +that it is the target, and not the reference, that was not found. (If +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 +specified by the reference’s DAV:reftarget property. + +POST fails with 404 (Not Found), since a nonexistent resource cannot +accept another resource as its subordinate. The Ref-Type and Ref-Target +headers are included in the response, so that the client can tell that +it is the target, and not the reference, that was not found. (If 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 +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.) + +PROPFIND responds with a 207 Multistatus, including a 404 (Not Found) 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]. + +For example, + +Request: + +PROPFIND /collection1/directref7 HTTP/1.1 +Host: www.somehost.com +Content-Type: text/xml +Content-Length: xxxx + + + + + + + + + +Response: + +HTTP/1.1 207 Multi-Status +Content-Type: text/xml +Content-Length: xxxx + + + + + http://www.somehost.com/collection1/directref7 + HTTP/1.1 404 Not Found + + + http://www.somehost.com/collection2/file19 + + + Target resource not +found. + + +PROPPATCH responds with a 207 Multistatus, including a 404 (Not Found) +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), +or could it just be a 404 (Not Found)? + +For example, + +Request: + +PROPPATCH /collection1/directref7 HTTP/1.1 +Host: www.somehost.com +Content-Type: text/xml +Content-Length: xxxx + + + + + + Pauloosie Padluq + South Baffin Carvers + + + + +Response: + +HTTP/1.1 207 Multi-Status +Content-Type: text/xml +Content-Length: xxxx + + + + + http://www.somehost.com/collection1/directref7 + HTTP/1.1 404 Not Found + + + http://www.somehost.com/collection2/file19 + + + Target resource not +found. + + +MOVE, COPY, and DELETE succeed. For MOVE and COPY, the reference at the +destination will be broken, just as the reference at the source was. + +If a single resource is being LOCKed or UNLOCKed, the response is a 404 +(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 +LOCKed or UNLOCKed, the response is a 207 (Multi-Status). The + +DAV:status element for the dangling reference is a 404 (Not Found). 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]. + +3.13 Summary of Referencing Headers Required in Responses + +This section summarizes the rules that determine which referencing +headers must be included in responses to requests on references. + +o Every response to a request on a reference MUST include the Ref-Type + header, so that the client knows that it was operating on a + reference, and whether the operation was applied to the reference + itself or to its target. + +o Every response to a request on a direct reference MUST include the + Ref-Target header, unless the reference was created with the Hide- + 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 + on a direct reference with the Re-Direct header) MUST include all the + referencing entity headers that make sense for redirect references: + Ref-Type, Ref-Target, and Ref-Integrity. 4 Ordered Collections 4.1 Overview - 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, 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 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 collection. Multiple - orderings of the same resources can be achieved by creating - multiple collections referencing those resources, and attaching a - different ordering to each collection. +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, +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 +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 +collection. Multiple orderings of the same resources can be achieved by +creating multiple collections referencing those resources, and attaching +a different ordering to each collection. - The server is responsible for enforcing these constraints on - orderings. The server MUST remove a resource from the ordering - when it is removed from the collection. The server MUST add a - resource to the ordering when it is added to the collection. +The server is responsible for enforcing these constraints on orderings. +The server MUST remove a resource from the ordering when it is removed +from the collection. The server MUST add a resource to the ordering when +it is added to the collection. - When responding to a PROPFIND on a collection, the server MUST - order the response elements according to the ordering defined - on the collection. +When responding to a PROPFIND on a collection, the server MUST order the +response elements according to the ordering defined on the collection. 4.2 Creating an Ordered Collection 4.2.1 Overview - 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 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 ordered, it may omit the Ordered header, or use - it with the value "DAV:arbitrary". +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 +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 +ordered, it may omit the Ordered header, or use it with the value +"DAV:unordered". - Every collection MUST have the new DAV:orderingtype property, - which indicates whether the collection is ordered and, if so, - identifies the semantics of the ordering. A value of DAV:arbitrary - indicates that that collection is not ordered. That is, the client - cannot depend on the repeatability of the ordering of results from - a PROPFIND request. Otherwise the value of DAV:orderingtype is an - href that SHOULD point to a resource that contains a definition of - the semantics of the ordering, allowing a human user or software - package to insert new collection members into the ordering - intelligently. +Every collection MUST have the new DAV:orderingtype property, which +indicates whether the collection is ordered and, if so, identifies the +semantics of the ordering. A value of DAV:unordered indicates that that +collection is not ordered. That is, the client cannot depend on the +repeatability of the ordering of results from a PROPFIND request. For +collections that are ordered, DAV:orderingtype SHOULD be set to an href +that identifies the semantics of the ordering, allowing a human user or +software package to insert new collection members into the ordering +intelligently. Although the href MAY point to a resource that contains +a definition of the semantics of the ordering, clients are discouraged +from accessing that resource, in order to avoid overburdening its +server. The DAV:orderingtype property MAY be set to DAV:custom to +indicate that the collection is to be ordered, but the semantics of the +ordering is not being advertised. - If the Ordered header is present on a MKCOL request, the server - MUST set 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 request as if it had an Ordered header with - the value "DAV:arbitrary", meaning that the collection is not - ordered. If the collection is ordered, the server MUST respond to - PROPFIND requests on the collection using the specified ordering. +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 +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", +meaning that the collection is not ordered. If the collection is +ordered, the server MUST respond to PROPFIND requests on the collection +using the specified ordering. 4.2.2 Status Codes No new error conditions are introduced. 4.2.3 Example Request: MKCOL /theNorth/ HTTP/1.1 Host: www.server.org Ordered: Response: HTTP/1.1 201 Created In this example, a new, ordered collection was created. Its - 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 consult the semantics to - determine how to position the new members in the ordering. +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 4.3.1 Overview - When a new member is added to a collection with MKREF, PUT, COPY, - or MOVE, 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, or after some other collection member - in the collection's ordering. +When a new member is added to a collection with MKREF, PUT, COPY, MOVE, +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 +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, or after some other collection member in the +collection's ordering. - The server MUST insert the new member into the ordering at the - location specified in the Position header, if one is present (and - if the collection is ordered); otherwise, it MUST append the new - member to the end of the ordering (if the collection is ordered). - If a PUT or MKREF causes an existing resource to be replaced, and - if the Position header is absent, the server MUST leave the member - at its previous position in the collection ordering. If the - Position header is present, the server MUST remove the member from - its previous position, and then insert it at the requested - position. +The server MUST insert the new member into the ordering at the location +specified in the Position header, if one is present (and if the +collection is ordered); otherwise, it MUST append the new member to the +end of the ordering (if the collection is ordered). If a PUT or MKREF +causes an existing resource to be replaced, and if the Position header +is absent, the server MUST leave the member at its previous position in +thee collection ordering. If the Position header is present, the server +MUST remove the member from its previous position, and then insert it at +the requested position. 4.3.2 Status Codes - 201 Created - 409 Conflict: Before / After a URI that is not in this collection - 400 Bad Request: Before / After self - 405 Method Not Allowed: Not an ordered collection +201 (Created): The resource was successfully created. + +409 (Conflict): The request may be attempting to position the resource +before or after a resource that is not in the collection, or before or +after itself, or it may be attempting to position the resource in an +unordered collection. 4.3.3 Examples Request: MKREF /~whitehead/dav/spec08.ref HTTP/1.1 HOST: www.ics.uci.edu Ref-Target: Position: After Response: HTTP/1.1 201 Created - 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 identified by the Ref-Target header. The Position header - in this example caused the server to set its position in the - ordering of the /~whitehead/dav/ collection immediately after the - requirements.html resource. +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 +identified by the Ref-Target header. The Position header in this +example caused the server to set its position in the ordering of the +/~whitehead/dav/ collection immediately after the requirements.html +resource. Request: MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 Host: www.ics.uci.edu Destination: + Position: First Response: HTTP/1.1 409 Conflict - In this case, the server returned a 409 Conflict status code - because the /~whitehead/dav/ collection is an unordered collection. - - Consequently, the server was unable to satisfy the Position - header. +In this case, the server returned a 409 Conflict status code because the +/~whitehead/dav/ collection is an unordered collection. Consequently, +the server was unable to satisfy the Position header. 4.4 Changing the Semantics of a Collection Ordering - After a collection has been created, a client can change its - ordering semantics, or change an ordered collection to an unordered - collection or vice versa, by using PROPPATCH to change the value of - its DAV:orderingtype property. The client is then responsible for - updating the ordering of the collection members according to the - new semantics. PROPPATCH is defined in [WebDAV], Section 7.2. +After a collection has been created, a client can change its ordering +semantics, or change an ordered collection to an unordered collection or +vice versa, by using PROPPATCH to change the value of its +DAV:orderingtype property. The client is then responsible for updating +the ordering of the collection members according to the new semantics. +PROPPATCH is defined in [WebDAV], Section 7.2. 4.5 Changing the Position of a Collection Member 4.5.1 The ORDERPATCH Method - To change the position of a collection member in the collection's - ordering, the client MUST use an ORDERPATCH request with a request - body containing an order XML element. The request-URI of an - ORDERPATCH request is the URI of the collection whose ordering is - to be updated. The order XML element identifies the member - resource whose position is to be changed, and describes its new - position in the ordering. The new position can be specified as - first in the ordering, last in the ordering, before some other - collection member in the ordering, or after some other collection - member in the ordering. +To change the positions of collection members in the collection's +ordering, the client MUST use an ORDERPATCH request with a request body +containing an order XML element. The request-URI of an ORDERPATCH +request is the URI of the collection whose ordering is to be updated. +The order XML element identifies the member resources whose positions +are to be changed, and describes their new positions in the ordering. +Each new position can be specified as first in the ordering, last in the +ordering, before some other collection member in the ordering, or after +some other collection member in the ordering. The server MUST apply the +changes in the order they appear in the order element. 4.5.2 Status Codes - Although the protocol currently allows only a single change to be - requested with ORDERPATCH, it is anticipated that this may change - in the future. Consequently, the server MUST return a 207 - Multi-Status response, as defined in [WebDAV]. +Since multiple changes can be requested in a single ORDERPATCH request, +the server MUST return a 207 Multi-Status response, as defined in +[WebDAV]. - Within the 207 Multi-Status response, the following status codes - are possible: +Within the 207 Multi-Status response, the following status codes are +possible: - 200 OK - 409 Conflict: Before / After a URI that is not in this collection - 409 Conflict: href doesn't point to a member of this collection - 400 Bad Request: only one change allowed - 400 Bad Request: Before / After self - 405 Method Not Allowed: Not an ordered collection - 405 Method Not Allowed: Not a collection - (It's ok to reposition to the same position) +200 (OK): The change in ordering was successfully made. + +409 (Conflict): An attempt was made to position the resource before or +after a resource that is not in the collection, or before or after +itself, or an attempt was made to position the resource in an unordered +collection. + +A request to reposition a collection member to the same place in the +ordering is not an error. 4.5.3 Example Consider a collection /coll-1/ with members ordered as follows: nunavut.map nunavut.img baffin.map baffin.desc baffin.img iqaluit.map nunavut.desc - iqaluit.desc iqaluit.img +iqaluit.desc Request: ORDERPATCH /coll-1/ HTTP/1.1 Host: www.nunanet.com Content-Type: text/xml Content-Length: xxx - - - + + nunavut.desc nunavut.map - + + + iqaluit.img + + + + Response: HTTP/1.1 207 Multi-Status Content-Type: text/xml Content-Length: xxx - - + http://www.nunanet.com/coll-1/nunavut.desc HTTP/1.1 200 OK + + http://www.nunanet.com/coll-1/iqaluit.img + HTTP/1.1 200 OK + - In this example, after the request has been processed, the - map of nunavut is the first member in the collection's ordering: +In this example, after the request has been processed, the collection's +ordering is as follows: nunavut.map nunavut.desc nunavut.img baffin.map baffin.desc baffin.img iqaluit.map iqaluit.desc iqaluit.img @@ -818,528 +1115,669 @@ nunavut.desc nunavut.img baffin.map baffin.desc baffin.img iqaluit.map iqaluit.desc iqaluit.img 4.5.4 Design Rationale + The decision to introduce the new ORDERPATCH method was made after - investigating the possibility of using the existing MOVE method - with a Position header. The use of MOVE initially looked - appealingly simple: +investigating the possibility of using the existing MOVE method with a +Position header. The use of MOVE initially looked appealingly simple: MOVE /root/coll-1/foo HTTP/1.1 Host: www.somehost.com Destination: Position: First Unfortunately, several features of the semantics of MOVE make it unsuitable for changing the position of a collection member in the collection's ordering. First, [WebDAV] defines MOVE as logically - equivalent to a copy followed by a delete of the source resource. - This definition makes it impossible to MOVE a resource to a - destination URL that is the same as the source URL. The resource - would be deleted rather than moved. Second, [WebDAV] states that - when moving a resource to a destination where a resource already - exists, the Overwrite header must be "T", and in this case the - server must DELETE the resource at the destination before - performing the MOVE. Again, this makes it impossible to MOVE - a resource to the same location. Finally, [WebDAV] states that +equivalent to a copy followed by a delete of the source resource. This +definition makes it impossible to MOVE a resource to a destination URL +that is the same as the source URL. The resource would be deleted +rather than moved. Second, [WebDAV] states that when moving a resource +to a destination where a resource already exists, the Overwrite header +must be "T", and in this case the server must DELETE the resource at the +destination before performing the MOVE. Again, this makes it impossible +to MOVE a resource to the same location. Finally, [WebDAV] states that locks are lost on a MOVE, an outcome that seems undesirable in this case. - The decision to allow only a single change to be described in a - PROPPATCH request was made in order to accommodate many existing - systems that do not allow multiple changes to be requested at once. - However, the protocol design is extensible to support multiple - requests in the future. - - In particular, the decision to define a new order XML element for - ORDERPATCH was made for the sake of extensibility. Although the - current definition of the order XML element allows only a single - change in the ordering per ORDERPATCH request, using an XML element - keeps open the option of later allowing multiple changes to be - described in a single ORDERPATCH request. Similarly, a - Multi-Status response is used in order to keep open the option of - multiple changes in a single request in the future. - 5 New Headers -5.1 Ref-Target Request Header +***** Decide which headers intended for MKREF also can be used with +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" ":" Coded-url Coded-url is defined in [WebDAV], Section 8.4. - The Ref-Target request header is used with the MKREF method to - identify the target resource of the new referential resource being - created. It is a required header in MKREF requests. This header - may also be used with COPY and MOVE requests to change the target - of the destination reference. +The Ref-Target header is used with the MKREF method to identify the +target resource of the new referential resource being created. It is a +required header in MKREF requests. This header may also be used with +COPY and MOVE requests to change the target of the destination +reference. + +Servers MUST include the Ref-Target header in the following responses +unless the Hide-Target header was used when the reference was created, +in which case the Ref-Target header MUST NOT be included in responses: + +o Responses to GET and HEAD requests on redirect references + +o Responses to all requests on direct references, unless the request + included the Re-Direct header + +5.2 Ref-Type Entity Header + +Ref-Type = "Ref-Type" ":" ("DAV:direct" | "DAV:redirect") + +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. 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: + +o Responses to all requests on both direct and redirect references + +5.3 Ref-Integrity Entity Header -5.2 Ref-Integrity Request Header Ref-Integrity = "Ref-Integrity" ":" ("DAV:weak") - The Ref-Integrity header is defined to allow future support for - strong 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 [should not? must not?] enforce referential integrity for +The Ref-Integrity header is defined to allow future support for strong +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. +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. -5.3 Pass-Through Request Header +***** Again, does DAV:weak mean that the server need not maintain +referential integrity, or that it must not? - Pass-Through = "Pass-Through" ":" "" +Servers MUST include the Ref-Integrity header in the following +responses: - The Pass-Through header is defined to allow future support for - direct references. Indirect references do not pass operations - through to their target resources, so for them the value of - the Pass-Through header is empty. Direct references pass all - operations through to their target resources. Other types of - references may pass certain operations through, while others may - affect the reference itself. Since only indirect references are - supported today, the only value currently defined for Pass-Through - is empty. 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 - Pass-Through header with the value empty. 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:passthrough - property MUST be treated like any other live property, as - specified in [WebDAV] sections 7.8.2 and 7.9.1. +o Responses to GET and HEAD requests on redirect references (or on + direct references if the request included the Re-Direct header) -5.4 Resource-Type Response Header +5.4 Re-Direct Request Header - Resource-Type = "Resource-Type" ":" ["DAV:collection" | - "DAV:reference" | ""] +Re-Direct = "Re-Direct" ":" - The Resource-Type response header contains the value of the - DAV:resourcetype property. It is used with 302 responses to PUT, - POST, GET, or HEAD requests on referential resources to indicate to - the client that the reason for the redirection is that the - request-URI pointed to a referential resource. +The optional Re-Direct header can be used on any request to a direct +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). -5.5 Ordered Request Header +***** Confirm behavior for exception cases. - Ordered = "Ordered" ":" ("DAV:arbitrary" | Coded-url) +***** What if there is a chain of direct references? Suppose I want to +see the properties of the second reference in the chain - how would I do +that? - The Ordered request header may be used with MKCOL to request that - the new collection be ordered and to specify its ordering - semantics. A value of "DAV:arbitrary" indicates that the - collection is not ordered. That is, the client cannot depend on - the repeatability of the ordering of results from a PROPFIND - request. A Coded-url value indicates that the collection is - ordered, and identifies the semantics of the ordering. The - Coded-url SHOULD point to a resource that contains a definition of - the semantics of the ordering, allowing a human user or software - package to insert new collection members into the ordering - intelligently. +5.5 Hide-Target Entity Header - 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 "DAV:arbitrary". +Hide-Target = "Hide-Target" ":" -5.6 Position Request Header +The optional Hide-Target header is for use when creating a new direct +reference. It specifies that the URI of the target resource is to be +hidden. If this header is used when creating a direct reference, the +server MUST NOT include the Ref-Target header in any response to a +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 +after a reference has been created, we need a DAV:hidetarget property to +allow that. + +5.6 Resource-Type Entity Header + +Resource-Type = "Resource-Type" ":" ["DAV:collection" | "DAV:reference" + |""] + +The Resource-Type header contains the value of the DAV:resourcetype +property. It is used with LOCK, MOVE, or COPY to set or change the +resource type. + +***** Not needed unless you can create a reference with LOCK, or change +resource type with MOVE or COPY. + +5.7 Ordered Entity Header + +Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) + +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 +"DAV:unordered" indicates that the collection is not ordered. That is, +the client cannot depend on the repeatability of the ordering of results +from a PROPFIND request. A Coded-url value indicates that the collection +is ordered, and identifies the semantics of the ordering, allowing a +human user or software package to insert new collection members into the +ordering intelligently. The Coded-url MAY point to a resource that +contains a definition of the semantics of the ordering. A value of +"DAV:custom" indicates that the collection is to be ordered, but the +semantics of the ordering is not being advertised. + +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 +"DAV:unordered". + +5.8 Position Request Header Position = "Position" ":" ("First" | "Last" | (("Before" | "After") Coded-url)) - The Position header may be used with MKREF, PUT, COPY, or MOVE to +The Position header may be used with MKREF, PUT, COPY, MOVE, or LOCK to tell the server where in the collection ordering to position the resource being added to the collection. It may be used for both ordinary and referential members. - If the Coded-url is a relative URL, it is interpreted relative to - the collection in which the resource is being created. +If the Coded-url is a relative URL, it is interpreted relative to the +collection in which the resource is being created. If the Position request header is not used, then: - If the request is replacing an existing resource, the server - MUST preserve the present ordering. +If the request is replacing an existing resource, the server MUST +preserve the present ordering. - If the request is adding a new member to the collection, the - server MUST append the new member to the end of the ordering - (if the collection is ordered). +If the request is adding a new member to the collection, the server MUST +append the new member to the end of the ordering (if the collection is +ordered). + +5.9 DAV-Collections Entity Header + +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 Name: reftarget Namespace: DAV: - Purpose: A required property of referential resources that - provides an efficient way for clients to discover - the URI of the target resource. This is a readonly - property, whose value can only be set by using the - Ref-Target header with a MKREF, COPY, or MOVE - request. +Purpose: A required property of referential resources that provides + an efficient way for clients to discover the URI of the + target resource. This is a read-only property, whose value + can only be set by using the Ref-Target header with a MKREF, + COPY, or MOVE request. Value: URI of the target resource. 6.2 refintegrity Property + Name: refintegrity Namespace: DAV: - Purpose: A required property of a referential resource that - indicates whether the server guarantees referential - integrity for that reference. The refintegrity - property is defined to allow future support for - strong references. The only value currently - defined for refintegrity is weak, which means that +Purpose: A required property of a referential resource that indicates + whether the server guarantees referential integrity for that + reference. The refintegrity property is defined to allow + future support for strong references. The only value + currently defined for refintegrity is weak, which means that the server need not [does not?] enforce referential - integrity for the reference. Other values may be - used by private agreement between the client and - server. This is a readonly property, whose value - can only be set by using the Ref-Integrity header - with a MKREF, COPY, or MOVE request. + integrity for the reference. Other values may be used by + private agreement between the client and server. This is a + readonly property, whose value can only be set by using the + Ref-Integrity header with a MKREF, COPY, or MOVE request. Value: weak -6.3 passthrough Property +6.3 reftype Property - Name: passthrough +Name: reftype Namespace: DAV Purpose: A required property of a referential resource that - indicates what operations are passed through to its - target resource. The passthrough property is - defined to allow future support for direct - references, which pass all operations through to - their targets. This specification currently - supports only indirect references, which do not - pass any operations through to their targets. The - only value currently defined for passthrough is - EMPTY. Other values may be used by private - agreement between the client and server. This is - a read-only property, whose value can only be set - by using the Pass-Through header with a MKREF, - COPY, or MOVE request. - Value: EMPTY + identifies the reference as direct or redirect. This is a + read-only property, whose value can only be set by using + the Ref-Type header with a MKREF, COPY, or MOVE request. +Value: direct | redirect - + -6.4 orderingtype Property +6.4 references Property + +Name: references +Namespace: DAV: +Purpose: Enables clients to discover, for any target resource, what + references point to it and what collections contain it by + reference. This is an optional property. If present, it is + a read-only property, maintained by the server. +Value: List of the URIs of the references that point to the target + resource. + + + +6.5 orderingtype Property Name: orderingtype Namespace: DAV: - Purpose: Indicates whether the collection is ordered and, if - so, uniquely identifies the semantics of the - ordering being used. SHOULD also provide an - explanation of the semantics in human and / or - machine-readable form. At a minimum, this allows - human users who add members to the collection to +Purpose: Indicates whether the collection is ordered and, if so, + uniquely identifies the semantics of the ordering being + used. May also point to an explanation of the semantics in + human and / or machine-readable form. At a minimum, this + allows human users who add members to the collection to understand where to position them in the ordering. - Value: arbitrary for an unordered collection, or a URI - that uniquely identifies the semantics of the - collection's ordering. The URI SHOULD point to - a definition of the ordering semantics. +Value: unordered for an unordered collection, or a URI that + uniquely identifies the semantics of the collection's + ordering. The URI MAY point to a definition of the ordering + semantics. The value custom may be used for a collection + that is to be ordered, but for which the semantics are not + being advertised. - + 7 New XML Elements 7.1 reference XML Element Name: reference Namespace: DAV: - Purpose: A new value of the DAV:resourcetype property that - identifies its resource as a referential resource. - The DAV:resourcetype property of a referential - resource MUST have this value. +Purpose: A new value of the DAV:resourcetype property that identifies + its resource as a referential resource. The + DAV:resourcetype property of a referential resource MUST + have this value. Value: EMPTY -7.2 weak XML Element +7.2 direct XML Element + +Name: direct +Namespace: DAV: +Purpose: A value for the DAV:reftype property that identifies its + resource as a direct reference. +Value: EMPTY + + + +7.3 redirect XML Element + +Name: redirect +Namespace: DAV: +Purpose: A value for the DAV:reftype property that identifies its + resource as a redirect reference. +Value: EMPTY + + + +7.4 weak XML Element Name: weak Namespace: DAV: - Purpose: The only value currently defined for the - DAV:refintegrity property. It means that the - server need not [does not?] enforce referential - integrity for the reference to which the property - belongs. +Purpose: The only value currently defined for the DAV:refintegrity + property. It means that the server need not [does not?] + enforce referential integrity for the reference to which the + property belongs. Value: EMPTY -7.3 arbitrary XML Element +7.5 unordered XML Element - Name: arbitrary +Name: unordered Namespace: DAV: - Purpose: A value of the DAV:orderingtype property that - indicates that the collection is not ordered. That - is, the client cannot depend on the repeatability - of the ordering of results from a PROPFIND request. +Purpose: A value of the DAV:orderingtype property that indicates that + the collection is not ordered. That is, the client cannot + depend on the repeatability of the ordering of results from + a PROPFIND request. Value: EMPTY - + -7.4 order XML Element +7.6 custom XML Element + +Name: custom +Namespace: DAV: +Purpose: A value of the DAV:orderingtype property that indicates that + the collection is ordered, but the semantics of the ordering + are not being advertised. +Value: EMPTY + + + +7.7 order XML Element Name: order - Namespace: DAV - Purpose: For use with the new ORDERPATCH method. Describes - a change to be made in a collection ordering. - Value: A description of the new position of a collection - member in the collection's ordering. +Namespace: DAV: +Purpose: For use with the new ORDERPATCH method. Describes a change + to be made in a collection ordering. +Value: A description of the new positions of collection members in + the collection's ordering. - + -7.5 member XML Element - Name: member - Namespace: DAV - Purpose: Occurs in the order XML Element, and describes the - new position of a single collection member in the - collection's ordering. - Value: An href containing the relative URI of the - collection member, and a description of its new - position in the ordering. The href XML element is - defined in [WebDAV], Section 11.3. +7.8 ordermember XML Element - +Name: ordermember +Namespace: DAV: +Purpose: Occurs in the order XML Element, and describes the new + position of a single collection member in the collection's + ordering. +Value: An href containing the relative URI of the collection + member, and a description of its new position in the + ordering. The href XML element is defined in [WebDAV], + Section 11.3. -7.6 position XML Element + + +7.9 position XML Element Name: position - Namespace: DAV - Purpose: Occurs in the member XML element. Describes the - new position in a collection's ordering of one of - the collection's members. +Namespace: DAV: +Purpose: Occurs in the member XML element. Describes the new + position in a collection's ordering of one of the + collection's members. Value: The new position can be described as first in the - collection's ordering, last in the collection's - ordering, before some other member of the - collection, or after some other member of the - collection. + collection's ordering, last in the collection's ordering, + before some other member of the collection, or after some + other member of the collection. -7.7 first XML Element +7.10 first XML Element Name: first - Namespace: DAV +Namespace: DAV: Purpose: Occurs in the position XML element. Describes the - collection member's position as first in the - collection's ordering. + collection member's position as first in the collection's + ordering. Value: EMPTY -7.8 last XML Element +7.11 last XML Element Name: last - Namespace: DAV +Namespace: DAV: Purpose: Occurs in the position XML element. Describes the - collection member's position as last in the - collection's ordering. + collection member's position as last in the collection's + ordering. Value: EMPTY -7.9 before XML Element +7.12 before XML Element Name: before - Namespace: DAV +Namespace: DAV: Purpose: Occurs in the position XML element. Describes the - collection member's position as coming before some - other collection member in the collection's - ordering. + collection member's position as coming before some other + collection member in the collection's ordering. Value: href of the member it precedes in the ordering -7.10 after XML Element +7.13 after XML Element Name: after - Namespace: DAV +Namespace: DAV: + Purpose: Occurs in the position XML element. Describes the - collection member's position as coming after some - other collection member in the collection's - ordering. + collection member's position as coming after some other + collection member in the collection's ordering. Value: href of the member it follows in the ordering -8 Compliance +8 Extensions to the DAV:multistatus XML Element - Section 14 of [Goland et al, 1998] defined a DAV header for use - when responding to OPTIONS requests. This header provides a way - for clients to discover which parts of WebDAV a resource supports. - The WebDAV specifications define numbered compliance classes - corresponding to collections of related functions that resources - may support. When the server receives an OPTIONS request, it lists - the classes that the request-URI supports in the DAV response - header. +As described in Section 3.12, the DAV:reftype property and the +DAV:reftarget property 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. - Since this specification defines two independent sets of - functionality, it defines two new compliance classes. A WebDAV - server may support neither, one or the other, or both for any - resource. +Consequently, the definition of the DAV:response XML element changes to +the following: -8.1 Class 3 + - This new compliance class indicates compliance with Section 3 - "Referential Resources" of this specification. Servers that comply - with Section 3 MUST list this class in the DAV response header - when they respond to an OPTIONS request. +9 Capability Discovery -8.2 Class 4 +9.1 Using OPTIONS - This new compliance class indicates compliance with Section 4 - "Ordered Collections" of this specification. Servers that comply - with Section 4 MUST list this class in the DAV response header - when they respond to an OPTIONS request. +Since referencing and ordering are independent capabilities, a resource +MAY support either or both. A resource that provides referencing MUST +support redirect references, and MAY in addition support direct +references. A response to an OPTIONS request MUST indicate which of +these capabilities the resource supports. -9 Dependencies on Other Specifications +This specification defines two new methods: MKREF in support of +referencing, and ORDERPATCH in support of ordering. The response MUST +indicate which of these methods the resource allows. In addition, the +response MUST include the DAV-Collections header, listing those of the +three collection-related capabilities the resource provides. Possible +values for the DAV-Collections header are DAV:basicref, DAV:directref, +and DAV:orderedcoll. + +9.2 Example + +Request: + +OPTIONS /somecollection/ HTTP/1.1 +HOST: somehost.org + +Response: + +HTTP/1.1 200 OK +Date: Tue, 20 Jan 1998 20:52:29 GMT +Connection: close +Accept-Ranges: none +Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, +PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, ORDERPATCH +Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, +PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, ORDERPATCH + +DAV-Collections: DAV:basicref, DAV:directref, DAV:orderedcoll + +This response indicates that the resource /somecollection/ provides +basic referencing, direct references, and ordered collections. + +10 Dependencies on Other Specifications TBD -10 Security Considerations +11 Security Considerations This section is provided to detail issues concerning security implications of which WebDAV applications need to be aware. All of the security considerations of HTTP/1.1 and the base WebDAV - protocol also apply to WebDAV collections. In addition, - referential resources and ordered collections introduce several - new security concerns and increase the risk of some existing - threats. These issues are detailed below. +protocol also apply to WebDAV collections. In addition, referential +resources and ordered collections introduce several new security +concerns and increase the risk of some existing threats. These issues +are detailed below. -10.1 Redirect Loops +11.1 Redirect Loops Although redirect loops were already possible in HTTP 1.1, the - introduction of referential resources creates a new avenue for - clients to create loops accidentally or maliciously. If the - referential 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], Section 10.3 "Redirection 3xx." +introduction of referential resources creates a new avenue for clients +to create loops accidentally or maliciously. If the referential +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], +Section 10.3 "Redirection 3xx." -10.2 References and Denial of Service +11.2 References and Denial of Service - The introduction of referential resources creates a new avenue - for denial of service attacks. Clients can create heavily used - references to target locations that were not designed for heavy - usage. +The introduction of referential resources creates a new avenue for +denial of service attacks. Clients can create heavily used references to +target locations that were not designed for heavy usage. -10.3 Malicious Modifications of Ordering +11.3 Maintaining Referential Integrity May Reveal Private Locations - Particularly in large collections, moving a collection member to - a different position in the ordering can make it very difficult - for users to find. +Although this specification does not require servers to maintain +referential integrity, it does not prevent them from doing so. If a +server updates a reference’s DAV:reftarget property when its target +resource is moved, there is the risk that a private location will be +revealed in the new value of DAV:reftarget. Clients can avoid this risk +by doing a COPY followed by a DELETE rather than a MOVE. -10.4 Denial of Service and DAV:orderingtype +If the owner of the target also owns the direct reference to it, the +Hide-Target header can be used when creating the direct reference to +prevent others from discovering the location of the target through that +reference. - There may be some risk of denial of service at sites that are - advertised in the DAV:orderingtype property of collections. - However, it is anticipated that widely-deployed applications will - use hard-coded values for frequently-used ordering semantics - rather than looking up the semantics at the location specified by - DAV:orderingtype. +11.4 DAV:references and Denial of Service -11 Internationalization Considerations +If the server maintains the DAV:references property in response to +references created in other administrative domains, it is exposed to +hostile attempts to make it devote resources to adding references to the +list. - This specification follows the practices of [WebDAV] in encoding - all human-readable content using XML [XML] and in the treatment - of names. Consequently, this specification complies with the - IETF Character Set Policy [Alvestrand]. +11.5 DAV:references and Malicious Deletion of Resources - WebDAV applications MUST support the character set tagging, - character set encoding, and the language tagging functionality of - the XML specification. This constraint ensures that the human- - readable content of this specification complies with [Alvestrand]. +Servers that support the DAV:references property should insure that +clients cannot create editable properties with the name DAV:references. +An editable DAV:references property would constitute a security risk on +servers that enforce referential integrity by deleting references when +their target is deleted. These servers could be tricked into deleting a +resource by listing it in the DAV:references property of some target +resource. - As in [WebDAV}, names in this specification fall into three - categories: names of protocol elements such as methods and - headers, names of XML elements, and names of properties. Naming - of protocol elements follows the precedent of HTTP, using English - names encoded in USASCII for methods and headers. The names of - XML elements used in this specification are English names encoded - in UTF-8. +11.6 Malicious Modifications of Ordering - For error reporting, [WebDAV] follows the convention of HTTP/1.1 - status codes, including with each status code a short, English - description of the code (e.g., 423 Locked). Internationalized - applications will ignore this message, and display an appropriate - message in the user's language and character set. +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 +in the DAV:orderingtype property of collections. However, it is +anticipated that widely-deployed applications will use hard-coded values +for frequently-used ordering semantics rather than looking up the +semantics at the location specified by DAV:orderingtype. + +12 Internationalization Considerations + +This specification follows the practices of [WebDAV] in encoding all +human-readable content using XML [XML] and in the treatment of names. +Consequently, this specification complies with the IETF Character Set +Policy [Alvestrand]. + +WebDAV applications MUST support the character set tagging, character +set encoding, and the language tagging functionality of the XML +specification. This constraint ensures that the human-readable content +of this specification complies with [Alvestrand]. + +As in [WebDAV}, names in this specification fall into three categories: +names of protocol elements such as methods and headers, names of XML +elements, and names of properties. Naming of protocol elements follows +the precedent of HTTP, using English names encoded in USASCII for +methods and headers. The names of XML elements used in this +specification are English names encoded in UTF-8. + +For error reporting, [WebDAV] follows the convention of HTTP/1.1 status +codes, including with each status code a short, English description of +the code (e.g., 423 Locked). Internationalized applications will ignore +this message, and display an appropriate message in the user's language +and character set. For rationales for these decisions and advice for application implementors, see [WebDAV]. -12 IANA Considerations +13 IANA Considerations TBD -13 Copyright +14 Copyright -14 Intellectual Property +15 Intellectual Property -15 Acknowledgements +16 Acknowledgements - This draft has benefited from thoughtful discussion by - Steve Carter, Ellis Cohen, Spencer Dawkins, Rajiv Dulepet, - Chuck Fay, Roy Fielding, Yaron Goland, Fred Hitt, Alex Hopmann, - Marcus Jager, Rohit Khare, Daniel LaLiberte, Steve Martin, - Surendra Koduru Reddy, Sam Ruby, Bradley Sergeant, Nick Shelness, - John Stracke, John Tigue, John Turner, and others. +This draft has benefited from thoughtful discussion by Steve Carter, +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. -16 References +17 References - [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. - Faizi, S. R. Carter, D. Jensen, "Extensions for Distributed - Authoring on the World Wide Web - WebDAV." Draft-ietf-webdav- - protocol-08. Internet Draft, work in progress. Microsoft, - U.C. Irvine, Netscape, Novell. April, 1998. +[WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. +Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." Draft- +ietf-webdav-protocol-09. Internet Draft, work in progress. Microsoft, +U.C. Irvine, Netscape, Novell. November, 1998. - [DASL] Saveen Reddy, D. Jensen, Surendra Reddy, - R. Henderson, J. Davis, A. Babich, "DAV Searching & Locating." - Draft-reddy-dasl-protocol-02. Internet Draft, work in progress. - Microsoft, Novell, Oracle, Netscape, Xerox, Filenet. June, 1998. +[DASL] Saveen Reddy, D. Jensen, Surendra Reddy, R. Henderson, J. Davis, +A. Babich, "DAV Searching & Locating." Draft-reddy-dasl-protocol-03. +Internet Draft, work in progress. Microsoft, Novell, Oracle, Netscape, +Xerox, Filenet. November, 1998. - [WebDAVReq] J. Slein, J. Davis, "Requirements for Advanced - Collection Functionality in WebDAV." Draft-ietf-webdav-collection- - reqts-02. Internet Draft, work in progress. Xerox, 1998. +[WebDAVReq] J. Slein, J. Davis, "Requirements for Advanced Collection +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, "Hypertext Transfer Protocol -- HTTP/1.1." - RFC 2068. UC Irvine, DEC, MIT/LCS. January, 1997. +[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. [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. +Language (XML)." World Wide Web Consortium Recommendation REC-xml- +19980210. http://www.w3.org/TR/1998/REC-xml-19980210. -17 Authors' Addresses +18 Authors' Addresses J. Slein Xerox Corporation 800 Phillips Road, 105-50C Webster, NY 14580 - Email: slein@wrc.xerox.com +Email: jslein@crt.xerox.com J. Davis Xerox Corporation 3333 Coyote Hill Road Palo Alto, CA 94304 Email: jdavis@parc.xerox.com A. Babich FileNet Corporation + 3565 Harbor Boulevard Costa Mesa, CA 92626-1420 Email: ababich@filenet.com E.J. Whitehead Jr. Dept. of Information and Computer Science University of California, Irvine Irvine, CA 92697-3425 Email: ejw@ics.uci.edu @@ -1336,11 +1774,39 @@ 3565 Harbor Boulevard Costa Mesa, CA 92626-1420 Email: ababich@filenet.com E.J. Whitehead Jr. Dept. of Information and Computer Science University of California, Irvine Irvine, CA 92697-3425 Email: ejw@ics.uci.edu - Expires January 31, 1999 +19 Appendices + +19.1 Appendix 1 - Extensions to the WebDAV Document Type Definition + + + + + + + + + + + + + + + + + + + + + + + + +Expires May 10, 1999