idnits 2.17.1 draft-ietf-webdav-collection-protocol-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == There are 11 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 32 longer pages, the longest (page 1) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 120 instances of lines with control characters in the document. ** The abstract seems to contain references ([WebDAV]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 8 instances of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 213: '...referencing MUST support redirect refe...' RFC 2119 keyword, line 214: '...ences. A server MUST advertise its co...' RFC 2119 keyword, line 274: '... of all references MUST have the value...' RFC 2119 keyword, line 280: '...bDAV referencing MUST provide redirect...' RFC 2119 keyword, line 284: '...ect or redirect, MUST have the DAV:ref...' (82 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 10, 1999) is 9118 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Alvestrand' is mentioned on line 1677, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'WebDAV' -- Possible downref: Non-RFC (?) normative reference: ref. 'DASL' -- Possible downref: Non-RFC (?) normative reference: ref. 'WebDAVReq' ** Obsolete normative reference: RFC 2068 (ref. 'HTTP') (Obsoleted by RFC 2616) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 11 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 WEBDAV Working Group J. Slein, Xerox 2 INTERNET DRAFT J. Davis, Xerox 3 A. Babich, FileNet 4 E.J. Whitehead Jr., UC Irvine 5 November 10, 1998 6 Expires May 10, 1999 8 WebDAV Advanced Collections Protocol 10 Status of this Memo 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its areas, and 14 its working groups. Note that other groups may also distribute working 15 documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or made obsolete by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference material 20 or to cite them other than as "work in progress". 22 To view the entire list of current Internet-Drafts, please check the 23 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 24 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), 25 ftp.nis.garr.it (Southern Europe),munnari.oz.au (Pacific Rim), 26 ftp.ietf.org (US EastCoast), or ftp.isi.edu (US West Coast). 28 Distribution of this document is unlimited. Please send comments to the 29 Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject 31 "subscribe" to . 33 Discussions of the WEBDAV working group are archived at URL: 34 . 36 Abstract 38 The base WebDAV protocol [WebDAV] provides basic support for 39 collections. It defines a MKCOL method for creating collections and 40 specifies how other HTTP and WebDAV methods interact with collections. 41 It supports internal members of collections, which it defines as members 42 whose URIs are immediately relative to the URI of the collection. 44 Many applications, however, need more powerful collections. There are 45 two areas in particular where more powerful functionality is often 46 needed: referential resources and ordering. 48 This draft specifies extensions to the base WebDAV protocol to support 49 these more powerful collections. 51 Table of Contents 53 1 Terminology ............................................... 3 54 2 Introduction .............................................. 4 55 3 Referential Resources ..................................... 4 56 3.1 Scope ..................................................... 4 57 3.2 Overview .................................................. 5 58 3.3 Creating Referential Resources ............................ 7 59 3.3.1 The MKREF Method .......................................... 7 60 3.3.2 Status Codes .............................................. 8 61 3.3.3 Example ................................................... 8 62 3.4 Deleting, Copying, and Moving Referential Resources ....... 9 63 3.5 Listing Referential Members of a Collection ............... 9 64 3.6 Other WebDAV Operations on Redirect Referential Resources . 9 65 3.7 Other WebDAV Operations on Direct Referential Resources .. 10 66 3.8 HTTP Operations on Redirect Referential Resources ........ 10 67 3.9 HTTP Operations on Direct Referential Resources .......... 11 68 3.10 Operations on Targets of Referential Resources ........... 12 69 3.11 Discovering a Target�s References ........................ 12 70 3.12 Behavior of Dangling Direct References ................... 13 71 3.13 Summary of Referencing Headers Required in Responses ..... 16 72 4 Ordered Collections ...................................... 16 73 4.1 Overview ................................................. 16 74 4.2 Creating an Ordered Collection ........................... 16 75 4.2.1 Overview ................................................. 16 76 4.2.2 Status Codes ............................................. 17 77 4.2.3 Example .................................................. 17 78 4.3 Setting the Position of a Collection Member .............. 17 79 4.3.1 Overview ................................................. 18 80 4.3.2 Status Codes ............................................. 18 81 4.3.3 Examples ................................................. 18 82 4.4 Changing the Semantics of a Collection Ordering .......... 19 83 4.5 Changing the Position of a Collection Member ............. 19 84 4.5.1 The ORDERPATCH Method .................................... 19 85 4.5.2 Status Codes ............................................. 19 86 4.5.3 Example .................................................. 19 87 4.5.4 Design Rationale ......................................... 21 88 5 New Headers .............................................. 21 89 5.1 Ref-Target Entity Header ................................. 21 90 5.2 Ref-Type Entity Header ................................... 22 91 5.3 Ref-Integrity Entity Header .............................. 22 92 5.4 Re-Direct Request Header ................................. 23 93 5.5 Hide-Target Entity Header ................................ 23 94 5.6 Resource-Type Entity Header .............................. 23 95 5.7 Ordered Entity Header .................................... 23 96 5.8 Position Request Header .................................. 24 97 5.9 DAV-Collections Entity Header ............................ 24 98 6 New Properties ........................................... 24 99 6.1 reftarget Property ....................................... 25 100 6.2 refintegrity Property .................................... 25 101 6.3 reftype Property ......................................... 25 102 6.4 references Property ...................................... 25 103 6.5 orderingtype Property .................................... 26 104 7 New XML Elements ......................................... 26 105 7.1 reference XML Element .................................... 26 106 7.2 direct XML Element ....................................... 26 107 7.3 redirect XML Element ..................................... 26 108 7.4 weak XML Element ......................................... 26 109 7.5 unordered XML Element .................................... 27 110 7.6 custom XML Element ....................................... 27 111 7.7 order XML Element ........................................ 27 112 7.8 ordermember XML Element .................................. 27 113 7.9 position XML Element ..................................... 28 114 7.10 first XML Element ........................................ 28 115 7.11 last XML Element ......................................... 28 116 7.12 before XML Element ....................................... 28 117 7.13 after XML Element ........................................ 28 118 8 Extensions to the DAV:multistatus XML Element ............ 29 119 9 Capability Discovery ..................................... 29 120 9.1 Using OPTIONS ............................................ 29 121 9.2 Example .................................................. 29 122 10 Dependencies on Other Specifications ..................... 30 123 11 Security Considerations .................................. 30 124 11.1 Redirect Loops ........................................... 30 125 11.2 References and Denial of Service ......................... 30 126 11.3 Maintaining Referential Integrity May Reveal Private Locations30 127 11.4 DAV:references and Denial of Service ..................... 30 128 11.5 DAV:references and Malicious Deletion of Resources ....... 31 129 11.6 Malicious Modifications of Ordering ...................... 31 130 11.7 Denial of Service and DAV:orderingtype ................... 31 131 12 Internationalization Considerations ...................... 31 132 13 IANA Considerations ...................................... 31 133 14 Copyright ................................................ 32 134 15 Intellectual Property .................................... 32 135 16 Acknowledgements ......................................... 32 136 17 References ............................................... 32 137 18 Authors' Addresses ....................................... 32 138 19 Appendices ............................................... 33 139 19.1 Appendix 1 - Extensions to the WebDAV Document Type Definition33 141 1 Terminology 143 The terminology used here follows and extends that in the base WebDAV 144 protocol specification [WebDAV]. 146 Collection 147 A resource that contains member resources 149 Member Resource 150 A resource contained by a collection 152 Referential Resource (or Reference) 153 A resource that has no content of its own, but rather is a 154 reference to another resource 156 Ordinary Resource 157 A resource that is not a reference to another resource 159 Target Resource 160 The resource referenced by a referential resource 162 Direct Reference 163 A reference that is resolved by the server, giving the client the 164 illusion that it is operating directly on the target resource 166 Redirect Reference 167 A reference that must be resolved by the client 169 Strong Reference 170 A reference whose referential integrity is guaranteed by the 171 server 173 Weak Reference 174 A reference whose referential integrity is not guaranteed by the 175 server 177 Referential Integrity 178 A server guarantees the integrity of a reference if it ensures 179 that the reference will not be broken, or enables the reference's 180 owner to ensure that the reference will not be broken. 182 2 Introduction 184 The simple collections that the base WebDAV specification supports are 185 powerful enough to be widely useful. They provide for the hierarchical 186 organization of resources, with mechanisms for creating and deleting 187 collections, copying and moving them, locking them, adding resources to 188 them and deleting resources from them, and getting listings of their 189 members. Delete, copy, move, list, and lock operations can be applied 190 recursively, so that a client can operate on whole hierarchies with a 191 single request. 193 Many applications, however, need more powerful collections. There are 194 two areas in particular where more powerful functionality is often 195 needed: references and ordering. 197 References make it possible for many collections, on the same or 198 different servers, to share the same resource. Because the collections 199 share the resource by referencing it, only one physical copy of the 200 resource need exist, and any changes made in the resource are visible 201 from all the collections that reference it. 203 It is useful for many applications to be able to impose an ordering on a 204 collection. Orderings may be based on property values, but they may be 205 completely independent of any properties on the collection�s member 206 resources. Orderings based on properties can be obtained using a search 207 protocol [DASL], but orderings not based on properties need some other 208 mechanism. 210 Since these two areas are independent of each other, servers may elect 211 to comply with the Referential Resources section of this specification 212 or with the Ordered Collections section or both. A server that supports 213 referencing MUST support redirect references, and MAY support direct 214 references. A server MUST advertise its compliance with particular 215 parts of this specification through its response to an OPTIONS request, 216 as specified in Section 9 below. 218 3 Referential Resources 220 3.1 Scope 221 [WebDAVReq] distinguishes between "weak" references and "strong" 222 references, and also between "redirect" references and "direct" 223 references. This specification supports weak references, direct 224 references, and redirect references, and is designed so that it can be 225 extended to support strong references in the future. 227 Strong references are references whose integrity is guaranteed by the 228 server; weak references are those whose integrity is not guaranteed. 229 Strong references and weak references are both useful in different 230 contexts. Some applications cannot tolerate broken links. A software 231 development application, for example, must be able to rely on the 232 integrity of references to component modules. Such applications must be 233 able to request strong references. Other applications may want to 234 reference target resources on multiple servers, where referential 235 integrity cannot be guaranteed, and may be less concerned about possible 236 broken references. 238 Several considerations led to the decision not to support strong 239 references in the current specification. First, there are many possible 240 policies that applications and services might use to enforce referential 241 integrity. 243 o Delete strong references when their targets are deleted. 244 o Decline to delete targets of strong references. 245 o Notify strong references when their targets have been deleted. 246 o Let owners of resources decide whether strong references to them are 247 allowed. 249 There appears to be no common practice in this area. Moreover, some of 250 the policies have significant security risks. 252 o Moving a target of strong references could be a security risk to the 253 owner of the target by revealing secret locations on the target's 254 server. 255 o A strong reference could be a security risk to the owner of the 256 reference by revealing secret locations on his server. 257 o The presence of strong references to resources on a server could make 258 it impossible to reclaim space on that server by moving or deleting 259 those target resources. 261 These considerations together led to the decision not to support strong 262 references in the short term. 264 3.2 Overview 266 A referential resource is a resource that has no content of its own, but 267 instead references another resource. The resource it references may be 268 in the same collection as the reference, or in any other collection. 269 This target resource may be a collection or a simple resource or another 270 reference, or any other sort of resource that may be defined in the 271 future. A resource may be the target of any number of referential 272 resources. To make it possible to distinguish references from ordinary 273 resources, a new value of the DAV:resourcetype property is defined here. 274 The DAV:resourcetype property of all references MUST have the value 275 DAV:reference. 277 Redirect references are references that must be resolved by the client. 278 They are simple for servers to implement, straightforward for clients to 279 use, and have only limited security implications. Any server that 280 complies with WebDAV referencing MUST provide redirect references. 282 To resolve a redirect reference, the client retrieves the DAV:reftarget 283 property, whose value is the URI of the target resource. Every 284 reference, direct or redirect, MUST have the DAV:reftarget property. If 285 a client wishes to operate on the target resource of a redirect 286 reference, it resolves the reference, and then invokes the operation on 287 the target resource. 289 The redirect reference appears to the client as an independent resource 290 with its own properties. Operations with the URI of the redirect 291 reference as their request-URI affect the reference, not its target 292 resource. 294 Direct references, in contrast, are resolved by the server. They give 295 the client the illusion that it is operating directly on the target 296 resource. These references are more complex for the server to 297 implement, and raise additional security issues. Consequently, servers 298 are not required to provide direct references in order to be compliant 299 with WebDAV referencing. 301 The default behavior of a direct reference is to apply most operations 302 directly to its target, so that the client is not aware that a reference 303 is mediating between it and the target resource. The exceptions are 304 operations that affect membership in a collection rather than the state 305 of the target resource. At present, the operations that fall into this 306 category are DELETE, MOVE, and COPY. These operations are applied to 307 the reference itself rather than to its target, so that only the 308 collection containing the reference is affected. 310 The Re-Direct request header is also provided, to force an operation to 311 be applied to the direct reference itself rather than its target. In 312 effect, it makes the reference behave like a redirect reference for that 313 request. This header is particularly useful with PROPFIND, to allow 314 clients to view the reference�s own properties. 316 To distinguish between direct and redirect references, a new DAV:reftype 317 property is defined, with the values DAV:direct and DAV:redirect. Every 318 reference MUST have the DAV:reftype property. The DAV:reftype property 319 of a direct reference MUST have the value DAV:direct. The DAV:reftype 320 property of a redirect reference MUST have the value DAV:redirect. 322 Although strong references are not currently supported, a new 323 DAV:refintegrity property is defined in anticipation of future support 324 for strong references. DAV:refintegrity will allow clients to 325 distinguish between weak and strong references. All references MUST 326 have this property. Although the only value currently defined for 327 DAV:refintegrity is DAV:weak, other values may be defined in the future. 329 ***** If a server wants to enforce referential integrity outside this 330 protocol, a value of DAV:weak is misleading. 332 3.3 Creating Referential Resources 334 3.3.1 The MKREF Method 336 Referential resources are created using the MKREF method. The request- 337 URI of the MKREF request identifies the resource to be created. The 338 required Ref-Target header contains the URI of the target resource. 340 An optional Ref-Integrity general header is defined below, primarily for 341 future support for strong references. The only value currently defined 342 for this header is "DAV:weak", although other values may be used by 343 private agreement. "DAV:weak" is the default value if the header is not 344 present. 346 ***** Does Ref-Integrity = DAV:weak mean that the server need not 347 enforce referential integrity, or that it must not enforce referential 348 integrity for the new resource? We have a requirement that there be 349 some way to request the server not to enforce referential integrity for 350 a particular reference. You might also want to change from don�t- 351 enforce to enforce at different times in the life of the reference. 353 An optional Ref-Type general header is defined below, with values 354 "DAV:direct" and "DAV:redirect". The default value is "DAV:redirect" if 355 the header is not present. 357 The optional Hide-Target request header is defined below, to enable the 358 creator of a direct reference to specify that the DAV:reftarget property 359 be hidden from clients. If the Hide-Target header is not present, the 360 server MUST assume that the DAV:reftarget property is not to be hidden. 361 If the Hide-Target header is used with Ref-Type header set to 362 DAV:redirect, the server MUST ignore the Hide-Target header. The Ref- 363 Target header MUST never be returned in response to any request for a 364 direct reference created with the Hide-Target header. 366 ***** How useful is this really? Isn�t it the owner of the target (not 367 of the reference) who wants to control whether the location of the 368 target is hidden? True, we have a scenario where the person creating 369 the reference wants to hide the location of the target, but that�s 370 because the owner of the reference and the owner of the target are the 371 same person in that example. 373 An optional Position request header supports ordered collections by 374 allowing the client creating a reference to specify where the new member 375 is to be placed in the collection's ordering. (This header can also be 376 used with PUT to create an ordinary resource at a specific position in 377 the collection ordering.) 379 When a server processes a MKREF request, it MUST set the 380 DAV:resourcetype property (defined in [WebDAV]) of the new resource to 381 be DAV:reference. 383 When a server processes a MKREF request, it MUST set the DAV:reftarget 384 property to the URI of the target resource. 386 When a server processes a MKREF request, it MUST set the 387 DAV:refintegrity property and the DAV:reftype property based on the 388 values of the Ref-Integrity and Ref-Type headers. 390 The client MUST NOT send any content with the MKREF request, and so MUST 391 NOT use the Content-Length or Transfer-Encoding headers. (See [HTTP].) 393 If a MKREF request is submitted for an existing resource, the existing 394 resource's content and headers will be overwritten. This behavior is 395 analogous to the behavior of the HTTP PUT method. Live properties may 396 get new values at the server's discretion; dead properties will retain 397 their existing values. If the Position header is absent in this case 398 and the collection is ordered, the server MUST leave the member at its 399 previous position in the collection ordering. If the Position header is 400 present and the collection is ordered, the server MUST remove the member 401 from its previous position, and then insert it at the requested 402 position. 404 3.3.2 Status Codes 406 201 (Created): The reference was successfully created. 408 200 (OK): The reference was successfully created, replacing an existing 409 resource at the same location. 411 400 (Bad Request): The client attempted to send content with the 412 request, or set an invalid value for the Ref-Target, Ref-Integrity, Ref- 413 Type, or Position header. 415 409 (Conflict): Several conditions may produce this response. There may 416 be no resource at the location specified in Ref-Target, on a server that 417 prohibits dangling references. The request may be attempting to create 418 the reference in a collection that does not exist. The request may be 419 attempting to position the reference before or after a resource that is 420 not in the collection, or before or after itself. The request may be 421 attempting to position the reference in an unordered collection. 423 ***** These are not conflicts with the state of the resource at the 424 request-URI, but conflicts with the state of the parent collection or 425 the target resource. Is it still appropriate to use 409? 427 507 (Insufficient Storage): There is not enough space on the server to 428 complete the request. 430 3.3.3 Example 432 Request: 434 MKREF /~whitehead/dav/spec08.ref HTTP/1.1 435 HOST: www.ics.uci.edu 436 Ref-Target: 438 Response: 440 HTTP/1.1 201 Created 441 This request resulted in the creation of a new referential resource at 442 www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource 443 identified by the Ref-Target header. Its DAV:resourcetype property is 444 set to DAV:reference. Its DAV:reftarget property is set to the URI of 445 its target resource. Its DAV:refintegrity property is set to the 446 default value of DAV:weak. Its DAV:reftype property is set to the 447 default value of DAV:redirect. 449 3.4 Deleting, Copying, and Moving Referential Resources 451 The DELETE method should be used to delete referential resources. For 452 both direct and redirect references, DELETE affects the reference 453 itself, and not its target. 455 A MOVE operation on a referential resource moves the referential 456 resource to a different location, but has no effect on the location of 457 its target. The DAV:reftarget property is unchanged after a MOVE unless 458 the Ref-Target header is used to change it. 460 A COPY operation on a referential resource copies the referential 461 resource, not its target resource, to another location. The 462 DAV:reftarget property of the destination resource is the same as the 463 DAV:reftarget of the source resource, unless the Ref-Target header is 464 used to change it. 466 3.5 Listing Referential Members of a Collection 468 Since a referential member of a collection is just a resource in the 469 collection, a listing of members of the collection shows referential 470 members along with ordinary members. That is, a WebDAV PROPFIND request 471 on a collection resource with Depth = 1 or infinity MUST return a 472 response XML element for each ordinary member and for each referential 473 member. 475 For a redirect reference, the properties returned by the PROPFIND are 476 the properties of the reference itself. If Depth = infinity in the 477 PROPFIND request, the server MUST NOT follow redirect references into 478 any collections to which they may refer. 480 For a direct reference, the properties returned by the PROPFIND are the 481 properties of its target resource. If Depth = infinity in the PROPFIND 482 request, the server MUST follow direct references into any collections 483 to which they may refer. That is, if the target resource is a 484 collection, the server MUST list the members of that collection. If the 485 Re-Direct header is used with PROPFIND, the server MUST treat any direct 486 references like redirect references, as described in the previous 487 paragraph. 489 3.6 Other WebDAV Operations on Redirect Referential Resources 491 Operations on a redirect reference affect only the reference, and not 492 its target resource. 494 A LOCK operation on a redirect reference locks the reference, not its 495 target. A LOCK on the collection with Depth = 1 or infinity locks any 496 redirect references that are members of the collection. It does not 497 lock the targets of those redirect references. 499 A PROPPATCH on a redirect reference modifies the properties of the 500 reference, not the properties of its target resource. 502 A PROPFIND on a redirect reference returns the properties of the 503 reference, not the properties of its target resource. 505 3.7 Other WebDAV Operations on Direct Referential Resources 507 With the exception of DELETE, MOVE, and COPY, which were discussed 508 above, operations on direct references affect the target resource, not 509 the reference, unless the Re-Direct header is used. 511 Unless the Re-Direct header is used, a LOCK operation on a direct 512 reference locks the target. A lock on a direct reference to a 513 collection locks the target collection. A lock on a collection with 514 Depth = 1 or infinity locks the targets of the direct references in the 515 collection. 517 Unless the Re-Direct header is used, a PROPPATCH on a direct reference 518 modifies the properties of its target resource, not the properties of 519 the reference itself. 521 Unless the Re-Direct header is used, a PROPFIND on a direct reference 522 returns the properties of its target resource, not the properties of the 523 reference itself. 525 If the Re-Direct header is used with a LOCK, PROPPATCH, or PROPFIND 526 request on a direct reference, it behaves as if it were being applied to 527 a redirect reference, as specified in Section 3.6. 529 3.8 HTTP Operations on Redirect Referential Resources 531 Although existing HTTP clients cannot create referential resources, they 532 should be able to read collections created by reference-aware WebDAV 533 clients. They should be able to follow any references in those 534 collections to their targets. To make this possible, a server that 535 receives a GET or HEAD on a redirect reference MUST return a 302(Moved 536 Temporarily) status code. The server MUST follow [HTTP] Section 10.3.3 537 "302 Moved Temporarily," but with these additional rules: 539 o The Location header MUST contain the target URI of the reference. 541 o The response MUST include all referencing entity headers that make 542 sense for redirect references: Ref-Type, Ref-Target, and Ref- 543 Integrity. 545 o The response MUST also include those HTTP headers that make sense for 546 referential resources, at a minimum: Cache-Control, Age, ETag, 547 Expires, and Last-Modified. 549 The second and third of these rules preserve normal GET and HEAD 550 behavior for reference-aware WebDAV clients. 552 POST cannot be applied to a redirect reference. A reference cannot 553 accept another entity as its subordinate. Depending upon the nature of 554 the target resource, however, it might make sense to apply POST to the 555 target. A server that receives a POST request on a redirect reference 556 MUST return a 302 (Moved Temporarily). The rules for constructing and 557 using the response are the same as for GET and HEAD, except that there 558 is no requirement to return any headers other than Ref-Type. This header 559 allows reference-aware WebDAV clients to recognize the resource as a 560 reference and understand the reason for the redirection. 562 PUT cannot be applied to a redirect reference. To replace one redirect 563 reference with another, MKREF MUST be used. To replace a redirect 564 reference with an ordinary resource, the reference MUST first be deleted 565 with DELREF, after which a PUT MUST be used to create the ordinary 566 resource. 568 Existing HTTP clients that do not understand referential resources need 569 to be accommodated, however. To enable these clients to operate 570 reasonably on redirect references, a server that receives a PUT request 571 on a redirect reference MUST return a 302 (Moved Temporarily). The 572 client and server MUST follow [HTTP] Section 10.3.3 "302 Moved 573 Temporarily," but with these additional rules: 575 o The Location response header MUST contain the target URI of the 576 reference. 578 o The response MUST include the Ref-Type header. This header allows 579 reference-aware WebDAV clients to recognize the resource as a 580 reference and understand the reason for the redirection. 582 o The response MUST include an entity body for display to users. The 583 entity body explains that the requested resource is a reference to 584 another resource, and allows the user to choose whether to replace 585 the target resource or to replace the reference. 587 This last rule is needed for PUT, but not for GET, HEAD, or POST. Only 588 for PUT does it make sense for the user to confirm that the operation is 589 to be performed at the request-URI. GET or HEAD will already have 590 returned all useful information about the request-URI. POST makes no 591 sense for the redirect reference at the request-URI. But the user might 592 really want to replace the redirect reference with the entity in the PUT 593 request. 595 To enable existing HTTP clients to retrieve the capabilities of the 596 target resource, a server that receives an OPTIONS request on a redirect 597 reference MUST return a 302 (Moved Temporarily). At the same time, 598 reference-aware WebDAV clients may need to retrieve the capabilities of 599 the reference itself. Consequently, the server MUST provide a choice as 600 to whether the method should be applied to the reference or its target. 601 Consequently, the same rules apply for OPTIONS as for PUT above. 603 3.9 HTTP Operations on Direct Referential Resources 604 GET, HEAD, PUT, POST, and OPTIONS on direct references are passed 605 through to their target resources. GET returns the content and headers 606 of the target resource, HEAD returns the headers of the target resource, 607 PUT replaces the content of the target resource, POST performs the 608 expected function at the target resource, and OPTIONS reports the 609 communication options available at the target resource. 611 The Re-Direct request header may be used with GET, HEAD, or OPTIONS to 612 view the headers or capabilities of the reference, rather than its 613 target. If the Re-Direct header is used, the method�s behavior is as 614 described in Section 3.8. 616 The Re-Direct request header must not be used with PUT or POST, which 617 cannot be applied to references. If a server receives a PUT or POST 618 request on a direct reference with the Re-Direct header, it MUST respond 619 with a 400 (Bad Request). 621 ***** Confirm behavior for PUT / POST with Re-Direct. 623 3.10 Operations on Targets of Referential Resources 625 In general, operations on targets of weak referential resources have no 626 effect on the referential resource. However, servers that choose to 627 maintain the integrity of references are free to make changes to the 628 state of references when moving or deleting their targets. 630 When moving a target resource, a server MAY insert an optional step into 631 the semantics of MOVE as defined in [WebDAV] for the purpose of 632 maintaining referential integrity. Between the copy step and the delete 633 step of a MOVE, the server MAY perform an update step, which changes the 634 DAV:reftarget property of any references to the target to reflect its 635 new location. 637 When deleting a target resource, a server MAY perform any internal 638 operations necessary to implement its policy on preserving referential 639 integrity. For example, it might delete any references to the deleted 640 target, or it might flag them as having a deleted target, or it might 641 replace references with copies of the target. 643 3.11 Discovering a Target�s References 645 An optional DAV:references property on the target resource provides a 646 list of referential resources whose DAV:reftarget property points to 647 that target resource. If present, DAV:references is a read-only 648 property, maintained by the server. By retrieving this property, a 649 client can discover the URIs of the references that point to the target, 650 and so can also discover the collections of which those URIs are 651 members. As for all DAV: properties, this specification is silent as to 652 how the DAV:references property is implemented on the server. 654 The DAV:references property is expected to be supported mainly by 655 Document Management Systems (DMSs) and other servers that will maintain 656 the property only for references within their own domain. It is not in 657 general possible for a server to maintain the property for references on 658 other servers. If a reference on a different server points to the 659 target, the server where the target is located is unlikely to know about 660 that reference. This protocol provides no mechanism for one server to 661 notify another of the creation of a reference to one of its resources. 662 Consequently, the list of references in DAV:reftarget may be incomplete. 664 Rationale: A number of scenarios require clients to navigate from a 665 target resource to the references that point to it, and to the 666 collections that contain those references. This capability is 667 particularly important for DMSs, which may populate their collections 668 entirely by reference. Their clients may need to determine, for any 669 object in the DMS, what collections it belongs to. It is also important 670 in other contexts. For example, some servers enforce referential 671 integrity by refusing to delete any resource that is referenced by other 672 resources. In such an environment, the client must be able to discover 673 the references in order to delete them before attempting to delete the 674 target. 676 Once a search capability [DASL] is available, it may be possible for a 677 client to discover the references that point to a given target by 678 searching for resources with DAV:reftarget equal to the URI of the 679 target resource. However, it will be much more efficient for the client 680 to retrieve a list of references from the target resource. 682 ***** Only if DASL provides search of structured properties or we define 683 DAV:reftarget as a string value, not an href. 685 Risks: When deciding whether to support the DAV:references property, 686 server implementors / administrators should balance the efficiencies it 687 provides in discovering references against the cost of maintaining the 688 property and the security risks enumerated in Sections 11.4 and 11.5. 690 3.12 Behavior of Dangling Direct References 692 ***** Think about chains of direct references. 694 GET and HEAD respond with 404 (Not Found), but the Ref-Type and Ref- 695 Target headers are included in the response, so that the client can tell 696 that it is the target, and not the reference, that was not found. (If 697 the Hide-Target header was used when creating the reference, then Ref- 698 Target is not included.) 700 PUT, MKCOL, and MKREF succeed, creating a new resource at the location 701 specified by the reference�s DAV:reftarget property. 703 POST fails with 404 (Not Found), since a nonexistent resource cannot 704 accept another resource as its subordinate. The Ref-Type and Ref-Target 705 headers are included in the response, so that the client can tell that 706 it is the target, and not the reference, that was not found. (If the 707 Hide-Target header was used when creating the reference, then Ref-Target 708 is not included.) 710 OPTIONS fails with 404 (Not Found). The Ref-Type and Ref-Target headers 711 are included in the response, so that the client can tell that it is the 712 target, and not the reference, that was not found. (If the Hide-Target 713 header was used when creating the reference, then Ref-Target is not 714 included.) 716 PROPFIND responds with a 207 Multistatus, including a 404 (Not Found) as 717 the status for the target resource. The DAV:reftype and DAV:reftarget 718 properties of the references are included in the response. (If the 719 Hide-Target header was used when creating the reference, then 720 DAV:reftarget is not included.) Their presence informs the client that 721 it is the target, not the reference, that was not found. These two 722 elements are extensions to the DAV:multistatus element as defined in 723 {WEBDAV]. 725 For example, 727 Request: 729 PROPFIND /collection1/directref7 HTTP/1.1 730 Host: www.somehost.com 731 Content-Type: text/xml 732 Content-Length: xxxx 734 735 736 737 738 739 740 742 Response: 744 HTTP/1.1 207 Multi-Status 745 Content-Type: text/xml 746 Content-Length: xxxx 748 749 750 751 http://www.somehost.com/collection1/directref7 752 HTTP/1.1 404 Not Found 753 754 755 http://www.somehost.com/collection2/file19 756 757 758 Target resource not 759 found. 760 762 PROPPATCH responds with a 207 Multistatus, including a 404 (Not Found) 763 as the status for the target resource. The DAV:reftype and 764 DAV:reftarget properties of the references are included in the response. 765 (If the Hide-Target header was used when creating the reference, then 766 DAV:reftarget is not included.) Their presence informs the client that 767 it is the target, not the reference, that was not found. These two 768 elements are extensions to the DAV:multistatus element as defined in 769 {WEBDAV]. 771 ***** Is a response to a PROPPATCH required to be a 207 (Multi-Status), 772 or could it just be a 404 (Not Found)? 774 For example, 776 Request: 778 PROPPATCH /collection1/directref7 HTTP/1.1 779 Host: www.somehost.com 780 Content-Type: text/xml 781 Content-Length: xxxx 783 784 785 786 787 Pauloosie Padluq 788 South Baffin Carvers 789 790 791 793 Response: 795 HTTP/1.1 207 Multi-Status 796 Content-Type: text/xml 797 Content-Length: xxxx 799 800 801 802 http://www.somehost.com/collection1/directref7 803 HTTP/1.1 404 Not Found 804 805 806 http://www.somehost.com/collection2/file19 807 808 809 Target resource not 810 found. 811 813 MOVE, COPY, and DELETE succeed. For MOVE and COPY, the reference at the 814 destination will be broken, just as the reference at the source was. 816 If a single resource is being LOCKed or UNLOCKed, the response is a 404 817 (Not Found). The Ref-Type and Ref-Target headers are included in the 818 response. (If the Hide-Target header was used when creating the 819 reference, then Ref-Target is not included.) Their presence informs the 820 client that it is the target, not the reference, that was not found. 822 If the dangling reference is a member of a collection that is being 823 LOCKed or UNLOCKed, the response is a 207 (Multi-Status). The 824 DAV:status element for the dangling reference is a 404 (Not Found). The 825 DAV:reftype and DAV:reftarget properties of the references are included 826 in the response. (If the Hide-Target header was used when creating the 827 reference, then DAV:reftarget is not included.) Their presence informs 828 the client that it is the target, not the reference, that was not found. 829 These two elements are extensions to the DAV:multistatus element as 830 defined in {WEBDAV]. 832 3.13 Summary of Referencing Headers Required in Responses 834 This section summarizes the rules that determine which referencing 835 headers must be included in responses to requests on references. 837 o Every response to a request on a reference MUST include the Ref-Type 838 header, so that the client knows that it was operating on a 839 reference, and whether the operation was applied to the reference 840 itself or to its target. 842 o Every response to a request on a direct reference MUST include the 843 Ref-Target header, unless the reference was created with the Hide- 844 Target header. This allows the client to tell what resource was 845 affected by the operation. A request that includes the Re-Direct 846 header is treated as if it were a request on a redirect reference, 847 and so the response NEED NOT include the Ref-Target header. 849 o Every response to a GET or HEAD request on a redirect reference (or 850 on a direct reference with the Re-Direct header) MUST include all the 851 referencing entity headers that make sense for redirect references: 852 Ref-Type, Ref-Target, and Ref-Integrity. 854 4 Ordered Collections 856 4.1 Overview 858 Collections on a compliant server may be ordered, but need not be. It 859 is up to the client to decide whether a given collection is ordered and, 860 if so, to specify the semantics to be used for ordering its members. If 861 a collection is ordered, each of its members must be in the ordering 862 exactly once, and the ordering must not include any resource that is not 863 a member of the collection. Only one ordering can be attached to any 864 collection. Multiple orderings of the same resources can be achieved by 865 creating multiple collections referencing those resources, and attaching 866 a different ordering to each collection. 868 The server is responsible for enforcing these constraints on orderings. 869 The server MUST remove a resource from the ordering when it is removed 870 from the collection. The server MUST add a resource to the ordering when 871 it is added to the collection. 873 When responding to a PROPFIND on a collection, the server MUST order the 874 response elements according to the ordering defined on the collection. 876 4.2 Creating an Ordered Collection 878 4.2.1 Overview 879 When a collection is created, the client can request that it be ordered 880 and specify the semantics of the ordering by using the new Ordered 881 header in the MKCOL request, setting its value to the URI of the 882 semantics to be used. If the client does not want the collection to be 883 ordered, it may omit the Ordered header, or use it with the value 884 "DAV:unordered". 886 Every collection MUST have the new DAV:orderingtype property, which 887 indicates whether the collection is ordered and, if so, identifies the 888 semantics of the ordering. A value of DAV:unordered indicates that that 889 collection is not ordered. That is, the client cannot depend on the 890 repeatability of the ordering of results from a PROPFIND request. For 891 collections that are ordered, DAV:orderingtype SHOULD be set to an href 892 that identifies the semantics of the ordering, allowing a human user or 893 software package to insert new collection members into the ordering 894 intelligently. Although the href MAY point to a resource that contains 895 a definition of the semantics of the ordering, clients are discouraged 896 from accessing that resource, in order to avoid overburdening its 897 server. The DAV:orderingtype property MAY be set to DAV:custom to 898 indicate that the collection is to be ordered, but the semantics of the 899 ordering is not being advertised. 901 If the Ordered header is present on a MKCOL request, the server MUST set 902 the collection's DAV:orderingtype property to the value of the Ordered 903 header. If the Ordered header is not present, the server MUST treat the 904 request as if it had an Ordered header with the value "DAV:unordered", 905 meaning that the collection is not ordered. If the collection is 906 ordered, the server MUST respond to PROPFIND requests on the collection 907 using the specified ordering. 909 4.2.2 Status Codes 911 No new error conditions are introduced. 913 4.2.3 Example 915 Request: 917 MKCOL /theNorth/ HTTP/1.1 918 Host: www.server.org 919 Ordered: 921 Response: 923 HTTP/1.1 201 Created 925 In this example, a new, ordered collection was created. Its 926 DAV:orderingtype property has as its value the URI from the Ordered 927 header. In this case, the URI points to a description of the semantics 928 governing the ordering. As new members are added to the collection, 929 clients or end users can use the semantics to determine where to 930 position the new members in the ordering. 932 4.3 Setting the Position of a Collection Member 933 4.3.1 Overview 935 When a new member is added to a collection with MKREF, PUT, COPY, MOVE, 936 or LOCK, its position in the ordering can be set with the new Position 937 header. The Position header allows the client to specify that the 938 member should be first in the collection's ordering, last in the 939 collection's ordering, before some other collection member in the 940 collection's ordering, or after some other collection member in the 941 collection's ordering. 943 The server MUST insert the new member into the ordering at the location 944 specified in the Position header, if one is present (and if the 945 collection is ordered); otherwise, it MUST append the new member to the 946 end of the ordering (if the collection is ordered). If a PUT or MKREF 947 causes an existing resource to be replaced, and if the Position header 948 is absent, the server MUST leave the member at its previous position in 949 thee collection ordering. If the Position header is present, the server 950 MUST remove the member from its previous position, and then insert it at 951 the requested position. 953 4.3.2 Status Codes 955 201 (Created): The resource was successfully created. 957 409 (Conflict): The request may be attempting to position the resource 958 before or after a resource that is not in the collection, or before or 959 after itself, or it may be attempting to position the resource in an 960 unordered collection. 962 4.3.3 Examples 964 Request: 966 MKREF /~whitehead/dav/spec08.ref HTTP/1.1 967 HOST: www.ics.uci.edu 968 Ref-Target: 969 Position: After 971 Response: 973 HTTP/1.1 201 Created 975 This request resulted in the creation of a new referential resource at 976 www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource 977 identified by the Ref-Target header. The Position header in this 978 example caused the server to set its position in the ordering of the 979 /~whitehead/dav/ collection immediately after the requirements.html 980 resource. 982 Request: 984 MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 985 Host: www.ics.uci.edu 986 Destination: 987 Position: First 989 Response: 991 HTTP/1.1 409 Conflict 993 In this case, the server returned a 409 Conflict status code because the 994 /~whitehead/dav/ collection is an unordered collection. Consequently, 995 the server was unable to satisfy the Position header. 997 4.4 Changing the Semantics of a Collection Ordering 999 After a collection has been created, a client can change its ordering 1000 semantics, or change an ordered collection to an unordered collection or 1001 vice versa, by using PROPPATCH to change the value of its 1002 DAV:orderingtype property. The client is then responsible for updating 1003 the ordering of the collection members according to the new semantics. 1004 PROPPATCH is defined in [WebDAV], Section 7.2. 1006 4.5 Changing the Position of a Collection Member 1008 4.5.1 The ORDERPATCH Method 1010 To change the positions of collection members in the collection's 1011 ordering, the client MUST use an ORDERPATCH request with a request body 1012 containing an order XML element. The request-URI of an ORDERPATCH 1013 request is the URI of the collection whose ordering is to be updated. 1014 The order XML element identifies the member resources whose positions 1015 are to be changed, and describes their new positions in the ordering. 1016 Each new position can be specified as first in the ordering, last in the 1017 ordering, before some other collection member in the ordering, or after 1018 some other collection member in the ordering. The server MUST apply the 1019 changes in the order they appear in the order element. 1021 4.5.2 Status Codes 1023 Since multiple changes can be requested in a single ORDERPATCH request, 1024 the server MUST return a 207 Multi-Status response, as defined in 1025 [WebDAV]. 1027 Within the 207 Multi-Status response, the following status codes are 1028 possible: 1030 200 (OK): The change in ordering was successfully made. 1032 409 (Conflict): An attempt was made to position the resource before or 1033 after a resource that is not in the collection, or before or after 1034 itself, or an attempt was made to position the resource in an unordered 1035 collection. 1037 A request to reposition a collection member to the same place in the 1038 ordering is not an error. 1040 4.5.3 Example 1041 Consider a collection /coll-1/ with members ordered as follows: 1043 nunavut.map 1044 nunavut.img 1045 baffin.map 1046 baffin.desc 1047 baffin.img 1048 iqaluit.map 1049 nunavut.desc 1050 iqaluit.img 1051 iqaluit.desc 1053 Request: 1055 ORDERPATCH /coll-1/ HTTP/1.1 1056 Host: www.nunanet.com 1057 Content-Type: text/xml 1058 Content-Length: xxx 1060 1061 1062 1063 nunavut.desc 1064 1065 1066 nunavut.map 1067 1068 1069 1070 1071 iqaluit.img 1072 1073 1074 1075 1076 1078 Response: 1080 HTTP/1.1 207 Multi-Status 1081 Content-Type: text/xml 1082 Content-Length: xxx 1084 1085 1086 1087 http://www.nunanet.com/coll-1/nunavut.desc 1088 HTTP/1.1 200 OK 1089 1090 1091 http://www.nunanet.com/coll-1/iqaluit.img 1092 HTTP/1.1 200 OK 1093 1094 1095 In this example, after the request has been processed, the collection's 1096 ordering is as follows: 1098 nunavut.map 1099 nunavut.desc 1100 nunavut.img 1101 baffin.map 1102 baffin.desc 1103 baffin.img 1104 iqaluit.map 1105 iqaluit.desc 1106 iqaluit.img 1108 4.5.4 Design Rationale 1110 The decision to introduce the new ORDERPATCH method was made after 1111 investigating the possibility of using the existing MOVE method with a 1112 Position header. The use of MOVE initially looked appealingly simple: 1114 MOVE /root/coll-1/foo HTTP/1.1 1115 Host: www.somehost.com 1116 Destination: 1117 Position: First 1119 Unfortunately, several features of the semantics of MOVE make it 1120 unsuitable for changing the position of a collection member in the 1121 collection's ordering. First, [WebDAV] defines MOVE as logically 1122 equivalent to a copy followed by a delete of the source resource. This 1123 definition makes it impossible to MOVE a resource to a destination URL 1124 that is the same as the source URL. The resource would be deleted 1125 rather than moved. Second, [WebDAV] states that when moving a resource 1126 to a destination where a resource already exists, the Overwrite header 1127 must be "T", and in this case the server must DELETE the resource at the 1128 destination before performing the MOVE. Again, this makes it impossible 1129 to MOVE a resource to the same location. Finally, [WebDAV] states that 1130 locks are lost on a MOVE, an outcome that seems undesirable in this 1131 case. 1133 5 New Headers 1135 ***** Decide which headers intended for MKREF also can be used with 1136 MOVE, COPY, LOCK. Is it possible to create a referential resource by 1137 invoking LOCK? If so, Ref-Type, Ref-Target, and Ref-Integrity would all 1138 have to be usable with LOCK. We might need a Resource-Type header to 1139 say that it is a reference we are creating. What about MOVE and COPY? 1140 At the moment, we�re saying you can change Ref-Type, Ref-Target, and 1141 Ref-Integrity on a MOVE or COPY. It would be pretty weird to change 1142 Resource-Type. What about Hide-Target? 1144 5.1 Ref-Target Entity Header 1146 Ref-Target = "Ref-Target" ":" Coded-url 1148 Coded-url is defined in [WebDAV], Section 8.4. 1150 The Ref-Target header is used with the MKREF method to identify the 1151 target resource of the new referential resource being created. It is a 1152 required header in MKREF requests. This header may also be used with 1153 COPY and MOVE requests to change the target of the destination 1154 reference. 1156 Servers MUST include the Ref-Target header in the following responses 1157 unless the Hide-Target header was used when the reference was created, 1158 in which case the Ref-Target header MUST NOT be included in responses: 1160 o Responses to GET and HEAD requests on redirect references 1162 o Responses to all requests on direct references, unless the request 1163 included the Re-Direct header 1165 5.2 Ref-Type Entity Header 1167 Ref-Type = "Ref-Type" ":" ("DAV:direct" | "DAV:redirect") 1169 The Ref-Type header is defined to distinguish between direct and 1170 redirect references. The possible values of this header are DAV:direct 1171 and DAV:redirect. If the header is not present on a MKREF request, the 1172 server MUST treat the request as if it has a Ref-Type header with the 1173 value DAV:redirect. This header may also be used with a COPY or MOVE 1174 request on a reference. If this header is not present on a COPY or MOVE 1175 request, the DAV:reftype property MUST be treated like any other live 1176 property, as specified in [WebDAV] sections 7.8.2 and 7.9.1. 1178 Servers MUST include the Ref-Target header in the following responses: 1180 o Responses to all requests on both direct and redirect references 1182 5.3 Ref-Integrity Entity Header 1184 Ref-Integrity = "Ref-Integrity" ":" ("DAV:weak") 1186 The Ref-Integrity header is defined to allow future support for strong 1187 references. It specifies whether the server should enforce referential 1188 integrity for a referential resource being created with MKREF. The only 1189 value currently defined for the Ref-Integrity header is "DAV:weak", 1190 which means that the server need not enforce referential integrity for 1191 the newly created reference. Other values may be used by private 1192 agreement between the client and server. If the header is not present 1193 on a MKREF request, the server MUST treat the request as if it has a 1194 Ref-Integrity header set to "DAV:weak". This header may also be used 1195 with COPY and MOVE requests. If this header is not present on a COPY or 1196 MOVE request, the DAV:refintegrity property MUST be treated like any 1197 other live property, as specified in [WebDAV] sections 7.8.2 and 7.9.1. 1199 ***** Again, does DAV:weak mean that the server need not maintain 1200 referential integrity, or that it must not? 1202 Servers MUST include the Ref-Integrity header in the following 1203 responses: 1205 o Responses to GET and HEAD requests on redirect references (or on 1206 direct references if the request included the Re-Direct header) 1208 5.4 Re-Direct Request Header 1210 Re-Direct = "Re-Direct" ":" 1212 The optional Re-Direct header can be used on any request to a direct 1213 reference except PUT or POST. It forces the reference to behave like a 1214 redirect reference for that request. The operation will be applied to 1215 the reference itself, not to its target. If the Re-Direct header is 1216 used on a request to any other sort of resource besides a direct 1217 reference, the server SHOULD ignore it. If the Re-Direct header is used 1218 with a PUT or POST request on a direct reference, the server MUST 1219 respond with a 400 (Bad Request). 1221 ***** Confirm behavior for exception cases. 1223 ***** What if there is a chain of direct references? Suppose I want to 1224 see the properties of the second reference in the chain - how would I do 1225 that? 1227 5.5 Hide-Target Entity Header 1229 Hide-Target = "Hide-Target" ":" 1231 The optional Hide-Target header is for use when creating a new direct 1232 reference. It specifies that the URI of the target resource is to be 1233 hidden. If this header is used when creating a direct reference, the 1234 server MUST NOT include the Ref-Target header in any response to a 1235 request on the reference. If the Hide-Target header is not present, the 1236 server MUST assume that the DAV:reftarget property is not to be hidden. 1237 If the Hide-Target header is used in a request with Ref-Type = 1238 DAV:redirect, the server MUST ignore the Hide-Target header. 1240 ***** If we want to let clients change their minds about Hide-Target 1241 after a reference has been created, we need a DAV:hidetarget property to 1242 allow that. 1244 5.6 Resource-Type Entity Header 1246 Resource-Type = "Resource-Type" ":" ["DAV:collection" | "DAV:reference" 1247 |""] 1249 The Resource-Type header contains the value of the DAV:resourcetype 1250 property. It is used with LOCK, MOVE, or COPY to set or change the 1251 resource type. 1253 ***** Not needed unless you can create a reference with LOCK, or change 1254 resource type with MOVE or COPY. 1256 5.7 Ordered Entity Header 1258 Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) 1259 The Ordered header may be used with MKCOL to request that the new 1260 collection be ordered and to specify its ordering semantics. A value of 1261 "DAV:unordered" indicates that the collection is not ordered. That is, 1262 the client cannot depend on the repeatability of the ordering of results 1263 from a PROPFIND request. A Coded-url value indicates that the collection 1264 is ordered, and identifies the semantics of the ordering, allowing a 1265 human user or software package to insert new collection members into the 1266 ordering intelligently. The Coded-url MAY point to a resource that 1267 contains a definition of the semantics of the ordering. A value of 1268 "DAV:custom" indicates that the collection is to be ordered, but the 1269 semantics of the ordering is not being advertised. 1271 If the Ordered header is not present on a MKCOL request, the server MUST 1272 treat the request as if it had an Ordered header with the value 1273 "DAV:unordered". 1275 5.8 Position Request Header 1277 Position = "Position" ":" ("First" | "Last" | 1278 (("Before" | "After") Coded-url)) 1280 The Position header may be used with MKREF, PUT, COPY, MOVE, or LOCK to 1281 tell the server where in the collection ordering to position the 1282 resource being added to the collection. It may be used for both 1283 ordinary and referential members. 1285 If the Coded-url is a relative URL, it is interpreted relative to the 1286 collection in which the resource is being created. 1288 If the Position request header is not used, then: 1290 If the request is replacing an existing resource, the server MUST 1291 preserve the present ordering. 1293 If the request is adding a new member to the collection, the server MUST 1294 append the new member to the end of the ordering (if the collection is 1295 ordered). 1297 5.9 DAV-Collections Entity Header 1299 DAV-Collections = "DAV-Collections" ":" 1#collection-capability 1300 collection-capability = "DAV:basicref" | "DAV:directref" | 1301 "DAV:orderedcoll" 1303 The DAV-Collections header is used in responses to OPTIONS requests, to 1304 enumerate the collection-related capabilities of the resource. A value 1305 of "DAV:basicref" indicates that the resource provides basic referencing 1306 (redirect references). A value of "DAV:directref" indicates that the 1307 resource provides direct references. If a resource provides direct 1308 references, it MUST also provide redirect references. A value of 1309 "DAV:orderedcoll" indicates that the resource provides ordered 1310 collections. 1312 6 New Properties 1313 6.1 reftarget Property 1315 Name: reftarget 1316 Namespace: DAV: 1317 Purpose: A required property of referential resources that provides 1318 an efficient way for clients to discover the URI of the 1319 target resource. This is a read-only property, whose value 1320 can only be set by using the Ref-Target header with a MKREF, 1321 COPY, or MOVE request. 1322 Value: URI of the target resource. 1324 1326 6.2 refintegrity Property 1328 Name: refintegrity 1329 Namespace: DAV: 1330 Purpose: A required property of a referential resource that indicates 1331 whether the server guarantees referential integrity for that 1332 reference. The refintegrity property is defined to allow 1333 future support for strong references. The only value 1334 currently defined for refintegrity is weak, which means that 1335 the server need not [does not?] enforce referential 1336 integrity for the reference. Other values may be used by 1337 private agreement between the client and server. This is a 1338 readonly property, whose value can only be set by using the 1339 Ref-Integrity header with a MKREF, COPY, or MOVE request. 1340 Value: weak 1342 1344 6.3 reftype Property 1346 Name: reftype 1347 Namespace: DAV 1348 Purpose: A required property of a referential resource that 1349 identifies the reference as direct or redirect. This is a 1350 read-only property, whose value can only be set by using 1351 the Ref-Type header with a MKREF, COPY, or MOVE request. 1352 Value: direct | redirect 1354 1356 6.4 references Property 1358 Name: references 1359 Namespace: DAV: 1360 Purpose: Enables clients to discover, for any target resource, what 1361 references point to it and what collections contain it by 1362 reference. This is an optional property. If present, it is 1363 a read-only property, maintained by the server. 1364 Value: List of the URIs of the references that point to the target 1365 resource. 1367 1368 6.5 orderingtype Property 1370 Name: orderingtype 1371 Namespace: DAV: 1372 Purpose: Indicates whether the collection is ordered and, if so, 1373 uniquely identifies the semantics of the ordering being 1374 used. May also point to an explanation of the semantics in 1375 human and / or machine-readable form. At a minimum, this 1376 allows human users who add members to the collection to 1377 understand where to position them in the ordering. 1378 Value: unordered for an unordered collection, or a URI that 1379 uniquely identifies the semantics of the collection's 1380 ordering. The URI MAY point to a definition of the ordering 1381 semantics. The value custom may be used for a collection 1382 that is to be ordered, but for which the semantics are not 1383 being advertised. 1385 1387 7 New XML Elements 1389 7.1 reference XML Element 1391 Name: reference 1392 Namespace: DAV: 1393 Purpose: A new value of the DAV:resourcetype property that identifies 1394 its resource as a referential resource. The 1395 DAV:resourcetype property of a referential resource MUST 1396 have this value. 1397 Value: EMPTY 1399 1401 7.2 direct XML Element 1403 Name: direct 1404 Namespace: DAV: 1405 Purpose: A value for the DAV:reftype property that identifies its 1406 resource as a direct reference. 1407 Value: EMPTY 1409 1411 7.3 redirect XML Element 1413 Name: redirect 1414 Namespace: DAV: 1415 Purpose: A value for the DAV:reftype property that identifies its 1416 resource as a redirect reference. 1417 Value: EMPTY 1419 1421 7.4 weak XML Element 1422 Name: weak 1423 Namespace: DAV: 1424 Purpose: The only value currently defined for the DAV:refintegrity 1425 property. It means that the server need not [does not?] 1426 enforce referential integrity for the reference to which the 1427 property belongs. 1428 Value: EMPTY 1430 1432 7.5 unordered XML Element 1434 Name: unordered 1435 Namespace: DAV: 1436 Purpose: A value of the DAV:orderingtype property that indicates that 1437 the collection is not ordered. That is, the client cannot 1438 depend on the repeatability of the ordering of results from 1439 a PROPFIND request. 1440 Value: EMPTY 1442 1444 7.6 custom XML Element 1446 Name: custom 1447 Namespace: DAV: 1448 Purpose: A value of the DAV:orderingtype property that indicates that 1449 the collection is ordered, but the semantics of the ordering 1450 are not being advertised. 1451 Value: EMPTY 1453 1455 7.7 order XML Element 1457 Name: order 1458 Namespace: DAV: 1459 Purpose: For use with the new ORDERPATCH method. Describes a change 1460 to be made in a collection ordering. 1461 Value: A description of the new positions of collection members in 1462 the collection's ordering. 1464 1466 7.8 ordermember XML Element 1468 Name: ordermember 1469 Namespace: DAV: 1470 Purpose: Occurs in the order XML Element, and describes the new 1471 position of a single collection member in the collection's 1472 ordering. 1473 Value: An href containing the relative URI of the collection 1474 member, and a description of its new position in the 1475 ordering. The href XML element is defined in [WebDAV], 1476 Section 11.3. 1478 1480 7.9 position XML Element 1482 Name: position 1483 Namespace: DAV: 1484 Purpose: Occurs in the member XML element. Describes the new 1485 position in a collection's ordering of one of the 1486 collection's members. 1487 Value: The new position can be described as first in the 1488 collection's ordering, last in the collection's ordering, 1489 before some other member of the collection, or after some 1490 other member of the collection. 1492 1494 7.10 first XML Element 1496 Name: first 1497 Namespace: DAV: 1498 Purpose: Occurs in the position XML element. Describes the 1499 collection member's position as first in the collection's 1500 ordering. 1501 Value: EMPTY 1503 1505 7.11 last XML Element 1507 Name: last 1508 Namespace: DAV: 1509 Purpose: Occurs in the position XML element. Describes the 1510 collection member's position as last in the collection's 1511 ordering. 1512 Value: EMPTY 1514 1516 7.12 before XML Element 1518 Name: before 1519 Namespace: DAV: 1520 Purpose: Occurs in the position XML element. Describes the 1521 collection member's position as coming before some other 1522 collection member in the collection's ordering. 1523 Value: href of the member it precedes in the ordering 1525 1527 7.13 after XML Element 1529 Name: after 1530 Namespace: DAV: 1532 Purpose: Occurs in the position XML element. Describes the 1533 collection member's position as coming after some other 1534 collection member in the collection's ordering. 1535 Value: href of the member it follows in the ordering 1537 1539 8 Extensions to the DAV:multistatus XML Element 1541 As described in Section 3.12, the DAV:reftype property and the 1542 DAV:reftarget property may be returned in the DAV:response element of a 1543 207 Multi-Status response, to indicate that a problem is not with a 1544 direct reference, but with its target resource. 1546 Consequently, the definition of the DAV:response XML element changes to 1547 the following: 1549 1552 9 Capability Discovery 1554 9.1 Using OPTIONS 1556 Since referencing and ordering are independent capabilities, a resource 1557 MAY support either or both. A resource that provides referencing MUST 1558 support redirect references, and MAY in addition support direct 1559 references. A response to an OPTIONS request MUST indicate which of 1560 these capabilities the resource supports. 1562 This specification defines two new methods: MKREF in support of 1563 referencing, and ORDERPATCH in support of ordering. The response MUST 1564 indicate which of these methods the resource allows. In addition, the 1565 response MUST include the DAV-Collections header, listing those of the 1566 three collection-related capabilities the resource provides. Possible 1567 values for the DAV-Collections header are DAV:basicref, DAV:directref, 1568 and DAV:orderedcoll. 1570 9.2 Example 1572 Request: 1574 OPTIONS /somecollection/ HTTP/1.1 1575 HOST: somehost.org 1577 Response: 1579 HTTP/1.1 200 OK 1580 Date: Tue, 20 Jan 1998 20:52:29 GMT 1581 Connection: close 1582 Accept-Ranges: none 1583 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 1584 PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, ORDERPATCH 1585 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 1586 PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, ORDERPATCH 1587 DAV-Collections: DAV:basicref, DAV:directref, DAV:orderedcoll 1589 This response indicates that the resource /somecollection/ provides 1590 basic referencing, direct references, and ordered collections. 1592 10 Dependencies on Other Specifications 1594 TBD 1596 11 Security Considerations 1598 This section is provided to detail issues concerning security 1599 implications of which WebDAV applications need to be aware. 1601 All of the security considerations of HTTP/1.1 and the base WebDAV 1602 protocol also apply to WebDAV collections. In addition, referential 1603 resources and ordered collections introduce several new security 1604 concerns and increase the risk of some existing threats. These issues 1605 are detailed below. 1607 11.1 Redirect Loops 1609 Although redirect loops were already possible in HTTP 1.1, the 1610 introduction of referential resources creates a new avenue for clients 1611 to create loops accidentally or maliciously. If the referential 1612 resource and its target are on the same server, the server may be able 1613 to detect MKREF requests that would create loops. See also [HTTP], 1614 Section 10.3 "Redirection 3xx." 1616 11.2 References and Denial of Service 1618 The introduction of referential resources creates a new avenue for 1619 denial of service attacks. Clients can create heavily used references to 1620 target locations that were not designed for heavy usage. 1622 11.3 Maintaining Referential Integrity May Reveal Private Locations 1624 Although this specification does not require servers to maintain 1625 referential integrity, it does not prevent them from doing so. If a 1626 server updates a reference�s DAV:reftarget property when its target 1627 resource is moved, there is the risk that a private location will be 1628 revealed in the new value of DAV:reftarget. Clients can avoid this risk 1629 by doing a COPY followed by a DELETE rather than a MOVE. 1631 If the owner of the target also owns the direct reference to it, the 1632 Hide-Target header can be used when creating the direct reference to 1633 prevent others from discovering the location of the target through that 1634 reference. 1636 11.4 DAV:references and Denial of Service 1638 If the server maintains the DAV:references property in response to 1639 references created in other administrative domains, it is exposed to 1640 hostile attempts to make it devote resources to adding references to the 1641 list. 1643 11.5 DAV:references and Malicious Deletion of Resources 1645 Servers that support the DAV:references property should insure that 1646 clients cannot create editable properties with the name DAV:references. 1647 An editable DAV:references property would constitute a security risk on 1648 servers that enforce referential integrity by deleting references when 1649 their target is deleted. These servers could be tricked into deleting a 1650 resource by listing it in the DAV:references property of some target 1651 resource. 1653 11.6 Malicious Modifications of Ordering 1655 Particularly in large collections, moving a collection member to a 1656 different position in the ordering can make it very difficult for users 1657 to find. 1659 11.7 Denial of Service and DAV:orderingtype 1661 There may be some risk of denial of service at sites that are advertised 1662 in the DAV:orderingtype property of collections. However, it is 1663 anticipated that widely-deployed applications will use hard-coded values 1664 for frequently-used ordering semantics rather than looking up the 1665 semantics at the location specified by DAV:orderingtype. 1667 12 Internationalization Considerations 1669 This specification follows the practices of [WebDAV] in encoding all 1670 human-readable content using XML [XML] and in the treatment of names. 1671 Consequently, this specification complies with the IETF Character Set 1672 Policy [Alvestrand]. 1674 WebDAV applications MUST support the character set tagging, character 1675 set encoding, and the language tagging functionality of the XML 1676 specification. This constraint ensures that the human-readable content 1677 of this specification complies with [Alvestrand]. 1679 As in [WebDAV}, names in this specification fall into three categories: 1680 names of protocol elements such as methods and headers, names of XML 1681 elements, and names of properties. Naming of protocol elements follows 1682 the precedent of HTTP, using English names encoded in USASCII for 1683 methods and headers. The names of XML elements used in this 1684 specification are English names encoded in UTF-8. 1686 For error reporting, [WebDAV] follows the convention of HTTP/1.1 status 1687 codes, including with each status code a short, English description of 1688 the code (e.g., 423 Locked). Internationalized applications will ignore 1689 this message, and display an appropriate message in the user's language 1690 and character set. 1692 For rationales for these decisions and advice for application 1693 implementors, see [WebDAV]. 1695 13 IANA Considerations 1696 TBD 1698 14 Copyright 1700 15 Intellectual Property 1702 16 Acknowledgements 1704 This draft has benefited from thoughtful discussion by Steve Carter, 1705 Geoffrey Clemm, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Rajiv 1706 Dulepet, David Durand, Chuck Fay, Roy Fielding, Yaron Goland, Fred Hitt, 1707 Alex Hopmann, Marcus Jager, Chris Kaler, Rohit Khare, Daniel LaLiberte, 1708 Steve Martin, Surendra Koduru Reddy, Sam Ruby, Bradley Sergeant, Nick 1709 Shelness, John Stracke, John Tigue, John Turner, and others. 1711 17 References 1713 [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. 1714 Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." Draft- 1715 ietf-webdav-protocol-09. Internet Draft, work in progress. Microsoft, 1716 U.C. Irvine, Netscape, Novell. November, 1998. 1718 [DASL] Saveen Reddy, D. Jensen, Surendra Reddy, R. Henderson, J. Davis, 1719 A. Babich, "DAV Searching & Locating." Draft-reddy-dasl-protocol-03. 1720 Internet Draft, work in progress. Microsoft, Novell, Oracle, Netscape, 1721 Xerox, Filenet. November, 1998. 1723 [WebDAVReq] J. Slein, J. Davis, "Requirements for Advanced Collection 1724 Functionality in WebDAV." Draft-ietf-webdav-collection-reqts-02. 1725 Internet Draft, work in progress. Xerox, 1998. 1727 [HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee, 1728 "Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. UC Irvine, DEC, 1729 MIT/LCS. January, 1997. 1731 [XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup 1732 Language (XML)." World Wide Web Consortium Recommendation REC-xml- 1733 19980210. http://www.w3.org/TR/1998/REC-xml-19980210. 1735 18 Authors' Addresses 1737 J. Slein 1738 Xerox Corporation 1739 800 Phillips Road, 105-50C 1740 Webster, NY 14580 1741 Email: jslein@crt.xerox.com 1743 J. Davis 1744 Xerox Corporation 1745 3333 Coyote Hill Road 1746 Palo Alto, CA 94304 1747 Email: jdavis@parc.xerox.com 1749 A. Babich 1750 FileNet Corporation 1751 3565 Harbor Boulevard 1752 Costa Mesa, CA 92626-1420 1753 Email: ababich@filenet.com 1755 E.J. Whitehead Jr. 1756 Dept. of Information and Computer Science 1757 University of California, Irvine 1758 Irvine, CA 92697-3425 1759 Email: ejw@ics.uci.edu 1761 19 Appendices 1763 19.1 Appendix 1 - Extensions to the WebDAV Document Type Definition 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1789 Expires May 10, 1999