idnits 2.17.1 draft-ietf-webdav-collection-protocol-03.txt: -(2891): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 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 52 longer pages, the longest (page 1) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 146 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 2 instances of lines with non-RFC2606-compliant FQDNs in the document. 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 (August 26, 1999) is 9003 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 2622, but not defined ** Obsolete normative reference: RFC 2396 (ref. 'URI') (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' ** Obsolete normative reference: RFC 2068 (ref. 'HTTP') (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2518 (ref. 'WebDAV') (Obsoleted by RFC 4918) Summary: 10 errors (**), 0 flaws (~~), 5 warnings (==), 3 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 T. Chihaya, DataChannel 4 G. Clemm, Rational 5 C. Fay, FileNet 6 E.J. Whitehead Jr., UC Irvine 7 A. Babich, FileNet 8 February 26, 1999 9 Expires August 26, 1999 11 WebDAV Advanced Collections Protocol 13 Status of this Memo 15 This document is an Internet-Draft and is in full conformance with all 16 provisions of Section 10 of RFC2026. Internet-Drafts are working 17 documents of the Internet Engineering Task Force (IETF), its areas, and 18 its working groups. Note that other groups may also distribute working 19 documents as Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference material 24 or to cite them other than as "work in progress". 26 To view the list Internet-Draft Shadow Directories, see 27 http://www.ietf.org/shadow.html. 29 Distribution of this document is unlimited. Please send comments to the 30 Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject 32 "subscribe" to . 34 Discussions of the WEBDAV working group are archived at URL: 35 . 37 Abstract 39 The base WebDAV protocol [WebDAV] provides basic support for 40 collections. It defines a MKCOL method for creating collections and 41 specifies how other HTTP and WebDAV methods interact with collections. 42 It supports internal members of collections, which it defines as URIs 43 that are immediately relative to the URI of the collection. 45 Many applications, however, need more powerful collections. There are 46 two areas in particular where more powerful functionality is often 47 needed: referential resources and ordering. 49 This draft specifies extensions to the base WebDAV protocol to support 50 these more powerful collections. 52 Table of Contents 54 1 Notational Conventions........................................4 55 2 Terminology...................................................4 56 3 Introduction..................................................5 57 4 Referential Resources.........................................5 58 4.1 Scope.........................................................5 59 4.2 Overview......................................................6 60 4.3 Creating Referential Resources................................8 61 4.3.1 The MKREF Method..............................................8 62 4.3.2 Status Codes..................................................9 63 4.3.3 Example: MKREF................................................9 64 4.4 Listing Referential Members of a Collection...................9 65 4.4.1 Example: PROPFIND on a Collection with References............10 66 4.4.2 Example: PROPFIND with No-Passthrough on a Collection with 67 References...................................................12 68 4.5 Copying Referential Resources................................15 69 4.5.1 COPY for Direct References...................................15 70 4.5.2 COPY for Redirect References.................................16 71 4.5.3 Example: COPY on a Direct Reference..........................16 72 4.5.4 Example: COPY on a Redirect Reference........................16 73 4.5.5 Example: COPY on a Collection That Contains a Direct 74 Reference and a Redirect Reference...........................17 75 4.6 Deleting and Moving Referential Resources....................18 76 4.7 Locking Referential Resources................................19 77 4.7.1 LOCK on Direct References....................................19 78 4.7.2 LOCK on Redirect References..................................20 79 4.7.3 Example: LOCK on a Direct Reference..........................21 80 4.7.4 Example: LOCK on a Redirect Reference........................22 81 4.7.5 Example: LOCK on a Collection That Contains a Direct 82 Reference and a Redirect Reference...........................22 83 4.8 Other WebDAV Operations on Redirect Referential Resources....24 84 4.8.1 Example: PROPPATCH on a Redirect Reference...................24 85 4.9 Other WebDAV Operations on Direct Referential Resources......24 86 4.9.1 Example: PROPPATCH on a Direct Reference.....................25 87 4.10 HTTP Operations on Redirect Referential Resources............25 88 4.10.1 Example: GET on a Redirect Reference.........................26 89 4.10.2 Example: GET on a Redirect Reference with No-Passthrough.....26 90 4.11 HTTP Operations on Direct Referential Resources..............26 91 4.11.1 Example: GET on a Direct Reference...........................26 92 4.11.2 Example: GET on a Direct Reference with No-Passthrough.......26 93 4.12 Operations on Targets of Referential Resources...............26 94 4.13 Discovering a Target�s References............................26 95 4.14 Behavior of Dangling Direct References.......................27 96 4.14.1 Example: PROPFIND on a Collection with a Dangling Direct 97 Reference....................................................28 98 4.15 Chains of Direct References..................................29 99 4.16 URIs and References..........................................29 100 5 Ordered Collections..........................................30 101 5.1 Overview.....................................................30 102 5.2 Creating an Ordered Collection...............................31 103 5.2.1 Overview.....................................................31 104 5.2.2 Status Codes.................................................31 105 5.2.3 Example: Creating an Ordered Collection......................31 106 5.3 Setting the Position of a Collection Member..................32 107 5.3.1 Overview.....................................................32 108 5.3.2 Status Codes.................................................32 109 5.3.3 Examples: Setting the Position of a Collection Member........32 110 5.4 Changing the Semantics of a Collection Ordering..............33 111 5.5 Changing the Position of a Collection Member.................33 112 5.5.1 The ORDERPATCH Method........................................33 113 5.5.2 Status Codes.................................................33 114 5.5.3 Example: Changing the Positions of Collection Members in 115 the Ordering.................................................34 116 5.5.4 Design Rationale.............................................35 117 6 Headers......................................................35 118 6.1 Ref-Target Entity Header.....................................35 119 6.1.1 Example: Resolving a Relative URI in Ref-Target..............36 120 6.2 Ref-Type Entity Header.......................................37 121 6.3 Ref-Integrity Request Header.................................37 122 6.4 No-Passthrough Request Header................................37 123 6.5 Ordered Entity Header........................................38 124 6.6 Position Request Header......................................38 125 7 Properties...................................................39 126 7.1 reftarget Property...........................................39 127 7.1.1 Example: Resolving a Relative URI in the DAV:reftarget.......39 128 7.2 refintegrity Property........................................40 129 7.3 reftype Property.............................................41 130 7.4 location Property............................................41 131 7.5 references Property..........................................41 132 7.6 orderingtype Property........................................42 133 8 XML Elements.................................................42 134 8.1 reference XML Element........................................42 135 8.2 direct XML Element...........................................42 136 8.3 redirect XML Element.........................................42 137 8.4 weak XML Element.............................................43 138 8.5 unordered XML Element........................................43 139 8.6 custom XML Element...........................................43 140 8.7 order XML Element............................................43 141 8.8 ordermember XML Element......................................43 142 8.9 position XML Element.........................................44 143 8.10 first XML Element............................................44 144 8.11 last XML Element.............................................44 145 8.12 before XML Element...........................................44 146 8.13 after XML Element............................................44 147 9 Extensions to the DAV:response XML Element for Multi-Status 148 Responses....................................................45 149 10 Capability Discovery.........................................45 150 10.1 Using OPTIONS................................................45 151 10.2 Example: Capability Discovery................................46 152 11 Dependencies on Other Specifications.........................46 153 12 Security Considerations......................................46 154 12.1 Privacy Concerns.............................................46 155 12.2 Redirect Loops...............................................47 156 12.3 References and Denial of Service.............................47 157 12.4 References May Reveal Private Locations......................47 158 12.5 DAV:references and Denial of Service.........................48 159 12.6 DAV:references and Malicious Deletion of Resources...........48 160 12.7 Denial of Service and DAV:orderingtype.......................48 161 13 Internationalization Considerations..........................48 162 14 IANA Considerations..........................................48 163 15 Copyright....................................................49 164 16 Intellectual Property........................................49 165 17 Acknowledgements.............................................49 166 18 References...................................................49 167 18.1 Normative References.........................................49 168 18.2 Informational References.....................................49 169 19 Authors' Addresses...........................................50 170 20 Appendices...................................................50 171 20.1 Appendix 1: Extensions to the WebDAV Document Type 172 Definition...................................................50 173 20.2 Appendix 2: Summary of Referencing Headers Required in 174 Responses....................................................51 175 20.3 Appendix 3: Summary of Method Semantics for References.......52 177 1 Notational Conventions 179 Since this document describes a set of extensions to the HTTP/1.1 180 protocol, the augmented BNF used here to describe protocol elements is 181 exactly the same as described in Section 2.1 of [HTTP]. Since this 182 augmented BNF uses the basic production rules provided in Section 2.2 of 183 [HTTP], these rules apply to this document as well. 185 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 186 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 187 document are to be interpreted as described in [RFC2119]. 189 2 Terminology 191 The terminology used here follows and extends that in the base WebDAV 192 protocol specification [WebDAV]. 194 Collection 195 A resource that contains a set of URIs, termed member URIs, which 196 identify member resources 198 Member URI 199 A URI which is a member of the set of URIs contained by a 200 collection 202 Referential Resource (or Reference) 203 A resource that has no body of its own (though it does have 204 properties), but rather is a reference to another resource 206 Ordinary Resource 207 A resource that is not a reference to another resource 209 Target Resource 210 The resource referenced by a referential resource 212 Direct Reference 213 A reference that is resolved by the server without any client 214 action, giving the client the illusion that it is operating 215 directly on the target resource 217 Redirect Reference 218 A reference that requires client action before it can be resolved, 219 so that the client is aware that a reference is mediating between 220 it and the target resource 222 Strong Reference 223 A reference whose referential integrity is enforced by the server 225 Weak Reference 226 A reference whose referential integrity is not enforced by the 227 server 229 Referential Integrity 230 The integrity of a reference is preserved as long as it points to 231 the same resource it pointed to when it was created. Its 232 integrity may be destroyed if the target resource is moved without 233 updating the reference to reflect its new location, or if the 234 target resource is deleted. 236 3 Introduction 238 The simple collections that the base WebDAV specification supports are 239 powerful enough to be widely useful. They provide for the hierarchical 240 organization of resources, with mechanisms for creating and deleting 241 collections, copying and moving them, locking them, adding members to 242 them and removing members from them, and getting listings of their 243 members. Delete, copy, move, list, and lock operations can be applied 244 recursively, so that a client can operate on whole hierarchies with a 245 single request. 247 Many applications, however, need more powerful collections. There are 248 two areas in particular where more powerful functionality is often 249 needed: references and ordering. 251 References make it possible for many collections, on the same or 252 different servers, to share the same resource. Because the collections 253 share the resource by referencing it, only one physical copy of the 254 resource need exist, and any changes made in the resource are visible 255 from all the collections that reference it. 257 It is useful for many applications to be able to impose an ordering on a 258 collection. Orderings may be based on property values, but they may be 259 completely independent of any properties on the resources identified by 260 the collection�s member URIs. Orderings based on properties can be 261 obtained using a search protocol [DASL], but orderings not based on 262 properties need some other mechanism. 264 Since these two areas are independent of each other, servers may elect 265 to comply with the Referential Resources section of this specification 266 or with the Ordered Collections section or both. A server that supports 267 referencing MUST support redirect references, and MAY support direct 268 references. A server MUST advertise its compliance with particular 269 parts of this specification through its response to an OPTIONS request, 270 as specified in Section 10 below. 272 4 Referential Resources 274 4.1 Scope 276 [CollReq] distinguishes between "weak" references and "strong" 277 references, and also between "redirect" references and "direct" 278 references. This specification supports weak references, direct 279 references, and redirect references, and is designed so that it can be 280 extended to support strong references in the future. 282 Strong references are references whose integrity is enforced by the 283 server; weak references are those whose integrity is not enforced by the 284 server. Strong references and weak references are both useful in 285 different contexts. Some applications cannot tolerate broken links. A 286 software development application, for example, must be able to rely on 287 the integrity of references to component modules. Such applications must 288 be able to request strong references. Other applications may want to 289 reference target resources on multiple servers, where referential 290 integrity cannot be enforced, and may be less concerned about possible 291 broken references. 293 Several considerations led to the decision not to support strong 294 references in the current specification. First, there are many possible 295 policies that applications and services might use in enforcing 296 referential integrity. Some examples are: 298 o Delete strong references when their targets are deleted. 299 o Decline to delete targets of strong references. 300 o Notify strong references when their targets have been deleted. 301 o Replace strong references with copies of their targets before 302 deleting the targets. 304 There appears to be no common practice in this area. Moreover, some of 305 the policies have significant security risks. 307 o Moving a target of strong references could be a security risk to the 308 owner of the target by revealing secret locations on the target's 309 server. 310 o A strong reference could be a security risk to the owner of the 311 reference by revealing secret locations on his server. 312 o The presence of strong references to resources on a server could make 313 it impossible to reclaim space on that server by moving or deleting 314 those target resources. 316 These considerations together led to the decision not to support strong 317 references in the short term. 319 4.2 Overview 321 A referential resource is a resource that has no body of its own, but 322 instead references another resource. The resource it references may 323 have a URI in the same collection as the reference, or in any other 324 collection. This target resource may be a collection or a simple 325 resource or another reference, or any other sort of resource that may be 326 defined in the future. A resource may be the target of any number of 327 referential resources. To make it possible to distinguish references 328 from ordinary resources, a new value of the DAV:resourcetype property is 329 defined here. The DAV:resourcetype property of all references MUST have 330 the value DAV:reference. 332 Redirect references are references that require action by the client 333 before they can be resolved. They are simple for servers to implement, 334 straightforward for clients to use, and have only limited security 335 implications. Any server that complies with WebDAV referencing MUST 336 provide redirect references. 338 If the client is aware that it is operating on a redirect reference, it 339 can resolve the reference by retrieving the reference�s DAV:reftarget 340 property, whose value is the URI of the target resource. It can then 341 submit requests to the target resource. 343 Otherwise, the client submits a request to the redirect reference. For 344 most operations, the response is a 302 (Moved Temporarily), accompanied 345 by the Ref-Type header with the value "DAV:redirect" and the Location 346 header with the URI of the target resource. The client can then 347 resubmit the request to the URI of the target resource. A few 348 operations, for reasons that will be explained, are exceptions to this 349 general behavior. These exceptional operations are applied to the 350 reference itself and do not result in a 302 response. 352 Direct references, in contrast, are resolved automatically by the 353 server. They give the client the illusion that it is operating directly 354 on the target resource. These references are more complex for the 355 server to implement, and raise additional security issues. 356 Consequently, servers are not required to provide direct references in 357 order to be compliant with WebDAV referencing. 359 The default behavior of a direct reference is to apply most operations 360 directly to its target, so that the client is not aware that a reference 361 is mediating between it and the target resource. The exceptions are 362 operations that affect membership in a collection rather than the state 363 of the target resource. At present, the operations that fall into this 364 category are DELETE and MOVE. These operations are applied to the 365 reference itself rather than to its target, so that only the collection 366 containing the reference is affected. 368 The No-Passthrough request header is also provided, to force an 369 operation to be applied to the reference itself rather than its target. 370 It can be used with most requests to direct or redirect references. 371 This header is particularly useful with PROPFIND, to allow clients to 372 view the reference�s own properties. 374 Ideally, non-referencing clients should be able to use both direct and 375 redirect references. This goal is more difficult to meet for redirect 376 references, since client action is required to resolve them. The 377 strategy of having redirect references respond to most requests with a 378 302 (Moved Temporarily), accompanied by the URI of the target resource 379 in the Location header, fulfills this goal in most cases. 381 To distinguish between direct and redirect references, a new DAV:reftype 382 property is defined, with the values DAV:direct and DAV:redirect. Every 383 reference MUST have the DAV:reftype property. The DAV:reftype property 384 of a direct reference MUST have the value DAV:direct. The DAV:reftype 385 property of a redirect reference MUST have the value DAV:redirect. 387 Every reference MUST have the DAV:reftarget property, whose value is the 388 URI of the reference�s target resource. 390 Although strong references are not currently supported, a new 391 DAV:refintegrity property is defined in anticipation of future support 392 for strong references. DAV:refintegrity will allow clients to 393 distinguish between weak and strong references. All references MUST 394 have this property. Although the only currently defined for 395 DAV:refintegrity is DAV:weak, other values may be defined in the future, 396 and servers MAY use extension values to identify their policy for 397 enforcing referential integrity for that resource. 399 4.3 Creating Referential Resources 401 4.3.1 The MKREF Method 403 Referential resources are created using the MKREF method. The request- 404 URI of the MKREF request identifies the resource to be created. The 405 REQUIRED Ref-Target header contains the URI of the target resource. 407 An OPTIONAL Ref-Integrity request header is defined below, primarily for 408 future support for strong references. The only values currently defined 409 for this header are "do-not-enforce" and "enforce", although other 410 values may be used by private agreement. If a server receives the value 411 "do-not-enforce", it MUST NOT enforce referential integrity for the 412 reference being created. If a server receives the value "enforce", it 413 MUST enforce referential integrity for the reference being created, but 414 is free to follow any policy it chooses for enforcing referential 415 integrity. If the Ref-Integrity header is not used with a MKREF 416 request, the server MAY enforce referential integrity, but is not 417 required to do so, and if it does enforce referential integrity, it may 418 do so according to any policy it likes. Clients and servers MAY use 419 other values of Ref-Integrity by private agreement, but if a server 420 receives a value it does not understand, it MUST fail the request. 422 An OPTIONAL Ref-Type general header is defined below, with values 423 "DAV:direct" and "DAV:redirect". The default value is "DAV:redirect" if 424 the header is not present. 426 An OPTIONAL Position request header supports ordered collections by 427 allowing the client creating a reference to specify where the new member 428 is to be placed in the collection's ordering. (This header can also be 429 used with any other method that adds a member to a collection, to 430 specify its position in the collection ordering.) 432 When a server processes a MKREF request, it MUST set the 433 DAV:resourcetype property (defined in [WebDAV]) of the new resource to 434 be DAV:reference. 436 When a server processes a MKREF request, it MUST set the DAV:reftarget 437 property to the URI of the target resource. 439 When a server processes a MKREF request, it MUST set the DAV:reftype 440 property based on the value of the Ref-Type header. 442 When a server processes a MKREF request, it MUST set the 443 DAV:refintegrity property to "DAV:weak" if it is not enforcing 444 referential integrity for the newly-created reference. If it is 445 enforcing referential integrity for the new reference, it MAY set the 446 value of DAV:refintegrity to an extension value identifying its 447 enforcement policy. 449 The client MUST NOT send any content with the MKREF request, and so MUST 450 NOT use the Content-Length or Transfer-Encoding headers. (See [HTTP] 451 Section 4.3.) 453 If a MKREF request has a request-URI that identifies an existing 454 resource, the request MUST fail. This behavior is analogous to the 455 behavior of the MKCOL method [WebDAV]. 457 4.3.2 Status Codes 459 Servers MUST use the HTTP/1.1 status codes as defined in [HTTP]. Some 460 likely client errors for MKREF include: 462 400 (Bad Request): The client attempted to send content with the 463 request, or set an invalid value for the Ref-Target, Ref-Integrity, Ref- 464 Type, or Position header. 466 405 (Method Not Allowed): A resource already exists at the request-URI. 468 409 (Conflict): Several conditions may produce this response. There may 469 be no resource at the location specified in Ref-Target, on a server that 470 prohibits dangling references. The request may be attempting to create 471 the reference in a collection that does not exist. The request may be 472 attempting to position the reference before or after a resource that is 473 not in the collection, or before or after itself. The request may be 474 attempting to position the reference in an unordered collection. 476 4.3.3 Example: MKREF 478 Request: 480 MKREF /~whitehead/dav/spec08.ref HTTP/1.1 481 HOST: www.ics.uci.edu 482 Ref-Target: 484 Response: 486 HTTP/1.1 201 Created 488 This request resulted in the creation of a new referential resource at 489 www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource 490 identified by the Ref-Target header. Its DAV:resourcetype property is 491 set to DAV:reference. Its DAV:reftarget property is set to the URI of 492 its target resource. Its DAV:refintegrity property is set to the value 493 of DAV:weak, indicating that the server will not enforce referential 494 integrity for the new reference. Its DAV:reftype property is set to the 495 default value of DAV:redirect. 497 4.4 Listing Referential Members of a Collection 498 A URI of a reference can be a member of a collection just as the URI of 499 an ordinary resource can. A listing of members of a collection shows 500 all of the URIs in the collection, whether they identify references or 501 ordinary resources. That is, a WebDAV PROPFIND request on a collection 502 resource with Depth = 1 or infinity MUST return a response XML element 503 for each URI in the collection, whether it identifies an ordinary 504 resource or a referential resource. 506 For each direct reference, the properties returned by the PROPFIND MUST 507 be the properties of the target resource unless the No-Passthrough 508 header is included with the PROPFIND request. 510 For each redirect reference, the response element MUST contain a 302 511 (Moved Temporarily) status code unless the No-Passthrough header is 512 included with the PROPFIND request. The DAV:location and DAV:reftype 513 properties MUST be included with the 302 status code, extending the 514 syntax of the DAV:response element that was defined in [WebDAV] as 515 described in Section 9 below. A referencing client can tell from the 516 DAV:reftype property that the collection contains a redirect reference. 517 The DAV:location property contains the absolute URI of the target 518 resource. A referencing client can either use the DAV:location property 519 to retrieve the properties of the target resource or can submit a 520 PROPFIND to the redirect reference with the No-Passthrough header to 521 retrieve its properties. The DAV:location property is expected to be 522 defined in a future revision of [WebDAV], at which time non-referencing 523 clients will also be able to use the response to retrieve the properties 524 of the target resource. 526 If Depth = infinity in the PROPFIND request, the server MUST NOT follow 527 redirect references into any collections to which they may refer. 529 If Depth = infinity in the PROPFIND request, the server MUST follow 530 direct references into any collections to which they may refer unless 531 the No-Passthrough header is used with the request. That is, if the 532 target resource is a collection, the server MUST list the members of 533 that collection. 535 The No-Passthrough header MAY be used with a PROPFIND request on a 536 collection. If the No-Passthrough header is present, then the 537 properties of the references in the collection MUST be returned, 302 538 (Moved Temporarily) status codes MUST NOT be returned for redirect 539 references, direct references MUST NOT pass the request through to their 540 target resources, and the server MUST NOT follow direct references to 541 collections into their target collections. 543 4.4.1 Example: PROPFIND on a Collection with References 545 http://www.svr.com/MyCollection/ 546 (ordinary resource) diary.html 547 (direct reference) tuva 548 (redirect reference) nunavut 550 The target of http://www.svr.com/MyCollection/tuva is a collection: 551 http://www.feynman.com/tuva/ 552 (ordinary resource) history.html 553 (ordinary resource) music.html 555 Request: 557 PROPFIND /MyCollection/ HTTP/1.1 558 Host: www.svr.com 559 Depth: infinity 560 Content-Type: text/xml 561 Content-Length: xxxx 563 564 565 566 567 568 569 571 Response: 573 HTTP/1.1 207 Multi-Status 574 Content-Type: text/xml 575 Content-Length: xxxx 577 578 580 581 http://www.svr.com/MyCollection/ 582 583 584 collection 585 diary, interests, hobbies 586 587 HTTP/1.1 200 OK 588 589 590 591 http://www.svr.com/MyCollection/diary.html 592 593 594 595 diary, travel, family, history 596 597 HTTP/1.1 200 OK 598 599 600 601 http://www.svr.com/MyCollection/tuva 602 603 604 collection 605 history, music, throat-singing 606 607 HTTP/1.1 200 OK 608 609 610 611 http://www.svr.com/MyCollection/tuva/history.html 612 613 614 615 history, language, culture 616 617 HTTP/1.1 200 OK 618 619 620 621 http://www.svr.com/MyCollection/tuva/music.html 622 623 624 625 music, throat-singing 626 627 HTTP/1.1 200 OK 628 629 630 631 http://www.svr.com/MyCollection/nunavut 632 HTTP/1.1 302 Moved Temporarily 633 634 635 http://www.inac.gc.ca/art/inuit/ 636 637 redirect 638 639 640 642 In this example, Depth = infinity and the No-Passthrough header is not 643 used. The collection contains one URI that identifies a redirect 644 reference. The response element for the redirect reference has a status 645 of 302 (Moved Temporarily), and includes a DAV:prop element with the 646 DAV:location and DAV:reftype properties to allow clients to retrieve the 647 properties of its target resource. The collection also contains one URI 648 that identifies a direct reference. The response element for the direct 649 reference contains the properties of its target collection. There are 650 also response elements for each member of its target collection. 652 4.4.2 Example: PROPFIND with No-Passthrough on a Collection with 653 References 655 /MyCollection/ 656 (collection) photos/ 657 (ordinary resource) family.gif 658 (ordinary resource) trip.gif 659 (ordinary resource) diary.html 660 (direct reference) tuva 661 (redirect reference) nunavut 663 Request: 665 PROPFIND /MyCollection/ HTTP/1.1 666 Host: www.svr.com 667 Depth: infinity 668 No-Passthrough: 669 Content-Type: text/xml 670 Content-Length: xxxx 672 673 674 675 676 677 678 679 681 Response: 683 HTTP/1.1 207 Multi-Status 684 Content-Type: text/xml 685 Content-Length: xxxx 687 688 689 690 http://www.svr.com/MyCollection/ 691 692 693 collection 694 695 HTTP/1.1 200 OK 696 697 698 699 HTTP/1.1 404 Not Found 700 701 702 703 http://www.svr.com/MyCollection/photos/ 704 705 706 collection 707 708 HTTP/1.1 200 OK 709 710 711 712 HTTP/1.1 404 Not Found 713 714 715 716 http://www.svr.com/MyCollection/photos/family.gif 717 718 719 720 721 HTTP/1.1 200 OK 722 723 724 725 HTTP/1.1 404 Not Found 726 727 728 729 http://www.svr.com/MyCollection/photos/trip.gif 730 731 732 733 734 HTTP/1.1 200 OK 735 736 737 738 HTTP/1.1 404 Not Found 739 740 741 742 http://www.svr.com/MyCollection/diary.html 743 744 745 746 747 HTTP/1.1 200 OK 748 749 750 751 HTTP/1.1 404 Not Found 752 753 754 755 http://www.svr.com/MyCollection/tuva 756 757 758 reference 759 direct 760 761 http://www.feynman.com/tuva/ 762 763 764 HTTP/1.1 200 OK 765 766 767 768 http://www.svr.com/MyCollection/nunavut 769 770 771 reference 772 redirect 773 774 http://www.inac.gc.ca/art/inuit/ 775 776 777 HTTP/1.1 200 OK 778 779 780 782 Since the No-Passthrough header is present, the response shows the 783 properties of the references in the collection rather than the 784 properties of their targets. Even though Depth = infinity, the No- 785 Passthrough header prevents the server from listing the members of the 786 collection that is the target of the direct reference. No-Passthrough 787 also prevents a 302 response from being returned for the redirect 788 reference. 790 4.5 Copying Referential Resources 792 In determining the semantics of COPY, the desire to provide intuitively 793 correct behavior was weighed against consistency considerations. 795 A client�s intent in performing a COPY operation is to create a new 796 resource that is similar to the original resource and behaves like the 797 original resource, and that can be modified without affecting the 798 original resource. For references to ordinary resources, the 799 expectation would be that the target resource be copied. This would 800 yield an independent resource that could be modified without affecting 801 the original resource. For collections the situation is less clear. 802 There is tension between two expectations. On the one hand, the client 803 may expect the new copy of the collection to behave like the old one 804 (which implies having references where the old one had references). On 805 the other hand, the client may expect that it will be possible to modify 806 the members of the new collection without affecting the members of the 807 old collection (which implies having copies of the targets where the 808 original collection had references). 810 4.5.1 COPY for Direct References 812 COPY follows the general principle that operations on direct references 813 are applied to the target resource unless the No-Passthrough header is 814 used. A COPY on a direct reference MUST be applied to its target 815 resource unless the No-Passthrough header is used. If the No- 816 Passthrough header is used, then the COPY MUST be applied to the direct 817 reference rather than to its target. 819 For consistency, the same is true when a COPY request is sent to a 820 collection, and direct references are encountered inside the collection. 821 Unless the No-Passthrough header is present on the request, the targets 822 of the direct references MUST be copied into the new collection. If the 823 No-Passthrough header is used, then the direct references, and not their 824 targets, MUST be copied into the new collection. 826 These semantics yield intuitively correct results when a COPY request is 827 sent to an individual reference. It is less clear that the results are 828 intuitive when a COPY request is sent to a collection containing direct 829 references, but consistency dictates that we follow the same semantics 830 for this case. A design principle that is followed throughout this 831 specification is that a method behaves the same when it is sent to the 832 URI of a reference as it does when it is sent to a the URI of a 833 collection and encounters a reference inside that collection. 835 4.5.2 COPY for Redirect References 837 For redirect references, the normal behavior would be to respond to a 838 request with a 302 (Moved Temporarily) status code, allowing the client 839 to resubmit the request to the target resource identified in the 840 Location header. This would also yield intuitively correct behavior for 841 COPY. However, it seems undesirable to respond to a COPY request on a 842 collection with a Multi-Status including a 302 response for each 843 redirect reference. To avoid this sort of response, the following rules 844 apply when COPY is sent to redirect references: 846 A COPY on a redirect reference MUST be applied to the reference itself, 847 whether or not the No-Passthrough header is present. 849 The same is true when a COPY request is sent to a collection, and 850 redirect references are encountered inside the collection. Whether or 851 not the No-Passthrough header is present on the request, the redirect 852 references themselves are copied into the new collection, and 302 status 853 codes are not returned for them. 855 4.5.3 Example: COPY on a Direct Reference 857 Request: 859 COPY /MyCollection/tuva HTTP/1.1 860 Host: www.svr.com 861 Destination: http://www.svr.com/OtherCollection/tuva.html 863 Response: 865 HTTP/1.1 204 No Content 866 Ref-Type: direct 867 Ref-Target: /Asia/History/tuva.html 869 In this example, the request-URI identifies a direct reference whose 870 target resource is identified by 871 http://www.svr.com/Asia/History/tuva.html. This target resource was 872 copied to the destination location in the Destination header, 873 http://www.svr.com/OtherCollection/tuva.html. The headers included with 874 the response insure that the client knows that it was operating on a 875 direct reference, and that the client knows which resource was copied. 877 4.5.4 Example: COPY on a Redirect Reference 879 Request: 881 COPY /MyCollection/tuva HTTP/1.1 882 Host: www.svr.com 883 Destination: http://www.svr.com/OtherCollection/tuva.html 885 Response: 887 HTTP/1.1 204 No Content 888 Ref-Type: redirect 889 Ref-Target: /Asia/History/tuva.html 891 In this example, the request-URI identifies a redirect reference whose 892 target resource is identified by 893 http://www.svr.com/Asia/History/tuva.html. In this case, the reference 894 was copied to the destination location in the Destination header, 895 http://www.svr.com/OtherCollection/tuva.html. The Ref-Type header 896 included with the response informs the client that it was operating on a 897 redirect reference. The Ref-Target header provides the information the 898 client needs to copy the target resource, should it wish to do so. 900 The result would have been exactly the same, and the response would have 901 been exactly the same (except that the Ref-Target header would be 902 OPTIONAL), had the No-Passthrough header been used in the request. 904 4.5.5 Example: COPY on a Collection That Contains a Direct Reference and 905 a Redirect Reference 907 /MyCollection/ 908 (ordinary resource) diary.html 909 (direct reference) tuva 910 (redirect reference) nunavut 912 Request: 914 COPY /MyCollection/ HTTP/1.1 915 Host: www.svr.com 916 Destination: http://www.svr.com/OtherCollection/ 918 Response: 920 HTTP/1.1 207 Multi-Status 921 Content-Type: text/xml 922 Content-Length: nnnn 924 925 926 927 tuva 928 HTTP/1.1 201 Created 929 930 direct 931 932 http://www.feynman.com/tuva/ 933 934 935 936 937 nunavut 938 HTTP/1.1 201 Created 939 940 redirect 941 942 http://www.inac.gc.ca/art/inuit/ 943 944 945 946 948 When references are involved, it is not possible to follow the rules in 949 [WebDAV] Section 8.8.3 for reducing the length of responses to COPY 950 requests. Although the entire COPY operation in the example was 951 successful, a Multi-Status response is still REQUIRED, so that the 952 DAV:reftype and DAV:reftarget properties can be returned for the 953 references in the collection. The results for each reference MUST be 954 reported in a separate DAV:response element so that it is clear which 955 reference is associated with which values of DAV:reftype and 956 DAV:reftarget. In this case, since /MyCollection/tuva is a direct 957 reference, its target resource was copied into the new collection. 958 Since /MyCollection/nunavut is a redirect reference, the reference 959 itself, and not its target, was copied into the new collection. There 960 are no response elements for the collection /MyCollection/ or for the 961 ordinary resource /MyCollection/diary.html, since they were successfully 962 copied and no special information needs to be returned for them. 964 4.6 Deleting and Moving Referential Resources 966 The DELETE method is used to delete referential resources. For both 967 direct and redirect references, DELETE MUST affect the reference itself, 968 and not its target. Similarly, when a DELETE on a collection encounters 969 a reference in the subtree under that collection, it MUST delete the 970 reference, and not its target. 972 A MOVE operation on a referential resource MUST move the referential 973 resource to a different location, and MUST NOT change the location of 974 its target. The DAV:reftarget property is unchanged after a MOVE. 975 Similarly, when a MOVE on a collection encounters a reference in the 976 subtree under that collection, it MUST move the reference, and not its 977 target. 979 DELETE and MOVE differ from other methods in that they do not alter the 980 resource that is being deleted or moved, but rather the collection that 981 contains its URI. They change the membership of that collection. 983 When a reference is added to a collection, the aim is to make it look as 984 if the target resource were a member of that collection. When the 985 reference is removed from that collection, the aim is to change the 986 membership of that collection. Membership of the target in any other 987 collections, either internally or by reference, should not be affected. 988 Consequently, DELETE and MOVE do not follow the normal rules of behavior 989 for references. Instead, they are always applied to the reference 990 itself, not to its target, and they never result in 302 status codes. 992 Although clients MAY use the No-Passthrough header with DELETE and MOVE 993 requests, the header has no effect on their behavior. Whether the No- 994 Passthrough header is present or not, they are always applied to the 995 reference. 997 [WebDAV] defines MOVE to be logically equivalent to COPY followed by 998 DELETE. For direct references, MOVE is logically equivalent to COPY 999 with the No-Passthrough header followed by DELETE. 1001 4.7 Locking Referential Resources 1003 The semantics of LOCK described here resulted from balancing a set of 1004 incompatible considerations: 1006 o Ideally, a LOCK on a reference should lock both the reference and its 1007 target resource. The owner of an exclusive write lock, for example, 1008 would be surprised if anyone else could modify the content of the 1009 target resource while he held the lock. He would also be surprised 1010 if anyone else could delete the reference to it, or replace the 1011 reference with one pointing to a different target. 1013 o Non-referencing clients should be able to use both direct and 1014 redirect references without encountering surprising results. 1016 o Preserve the clear distinction between redirect and direct 1017 references. Redirect references should be simple for servers to 1018 implement. In particular, a server should never have to resolve a 1019 redirect reference. A server should not have to provide proxy 1020 capabilities in order to implement redirect references. Direct 1021 references rely on more sophisticated server capabilities to give 1022 clients the illusion of operating directly on the target resource. 1024 o There should be consistency between the behavior of LOCK on a single 1025 referential resource and the behavior of LOCK on a collection that 1026 contains referential resources. 1028 o Keep the behavior of all requests to references as consistent as 1029 possible. Try to adhere to the general rule that in the absence of a 1030 No-Passthrough header, all methods return a 302 when sent to a 1031 redirect reference and are applied to the target when sent to a 1032 direct reference. 1034 o Be consistent with the LOCK semantics defined in [WebDAV]. 1036 We have compromised the intuitive locking behavior and support for non- 1037 referencing clients in order to preserve various sorts of consistency. 1039 4.7.1 LOCK on Direct References 1041 LOCK follows the general principle that operations on direct references 1042 are applied to the target resource unless the No-Passthrough header is 1043 used. When a LOCK request is sent to a direct reference without the No- 1044 Passthrough header, the target resource MUST be locked. When a LOCK 1045 request with the No-Passthrough header is sent to a direct reference, 1046 the reference itself MUST be locked. 1048 A principle followed throughout this specification is that behavior when 1049 a reference is encountered during an operation on a collection must be 1050 the same as behavior when operating on an individual reference. When a 1051 LOCK request with Depth > 0 is sent to a collection, the targets of any 1052 direct references encountered MUST be locked, unless the No-Passthrough 1053 header is used. If the No-Passthrough header is present on a LOCK 1054 request with Depth > 0 to a collection, then any direct references 1055 encountered MUST themselves be locked. 1057 As was noted above, more intuitive results would have been obtained by 1058 requiring that both the reference and its target to be locked in 1059 response to a LOCK request. Reference-aware clients can obtain this 1060 result by performing two LOCK operations, one with the No-Passthrough 1061 header and one without. Non-referencing clients cannot do so. This 1062 means that for non-referencing clients there is always the risk that a 1063 referencing client may delete or replace the reference that was used to 1064 lock a target resource while the non-referencing client has the target 1065 locked. To insure intuitive results for non-referencing clients, 1066 referencing clients SHOULD be designed to check whether the target 1067 resource is locked before replacing, moving, or deleting a direct 1068 reference. 1070 UNLOCK behaves as specified in [WebDAV], unlocking all resources 1071 included in the lock identified by the Lock-Token header. 1073 4.7.2 LOCK on Redirect References 1075 The behavior of LOCK for redirect references was determined by what is 1076 possible for the case of locking collections that contain redirect 1077 references. 1079 The expected behavior for any operation on a redirect reference is that 1080 a 302 (Moved Temporarily) response will be returned, unless the No- 1081 Passthrough header is used. However, this policy would have 1082 unacceptable consequences when locking a collection that contains 1083 redirect references. Since [WebDAV} requires LOCK on a collection to be 1084 an atomic operation, if a 302 response is received for any member of the 1085 collection, the entire LOCK must fail. This would make it impossible to 1086 lock any collection that contained a redirect reference. 1088 To avoid this result, a LOCK on a collection with Depth > 0 MUST lock 1089 any redirect references it encounters, and not return 302 responses for 1090 them, whether or not the No-Passthrough header is used. 1092 This gives part of the expected lock behavior without forcing the server 1093 to resolve the redirect reference or become a proxy server in cases 1094 where the target resides on a different server. 1096 Each DAV:response element for a redirect reference MUST include the 1097 DAV:reftype and DAV:reftarget properties so that a referencing client 1098 can lock the targets if it wishes. (There will be no hint in any 1099 response code that there are redirect references whose targets need to 1100 be locked. The client will most likely not lock any targets until it 1101 attempts an operation on the target and gets a 302 response.) Non- 1102 referencing clients cannot lock the targets of the redirect references 1103 and may never realize that the targets have not been locked. 1105 Clearly, a LOCK with Depth = infinity on a collection MUST NOT follow 1106 any redirect references whose targets are collections into the target 1107 collections; it MUST NOT cause any members of those target collections 1108 to be locked. 1110 The behavior of LOCK for individual redirect references is designed to 1111 be consistent with LOCK behavior for collections that contain redirect 1112 references. Whether or not a No-Passthrough header is present, a LOCK 1113 on a redirect reference MUST lock only the reference, not its target, 1114 and it MUST NOT return a 302 response. The response MUST include the 1115 Ref-Type and Ref-Target headers, so that a referencing client can lock 1116 the target resource if it wishes. 1118 UNLOCK behaves as specified in [WebDAV], unlocking all resources 1119 included in the lock identified by the Lock-Token header. 1121 4.7.3 Example: LOCK on a Direct Reference 1123 Request: 1125 LOCK /MyCollection/tuva HTTP/1.1 1126 Host: www.svr.com 1127 Content-Type: text/xml 1128 Content-Length: nnnn 1129 Authorizaton: Digest username="jas", 1130 realm=jas@webdav.sb.aol.com, nonce=". . .", 1131 uri="/MyCollection/tuva", 1132 response=". . .", opaque=". . ." 1134 1135 1136 1137 1138 1139 http://www.svr.com/~jas/contact.html 1140 1141 1143 Response: 1145 HTTP/1.1 200 OK 1146 Ref-Type: direct 1147 Ref-Target: /Asia/History/tuva.html 1148 Content-Type: text/xml 1149 Content-Length: nnnn 1151 1152 1153 1154 1155 1156 1157 0 1158 1159 http://www.svr.com/~jas/contact.html 1160 1161 1162 opaquelocktoken:e71dfae-5dec-22d6-fea5-00a0c91e6be4 1163 1164 1165 1166 1168 In this example, the request-URI identifies a direct reference whose 1169 target resource is identified by 1170 http://www.svr.com/Asia/History/tuva.html. This target resource was 1171 locked. The Ref-Type and Ref-Target headers included with the response 1172 insure that the client knows that it was operating on a direct 1173 reference, and that the client knows which resource was locked. 1175 4.7.4 Example: LOCK on a Redirect Reference 1177 4.7.5 Example: LOCK on a Collection That Contains a Direct Reference and 1178 a Redirect Reference 1180 /MyCollection/ 1181 (ordinary resource) diary.html 1182 (direct reference) tuva 1183 (redirect reference) nunavut 1185 Request: 1187 LOCK /MyCollection/ HTTP/1.1 1188 Host: www.svr.com 1189 Content-Type: text/xml 1190 Content-Length: nnnn 1191 Authorizaton: Digest username="jas", 1192 realm=jas@webdav.sb.aol.com, nonce=". . .", 1193 uri="/MyCollection/tuva", 1194 response=". . .", opaque=". . ." 1196 1197 1198 1199 1200 1201 http://www.svr.com/~jas/contact.html 1202 1203 1205 Response: 1207 HTTP/1.1 207 Multi-Status 1208 Content-Type: text/xml 1209 Content-Length: nnnn 1211 1212 1213 1214 /MyCollection/ 1215 HTTP/1.1 200 OK 1216 1217 1218 1219 1220 1221 0 1222 1223 http://www.svr.com/~jas/contact.html 1224 1225 1226 opaquelocktoken:e71dfae-5dec-22d6-fea5-00a0c91e6be4 1227 1228 1229 1230 1231 1232 1233 /MyCollection/tuva 1234 HTTP/1.1 200 OK 1235 1236 direct 1237 1238 http://www.feynman.com/tuva/ 1239 1240 1241 1242 1243 /MyCollection/nunavut 1244 HTTP/1.1 200 OK 1245 1246 redirect 1247 1248 http://www.inac.gc.ca/art/inuit/ 1249 1250 1251 1252 1254 Although the entire LOCK operation was successful, a Multi-Status 1255 response is still REQUIRED, so that the DAV:reftype and DAV:reftarget 1256 properties can be returned for the references in the collection. The 1257 results for each reference MUST be reported in a separate DAV:response 1258 element so that it is clear which reference is associated with which 1259 values of DAV:reftype and DAV:reftarget. In this case, since 1260 /MyCollection/tuva is a direct reference, its target resource was 1261 locked. Since /MyCollection/nunavut is a redirect reference, the 1262 reference itself, and not its target, was locked. There is no response 1263 element for the ordinary resource /MyCollection/diary.html, since it was 1264 successfully locked and no special information needs to be returned for 1265 it. 1267 4.8 Other WebDAV Operations on Redirect Referential Resources 1269 Although non-referencing WebDAV clients cannot create referential 1270 resources, they should be able to use the references created by 1271 reference-aware WebDAV clients. They should be able to follow any 1272 references to their targets. To make this possible, a server that 1273 receives a PROPFIND, PROPPATCH, MKCOL, or MKREF request made via a 1274 redirect reference MUST return a 302 (Moved Temporarily) status code. 1275 The client and server MUST follow [HTTP] Section 10.3.3 "302 Moved 1276 Temporarily," but with these additional rules: 1278 o The Location response header MUST contain the target URI of the 1279 reference. 1281 o The response MUST include the Ref-Type header. This header allows 1282 reference-aware WebDAV clients to recognize the resource as a 1283 reference and understand the reason for the redirection. 1285 A reference-aware WebDAV client can act on this response in one of two 1286 ways. It can, like a non-referencing client, resubmit the request to 1287 the URI in the Location header in order to operate on the target 1288 resource. Alternatively, it can resubmit the request to the URI of the 1289 redirect reference with the No-Passthrough header in order to operate on 1290 the reference itself. If the No-Passthrough header is present, the 1291 request MUST be applied to the reference itself, and a 302 response MUST 1292 NOT be returned. 1294 If a reference-aware client knows before submitting its request that the 1295 request-URI identifies a redirect reference, it can save the round trip 1296 caused by the 302 response by using No-Passthrough in its initial 1297 request to the URI. 1299 Since MKCOL and MKREF fail when applied to existing resources, if the 1300 client attempts to resubmit the request to the target resource, the 1301 request MUST fail (unless the reference is a dangling reference). 1302 Similarly, if the client attempts to resubmit the request to the 1303 reference with a No-Passthrough header, the request MUST fail. 1305 4.8.1 Example: PROPPATCH on a Redirect Reference 1307 4.9 Other WebDAV Operations on Direct Referential Resources 1309 With the exception of DELETE and MOVE, which were discussed above, 1310 operations on direct references affect the target resource, not the 1311 reference, unless the No-Passthrough header is used. 1313 Unless the No-Passthrough header is used, a PROPPATCH on a direct 1314 reference MUST modify the properties of its target resource, not the 1315 properties of the reference itself. 1317 Unless the No-Passthrough header is used, a PROPFIND on a direct 1318 reference MUST return the properties of its target resource, not the 1319 properties of the reference itself. 1321 If the No-Passthrough header is used with a PROPPATCH or PROPFIND 1322 request on a direct reference, the operation MUST be applied to the 1323 reference itself rather than to its target resource. 1325 MKCOL and MKREF fail if their request-URI identifies an existing 1326 resource of any kind. Consequently, when submitted to a target resource 1327 via a direct reference, they MUST fail unless the reference is a 1328 dangling reference. If they are submitted to an existing direct 1329 reference with the No-Passthrough header, they MUST also fail. 1331 4.9.1 Example: PROPPATCH on a Direct Reference 1333 4.10 HTTP Operations on Redirect Referential Resources 1335 Although existing HTTP clients cannot create referential resources, they 1336 should be able to use collections created by reference-aware WebDAV 1337 clients. They should be able to follow any references identified by 1338 URIs in those collections to their targets. To enable existing HTTP 1339 clients to use GET, HEAD, PUT, POST, or OPTIONS via redirect references, 1340 a server that receives any of these requests on a redirect reference 1341 MUST return a 302 (Moved Temporarily). The client and server MUST 1342 follow [HTTP] Section 10.3.3 "302 Moved Temporarily," but with these 1343 additional rules: 1345 o The Location response header MUST contain the target URI of the 1346 reference. 1348 o The response MUST include the Ref-Type header. This header allows 1349 reference-aware WebDAV clients to recognize the resource as a 1350 reference and understand the reason for the redirection. 1352 Reference-aware clients can act on a 302 response in either of two ways. 1353 Like plain HTTP clients, they can resubmit the request to the URI in the 1354 Location header (the URI of the target resource). They may, however, 1355 want to operate on the reference rather than on its target. In this 1356 case, they may resubmit the request to the URI of the reference and 1357 include the No-Passthrough header with the request. If the No- 1358 Passthrough header is present, the request MUST be applied to the 1359 reference itself, and a 302 response MUST NOT be returned. 1361 If a reference-aware client knows before submitting its request that the 1362 request-URI identifies a redirect reference, it can save the round trip 1363 caused by the 302 response by using No-Passthrough in its initial 1364 request to the URI. 1366 The No-Passthrough header can be used with GET or HEAD to retrieve the 1367 entity headers of a redirect reference. When No-Passthrough is used 1368 with GET or HEAD, the referencing entity headers (Ref-Type and Ref- 1369 Target) MUST be returned, along with all HTTP headers that make sense 1370 for references (at a minimum, Cache-Control, Age, ETag, Expires, and 1371 Last-Modified). 1373 The No-Passthrough header can be used with PUT to replace the redirect 1374 reference with an ordinary resource. It can be used with OPTIONS to 1375 retrieve the capabilities of a redirect reference. 1377 Clients MUST NOT, however, use the No-Passthrough header with POST. 1378 Since a reference cannot accept another entity as its subordinate, an 1379 attempt to POST to a reference with No-Passthrough will also fail. If a 1380 server receives a POST request with the No-Passthrough header on a 1381 redirect reference, it MUST fail the request with a 400 (Bad Request) 1382 status code. 1384 4.10.1 Example: GET on a Redirect Reference 1386 4.10.2 Example: GET on a Redirect Reference with No-Passthrough 1388 4.11 HTTP Operations on Direct Referential Resources 1390 GET, HEAD, PUT, POST, and OPTIONS on direct references are automatically 1391 passed through to their target resources. GET MUST return the content 1392 and headers of the target resource, HEAD MUST return the headers of the 1393 target resource, PUT MUST replace the content of the target resource, 1394 POST MUST perform the expected function at the target resource, and 1395 OPTIONS MUST report the communication options available at the target 1396 resource. 1398 The No-Passthrough request header MAY be used with GET, HEAD, PUT, or 1399 OPTIONS to view the headers or capabilities of the reference, rather 1400 than its target. 1402 The No-Passthrough request header MUST NOT be used with POST, which 1403 cannot be applied to references. If a server receives a POST request on 1404 a direct reference with the No-Passthrough header, it MUST fail the 1405 request with a 400 (Bad Request) status code. 1407 4.11.1 Example: GET on a Direct Reference 1409 4.11.2 Example: GET on a Direct Reference with No-Passthrough 1411 4.12 Operations on Targets of Referential Resources 1413 In general, operations on targets of weak referential resources have no 1414 effect on the referential resource. However, servers that choose to 1415 maintain the integrity of references are free to make changes to the 1416 state of references when moving or deleting their targets. 1418 When moving a target resource, a server MAY insert an optional step into 1419 the semantics of MOVE as defined in [WebDAV] for the purpose of 1420 maintaining referential integrity. Between the copy step and the delete 1421 step of a MOVE, the server MAY perform an update step, which changes the 1422 DAV:reftarget property of any references to the target to reflect its 1423 new location. 1425 When deleting a target resource, a server MAY perform any internal 1426 operations necessary to implement its policy on preserving referential 1427 integrity. For example, it might delete any references to the deleted 1428 target, or it might flag them as having a deleted target, or it might 1429 replace references with copies of the target. 1431 4.13 Discovering a Target�s References 1432 An OPTIONAL DAV:references property on the target resource provides a 1433 list of referential resources whose DAV:reftarget property points to 1434 that target resource. If present, DAV:references is a read-only 1435 property, maintained by the server. By retrieving this property, a 1436 client can discover the URIs of the references that point to the target, 1437 and so can also discover the collections that contain those URIs as 1438 members. As for all DAV: properties, this specification is silent as to 1439 how the DAV:references property is implemented on the server. 1441 The DAV:references property is expected to be supported mainly by 1442 Document Management Systems (DMSs) and other servers that will maintain 1443 the property only for references within their own domain. It is not in 1444 general possible for a server to maintain the property for references on 1445 other servers. If a reference on a different server points to the 1446 target, the server where the target is located is unlikely to know about 1447 that reference. This protocol provides no mechanism for one server to 1448 notify another of the creation of a reference to one of its resources. 1449 Consequently, the list of references in DAV:reftarget may be incomplete. 1451 Rationale: A number of scenarios require clients to navigate from a 1452 target resource to the references that point to it, and to the 1453 collections that contain the URIs of those references. This capability 1454 is particularly important for DMSs, which may populate their collections 1455 entirely by reference. Their clients may need to determine, for any 1456 object in the DMS, what collections contain URIs that identify 1457 references to that object. It is also important in other contexts. For 1458 example, some servers enforce referential integrity by refusing to 1459 delete any resource that is referenced by other resources. In such an 1460 environment, the client must be able to discover the references in order 1461 to delete them before attempting to delete the target. 1463 Risks: When deciding whether to support the DAV:references property, 1464 server implementers / administrators should balance the benefits it 1465 provides against the cost of maintaining the property and the security 1466 risks enumerated in Sections 12.4 and 12.5. 1468 4.14 Behavior of Dangling Direct References 1470 Whenever the No-Passthrough header accompanies a request on a dangling 1471 direct reference, the request succeeds. Since No-Passthrough causes the 1472 request to be applied to the reference rather than to its target, it 1473 does not matter that the target resource does not exist. The client 1474 will not be informed that the reference points to a nonexistent target. 1476 In the absence of the No-Passthrough header, the responses MUST be as 1477 follows: 1479 GET, HEAD, OPTIONS, POST, PROPFIND, PROPPATCH, LOCK, UNLOCK, and COPY 1480 respond with 404 (Not Found), but the Ref-Type and Ref-Target headers 1481 are included in the response, so that the client can tell that it is the 1482 target, and not the reference, that was not found. 1484 If, however, a PROPFIND, LOCK, UNLOCK, or COPY with Depth header greater 1485 than 0 on a collection encounters a dangling direct reference inside the 1486 collection, the response is a 207 (Multi-Status). The DAV:response 1487 element for the dangling reference will have a status of 404 (Not 1488 Found). The DAV:reftype and DAV:reftarget properties of the references 1489 are included in the response. Their presence informs the client that it 1490 is the target, not the reference, that was not found. Including these 1491 two properties requires an extension to the DAV:response element as 1492 defined in {WEBDAV]. This extension is defined in Section 9 below. 1494 PUT succeeds, creating a new resource at the location specified by the 1495 reference�s DAV:reftarget property. 1497 MKREF and MKCOL succeed, since there is no existing resource at the 1498 target URI. 1500 MOVE and DELETE succeed, since they always affect the reference rather 1501 than its target. For MOVE, the reference at the destination will be 1502 broken, just as the reference at the source was. 1504 4.14.1 Example: PROPFIND on a Collection with a Dangling Direct 1505 Reference 1507 Request: 1509 PROPFIND /collection1/ HTTP/1.1 1510 Host: www.somehost.com 1511 Depth: 1 1512 Content-Type: text/xml 1513 Content-Length: xxxx 1515 1516 1517 1518 1519 1520 1521 1523 Response: 1525 HTTP/1.1 207 Multi-Status 1526 Content-Type: text/xml 1527 Content-Length: xxxx 1529 1530 1531 1532 http://www.somehost.com/collection1/ 1533 1534 1535 Smith, J.H. 1536 My Working Collection 1537 1538 HTTP/1.1 200 OK 1539 1540 1541 1542 http://www.somehost.com/collection1/directref7 1543 HTTP/1.1 404 Not Found 1544 1545 1546 1547 /collection2/file19 1548 1549 1550 Target resource not found. 1551 1552 1553 1555 4.15 Chains of Direct References 1557 Unless a No-Passthrough header is present, any operation on a direct 1558 reference that is part of a chain of direct references MUST get passed 1559 through to the target of the last reference in the chain. 1561 Whenever a response is required to include the Ref-Target header, for a 1562 chain of direct references, there MUST be a Ref-Target header for each 1563 reference in the chain. In order for the client to know which reference 1564 in the chain each Ref-Target belongs to, the value of each Ref-Target 1565 header MUST include a hop-number of the reference as well as the URL of 1566 its target resource. For example, 1568 Request: 1570 HEAD /math/ref1 HTTP/1.1 1571 Host: www.somehost.edu 1573 Response: 1575 HTTP/1.1 200 ok 1576 Ref-Type: direct 1577 Ref-Target: 0; /logic/ref2 1578 Ref-Target: 1; /library/ref3 1579 Ref-Target: 2; /library/frege/grundgesetze.html 1580 . 1581 . 1583 A server cannot tell whether a dangling reference once pointed to an 1584 ordinary resource or to another reference in a chain of direct 1585 references. When a break occurs before the end of a chain of direct 1586 references, the server�s behavior will be the same as for any other 1587 dangling direct reference, as described in Section 4.13. For example, a 1588 PUT will create the new resource at the location specified by the 1589 DAV:reftarget property of the broken reference, even if that is in the 1590 middle of what was once a chain of direct references. 1592 4.16 URIs and References 1594 In a request-URI /segment1/segment2/segment3, any of the three segments 1595 may identify a reference. (See [URI], Section 3.3, for definitions of 1596 "path" and "segment".) Servers will be unable to resolve such URIs 1597 unless certain constraints hold. If any segment of the path identifies 1598 a reference, that reference MUST ultimately resolve to a resource that 1599 behaves as a container. (Examples are WebDAV collections, tar files, 1600 and some CGI scripts.) The succeeding segment of the path MUST resolve 1601 to a resource that is immediately contained in that container. 1603 Consider request-URI /x/y/z.html. Suppose that /x/ is a reference whose 1604 target is collection /a/, which contains reference y whose target is 1605 collection /b/, which contains reference z.html whose target is 1606 /c/d.html. 1608 /x/ -----> /a/ 1609 /a/y/ -----> /b/ 1610 /b/z.html -----> /c/d.html 1612 The server is able to resolve the request-URI because each segment of 1613 the URI's path satisfies the constraints stated above. Except for the 1614 final segment, each segment that is a reference resolves to a collection 1615 that contains the next segment as an internal member. The final 1616 segment, which is a reference, does have a target resource. 1618 If the references are direct references, the server automatically 1619 applies the request to the ultimate target, /c/d.html. 1621 If the references are redirect references, the client must follow up 1622 three separate 302 responses before finally reaching the target 1623 resource. The server responds to the initial request with a 302 with 1624 Location: /a/y/z.html, and the client resubmits the request to 1625 /a/y/z.html. The server responds to this request with a 302 with 1626 Location: /b/z.html, and the client resubmits the request to /b/z.html. 1627 The server responds to this request with a 302 with Location: /c/d.html, 1628 and the client resubmits the request to /c/d.html. This final request 1629 succeeds. 1631 5 Ordered Collections 1633 5.1 Overview 1635 Collections on a compliant server may be ordered, but need not be. It 1636 is up to the client to decide whether a given collection is ordered and, 1637 if so, to specify the semantics to be used for ordering its members. If 1638 a collection is ordered, each of its members must be in the ordering 1639 exactly once, and the ordering must not include any resource that is not 1640 a member of the collection. Only one ordering can be attached to any 1641 collection. Multiple orderings of the same resources can be achieved by 1642 creating multiple collections referencing those resources, and attaching 1643 a different ordering to each collection. 1645 The server is responsible for enforcing these constraints on orderings. 1646 The server MUST remove a member URI from the ordering when it is removed 1647 from the collection. The server MUST add a member URI to the ordering 1648 when it is added to the collection. 1650 When responding to a PROPFIND on a collection, the server MUST order the 1651 response elements according to the ordering defined on the collection. 1653 5.2 Creating an Ordered Collection 1655 5.2.1 Overview 1657 When a collection is created, the client can request that it be ordered 1658 and specify the semantics of the ordering by using the new Ordered 1659 header in the MKCOL request, setting its value to the URI of the 1660 semantics to be used or setting its value to DAV:custom if the semantics 1661 are not being advertised. If the client does not want the collection to 1662 be ordered, it may omit the Ordered header, or use it with the value 1663 "DAV:unordered". 1665 Every collection MUST have the new DAV:orderingtype property, which 1666 indicates whether the collection is ordered and, if so, identifies the 1667 semantics of the ordering. A value of DAV:unordered indicates that that 1668 collection is not ordered. That is, the client cannot depend on the 1669 repeatability of the ordering of results from a PROPFIND request. For 1670 collections that are ordered, DAV:orderingtype SHOULD be set to an href 1671 that identifies the semantics of the ordering, allowing a human user or 1672 software package to insert new collection members into the ordering 1673 intelligently. Although the href MAY point to a resource that contains 1674 a definition of the semantics of the ordering, clients are discouraged 1675 from accessing that resource, in order to avoid overburdening its 1676 server. The DAV:orderingtype property MAY be set to DAV:custom to 1677 indicate that the collection is to be ordered, but the semantics of the 1678 ordering is not being advertised. 1680 If the Ordered header is present on a MKCOL request, the server MUST set 1681 the collection's DAV:orderingtype property to the value of the Ordered 1682 header. If the Ordered header is not present, the server MUST treat the 1683 request as if it had an Ordered header with the value "DAV:unordered", 1684 meaning that the collection is not ordered. If the collection is 1685 ordered, the server MUST respond to PROPFIND requests on the collection 1686 using the specified ordering. 1688 5.2.2 Status Codes 1690 Servers MUST use the HTTP/1.1 status codes as defined in [HTTP]. 1692 5.2.3 Example: Creating an Ordered Collection 1694 Request: 1696 MKCOL /theNorth/ HTTP/1.1 1697 Host: www.server.org 1698 Ordered: 1700 Response: 1702 HTTP/1.1 201 Created 1704 In this example, a new, ordered collection was created. Its 1705 DAV:orderingtype property has as its value the URI from the Ordered 1706 header. In this case, the URI identifies the semantics governing the 1707 ordering. As new members are added to the collection, clients or end 1708 users can use the semantics to determine where to position the new 1709 members in the ordering. 1711 5.3 Setting the Position of a Collection Member 1713 5.3.1 Overview 1715 When a new member is added to a collection (for example, with PUT, 1716 MKREF, or MKCOL), its position in the ordering can be set with the new 1717 Position header. The Position header allows the client to specify that 1718 the member should be first in the collection's ordering, last in the 1719 collection's ordering, before some other collection member in the 1720 collection's ordering, or after some other collection member in the 1721 collection's ordering. 1723 The server MUST insert the new member into the ordering at the location 1724 specified in the Position header, if one is present (and if the 1725 collection is ordered); otherwise, it MUST append the new member to the 1726 end of the ordering (if the collection is ordered). If a PUT causes an 1727 existing resource to be replaced, and if the Position header is absent, 1728 the server MUST leave the member at its previous position in thee 1729 collection ordering. If the Position header is present, the server MUST 1730 remove the member from its previous position, and then insert it at the 1731 requested position. 1733 5.3.2 Status Codes 1735 Servers MUST use the HTTP/1.1 status codes as defined in [HTTP]. Some 1736 likely client errors for when setting the position of a collection 1737 member include: 1739 409 (Conflict): The request may be attempting to position the collection 1740 member before or after a URI that is not in the collection, or before or 1741 after itself, or it may be attempting to position the collection member 1742 in an unordered collection. 1744 5.3.3 Examples: Setting the Position of a Collection Member 1746 Request: 1748 MKREF /~whitehead/dav/spec08.ref HTTP/1.1 1749 HOST: www.ics.uci.edu 1750 Ref-Target: 1751 Position: After 1753 Response: 1755 HTTP/1.1 201 Created 1757 This request resulted in the creation of a new referential resource at 1758 www.ics.uci.edu/~whitehead/dav/spec08.ref, which points to the resource 1759 identified by the Ref-Target header. The Position header in this 1760 example caused the server to set its position in the ordering of the 1761 /~whitehead/dav/ collection immediately after requirements.html. 1763 Request: 1765 MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 1766 Host: www.ics.uci.edu 1767 Destination: 1768 Position: First 1770 Response: 1772 HTTP/1.1 409 Conflict 1774 In this case, the server returned a 409 Conflict status code because the 1775 /~whitehead/dav/ collection is an unordered collection. Consequently, 1776 the server was unable to satisfy the Position header. 1778 5.4 Changing the Semantics of a Collection Ordering 1780 After a collection has been created, a client can change its ordering 1781 semantics, or change an ordered collection to an unordered collection or 1782 vice versa, by using PROPPATCH to change the value of its 1783 DAV:orderingtype property. The client is then responsible for updating 1784 the ordering of the collection members according to the new semantics. 1785 PROPPATCH is defined in [WebDAV], Section 7.2. 1787 5.5 Changing the Position of a Collection Member 1789 5.5.1 The ORDERPATCH Method 1791 To change the positions of collection members in the collection's 1792 ordering, the client MUST use an ORDERPATCH request with a request body 1793 containing an order XML element. The request-URI of an ORDERPATCH 1794 request is the URI of the collection whose ordering is to be updated. 1795 The order XML element identifies the member URIs whose positions are to 1796 be changed, and describes their new positions in the ordering. Each new 1797 position can be specified as first in the ordering, last in the 1798 ordering, before some other collection member in the ordering, or after 1799 some other collection member in the ordering. The server MUST apply the 1800 changes in the order they appear in the order element. 1802 5.5.2 Status Codes 1804 Since multiple changes can be requested in a single ORDERPATCH request, 1805 the server MUST return a 207 Multi-Status response, as defined in 1806 [WebDAV]. 1808 Within the 207 Multi-Status response, the following status codes are 1809 possible: 1811 200 (OK): The change in ordering was successfully made. 1813 409 (Conflict): An attempt was made to position the collection member 1814 before or after a URI that is not in the collection, or before or after 1815 itself, or an attempt was made to position the collection member in an 1816 unordered collection. 1818 A request to reposition a collection member to the same place in the 1819 ordering is not an error. 1821 5.5.3 Example: Changing the Positions of Collection Members in the 1822 Ordering 1824 Consider a collection /coll-1/ with members ordered as follows: 1826 nunavut.map 1827 nunavut.img 1828 baffin.map 1829 baffin.desc 1830 baffin.img 1831 iqaluit.map 1832 nunavut.desc 1833 iqaluit.img 1834 iqaluit.desc 1836 Request: 1838 ORDERPATCH /coll-1/ HTTP/1.1 1839 Host: www.nunanet.com 1840 Content-Type: text/xml 1841 Content-Length: xxx 1843 1844 1845 1846 nunavut.desc 1847 1848 1849 nunavut.map 1850 1851 1852 1853 1854 iqaluit.img 1855 1856 1857 1858 1859 1861 Response: 1863 HTTP/1.1 207 Multi-Status 1864 Content-Type: text/xml 1865 Content-Length: xxx 1867 1868 1869 1870 http://www.nunanet.com/coll-1/nunavut.desc 1871 HTTP/1.1 200 OK 1872 1873 1874 http://www.nunanet.com/coll-1/iqaluit.img 1875 HTTP/1.1 200 OK 1876 1877 1879 In this example, after the request has been processed, the collection's 1880 ordering is as follows: 1882 nunavut.map 1883 nunavut.desc 1884 nunavut.img 1885 baffin.map 1886 baffin.desc 1887 baffin.img 1888 iqaluit.map 1889 iqaluit.desc 1890 iqaluit.img 1892 5.5.4 Design Rationale 1894 The decision to introduce the new ORDERPATCH method was made after 1895 investigating the possibility of using the existing MOVE method with a 1896 Position header. The use of MOVE initially looked appealingly simple: 1898 MOVE /root/coll-1/foo HTTP/1.1 1899 Host: www.somehost.com 1900 Destination: 1901 Position: First 1903 Unfortunately, several features of the semantics of MOVE make it 1904 unsuitable for changing the position of a collection member in the 1905 collection's ordering. First, [WebDAV] defines MOVE as logically 1906 equivalent to a copy followed by a delete of the source resource. This 1907 definition makes it impossible to MOVE a resource to a destination URL 1908 that is the same as the source URL. The resource would be deleted 1909 rather than moved. Second, [WebDAV] states that when moving a resource 1910 to a destination where a resource already exists, the Overwrite header 1911 must be "T", and in this case the server must DELETE the resource at the 1912 destination before performing the MOVE. Again, this makes it impossible 1913 to MOVE a resource to the same location. Finally, [WebDAV] states that 1914 locks are lost on a MOVE, an outcome that seems undesirable in this 1915 case. 1917 6 Headers 1919 6.1 Ref-Target Entity Header 1921 Ref-Target = "Ref-Target" ":" 1#([hop-count ";"] Coded-url) 1922 hop-count = 1*DIGIT 1923 Coded-url is defined in [WebDAV], Section 8.4. 1925 In general, the Ref-Target header has the simpler form: 1927 Ref-Target = "Ref-Target" ":" Coded-url 1929 The more complicated syntax is provided only for use in responses 1930 involving chains of direct references. 1932 The Ref-Target header is used with MKREF requests to identify the target 1933 resource of the new referential resource being created. It is a 1934 REQUIRED header in MKREF requests. When used with a MKREF request, its 1935 value is simply a Coded-url, and only a single value is allowed. For an 1936 example, see Section 4.3.3. 1938 Servers MUST include the Ref-Target header in responses to the following 1939 types of requests: 1941 Reference Type | No-Passthrough | Method 1942 -------------------------------------------------------------- 1943 direct or redirect | Present | GET, HEAD 1944 -------------------------------------------------------------- 1945 direct | Absent | All except MKREF, UNLOCK 1946 -------------------------------------------------------------- 1947 redirect | Absent | COPY, LOCK, DELETE, MOVE 1949 The only case where multiple values of Ref-Target are allowed is when it 1950 is included in a response for a reference that is part of a chain of 1951 direct references. In this case, the response MUST include a value of 1952 Ref-Target for each reference in the chain. Each value MUST include a 1953 hop-count, starting with 0, indicating which reference in the chain that 1954 Ref-Target belongs to. For an example, see Section 4.14. 1956 The Coded-url in a Ref-Target header MAY be a relative URI. If it is a 1957 relative URI, the base URI to be used for resolving it to absolute form 1958 has as its scheme component "http", as its authority component the value 1959 of the Host: header from the request, and as its path component the 1960 request-URI from the request. See [URI] Section 5 for a discussion of 1961 relative URI references and how to resolve them. 1963 6.1.1 Example: Resolving a Relative URI in Ref-Target 1965 Request: 1967 PUT /north/inuvik HTTP/1.1 1968 Host: www.somehost.edu 1969 Content-Type: image/gif 1970 Content-Length: nnnnnn 1972 1974 Response: 1976 HTTP/1.1 200 ok 1977 Ref-Type: direct 1978 Ref-Target: mapcollection/inuvik.gif 1980 In this example, the base URI is http://www.somehost.edu/north/inuvik. 1982 The relative URI in Ref-Target resolves to the absolute URI 1983 http://www.somehost.edu/north/mapcollection/inuvik.gif. 1985 6.2 Ref-Type Entity Header 1987 Ref-Type = "Ref-Type" ":" ("DAV:direct" | "DAV:redirect") 1989 The Ref-Type header is defined to distinguish between direct and 1990 redirect references. The possible values of this header are DAV:direct 1991 and DAV:redirect. If the header is not present on a MKREF request, the 1992 server MUST treat the request as if it has a Ref-Type header with the 1993 value DAV:redirect. 1995 Servers MUST include the Ref-Target header in every response to a 1996 request whose request-URI identifies a reference, with the exception of 1997 responses to MKREF requests. 1999 6.3 Ref-Integrity Request Header 2001 Ref-Integrity = "Ref-Integrity" ":" ("do-not-enforce" | "enforce" | 2002 extend) 2003 extend = 1#CHAR 2005 The Ref-Integrity header is defined primarily to allow future support 2006 for strong references. It specifies whether the server should enforce 2007 referential integrity for a referential resource being created with 2008 MKREF. 2010 The value "do-not-enforce" means that the server MUST NOT enforce 2011 referential integrity for the newly created reference. A client might 2012 use this value if, for example, it wanted to populate a collection with 2013 references before their content was made available on the Web. 2015 The value "enforce" means that the server MUST enforce referential 2016 integrity for the newly created reference, but does not constrain the 2017 server to use any particular policy for enforcing referential integrity. 2018 It is beyond the scope of this specification to define precisely the 2019 meaning of referential integrity or to enumerate any set of policies 2020 that might be considered compliant. 2022 Clients and servers may use other values of the Ref-Integrity header by 2023 private agreement, to specify more precisely the desired policy for 2024 enforcing referential integrity. If a server receives an extension 2025 value that it does not understand, it MUST fail the request. 2027 If the Ref-Integrity header is not present on a MKREF request, the 2028 server MAY enforce referential integrity or not, and if it does enforce 2029 referential integrity, it MAY follow any policy it chooses. 2031 6.4 No-Passthrough Request Header 2033 No-Passthrough = "No-Passthrough" ":" 2035 The optional No-Passthrough header can be used on any request to a 2036 reference except POST. For a direct reference, if the No-Passthrough 2037 header is present, the request MUST be applied to the reference itself 2038 rather than to its target. For a redirect reference, if the No- 2039 Passthrough header is present, the request MUST be applied to the 2040 reference itself, and a 302 response MUST NOT be returned. If the No- 2041 Passthrough header is used on a request to any other sort of resource 2042 besides a reference, the server SHOULD ignore it. If the No-Passthrough 2043 header is used with a POST request to a reference, the server MUST 2044 respond with a 400 (Bad Request). 2046 The No-Passthrough header can be used with PROPFIND requests on 2047 collections with Depth = infinity. When it is used in this way, the 2048 server MUST return the properties of any redirect references in the 2049 collection, and not return 302 (Moved Temporarily) status codes for 2050 them. It MUST also return the properties of any direct references in 2051 the collection (not the properties of their targets), and it MUST NOT 2052 follow any direct references to collections into their target 2053 collections. 2055 The No-Passthrough header can be used with LOCK requests on collections 2056 with Depth = infinity. When it is used in this way, the server MUST 2057 lock any redirect references in the collection, just as it would if the 2058 No-Passthrough header were absent. It MUST also lock any direct 2059 references in the collection (not their target resources), and it MUST 2060 NOT follow any direct references to collections into their target 2061 collections. 2063 The No-Passthrough header can be used with COPY requests on collections 2064 with Depth > 0. When it is used in this way, the server MUST copy any 2065 redirect references in the collection, just as it would if the No- 2066 Passthrough header were absent. It MUST also copy any direct references 2067 in the collection (not their target resources), and it MUST NOT follow 2068 any direct references to collections into their target collections. 2070 6.5 Ordered Entity Header 2072 Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url) 2074 The Ordered header may be used with MKCOL to request that the new 2075 collection be ordered and to specify its ordering semantics. A value of 2076 "DAV:unordered" indicates that the collection is not ordered. That is, 2077 the client cannot depend on the repeatability of the ordering of results 2078 from a PROPFIND request. A Coded-url value indicates that the collection 2079 is ordered, and identifies the semantics of the ordering, allowing a 2080 human user or software package to insert new collection members into the 2081 ordering intelligently. The Coded-url MAY point to a resource that 2082 contains a definition of the semantics of the ordering. A value of 2083 "DAV:custom" indicates that the collection is to be ordered, but the 2084 semantics of the ordering is not being advertised. 2086 If the Ordered header is not present on a MKCOL request, the server MUST 2087 treat the request as if it had an Ordered header with the value 2088 "DAV:unordered". 2090 6.6 Position Request Header 2091 Position = "Position" ":" ("First" | "Last" | 2092 (("Before" | "After") Coded-url)) 2094 The Position header may be used with any method that adds a member to a 2095 collection to tell the server where in the collection ordering to 2096 position the new member being added to the collection. It may be used 2097 for both ordinary and referential members. 2099 If the Coded-url is a relative URL, it is interpreted relative to the 2100 collection to which the new member is being added. 2102 If the Position request header is not used, then: 2104 If the request is replacing an existing resource, the server MUST 2105 preserve the present ordering. 2107 If the request is adding a new member to the collection, the server MUST 2108 append the new member to the end of the ordering (if the collection is 2109 ordered). 2111 7 Properties 2113 7.1 reftarget Property 2115 Name: reftarget 2116 Namespace: DAV: 2117 Purpose: A REQUIRED property of referential resources that provides 2118 an efficient way for clients to discover the URI of the 2119 target resource. This is a read-only property, whose value 2120 can only be set by using the Ref-Target header with a MKREF 2121 request. 2122 Value: URI of the target resource. This value MAY be a relative 2123 URI. The reftarget property can occur in the entity bodies 2124 of responses to a variety of requests. It always occurs in 2125 the context of a Multi-Status response, inside a 2126 DAV:response element that has a single DAV:href element. 2127 The value of this DAV:href element serves as the base URI 2128 for resolving a relative URI in DAV:reftarget. (The value 2129 of DAV:href may itself be relative, in which case it must be 2130 resolved first in order to serve as the base URI for the 2131 relative URI in DAV:reftarget.) See [URI] Section 5 for a 2132 discussion of relative URI references and how to resolve 2133 them. 2135 2137 7.1.1 Example: Resolving a Relative URI in the DAV:reftarget 2139 Request: 2141 PROPFIND /geog/ HTTP/1.1 2142 Host: www.xxsvr.com 2143 No-Passthrough: 2144 Depth: 1 2145 Content-Type: text/xml 2146 Content-Length: nnn 2148 2149 2150 2151 2152 2153 2154 2155 2157 Response: 2159 HTTP/1.1 207 Multi-Status 2160 Content-Type: text/xml 2161 Content-Length: nnn 2163 2164 2165 2166 /geog/ 2167 2168 2169 collection 2170 2171 HTTP/1.1 200 ok 2172 2173 2174 /D:prop> 2175 HTTP/1.1 404 Not Found 2176 2177 2178 2179 /geog/stats.html 2180 2181 2182 reference 2183 direct 2184 statistics/population/1997.html 2185 2186 HTTP/1.1 200 ok 2187 2188 2189 2191 In this example, the relative URI statistics/population/1997.html is 2192 returned as the value of reftarget for the reference identified by href 2193 /geog/stats.html. The href is itself a relative URI, which resolves to 2194 http://www.xxsrv.com/geog/stats.html. This is the base URI for 2195 resolving the relative URI in reftarget. The absolute URI of reftarget 2196 is http://www.xxsrv.com/geog/statistics/population/1997.html. 2198 7.2 refintegrity Property 2200 Name: refintegrity 2201 Namespace: DAV: 2202 Purpose: A REQUIRED property of a referential resource that indicates 2203 whether the server enforces referential integrity for that 2204 reference. The refintegrity property is defined to allow 2205 future support for strong references. The only value 2206 currently defined for refintegrity is weak, which means that 2207 the server does not enforce referential integrity for the 2208 reference. Although a server may assign another value to 2209 identify its policy for enforcing referential integrity for 2210 the reference, it cannot count on clients understanding such 2211 extension values. This is a readonly property. 2212 Value: weak or an extension value 2214 2216 7.3 reftype Property 2218 Name: reftype 2219 Namespace: DAV: 2220 Purpose: A required property of a referential resource that 2221 identifies the reference as direct or redirect. This is a 2222 read-only property, whose value can only be set by using 2223 the Ref-Type header with a MKREF request. 2224 Value: direct | redirect 2226 2228 7.4 location Property 2230 Name: location 2231 Namespace: DAV: 2232 Purpose: For use with 302 (Moved Temporarily) response codes in 2233 Multi-Status responses. It contains the absolute URI of the 2234 temporary location of the resource. In the context of 2235 redirect references, this value is the absolute URI of the 2236 target resource. It is analogous to the Location header in 2237 HTTP 302 responses defined in [HTTP] Section 10.3.3 "302 2238 Moved Temporarily." Including the location property in a 2239 Multi-Status response requires an extension to the syntax of 2240 the DAV:response element defined in [WebDAV], which is 2241 defined in Section 9 below. This property is not expected 2242 to be stored on the reference. It is modeled as a property 2243 only so that it can be returned inside a DAV:prop element in 2244 a Multi-Status response. 2245 Value: href containing the absolute URI of the target resource. 2247 2249 7.5 references Property 2251 Name: references 2252 Namespace: DAV: 2253 Purpose: Enables clients to discover, for any target resource, what 2254 references point to it and what collections contain it by 2255 reference. This is an optional property. If present, it is 2256 a read-only property, maintained by the server. 2257 Value: List of the URIs of the references that point to the target 2258 resource. 2260 2262 7.6 orderingtype Property 2264 Name: orderingtype 2265 Namespace: DAV: 2266 Purpose: Indicates whether the collection is ordered and, if so, 2267 uniquely identifies the semantics of the ordering being 2268 used. May also point to an explanation of the semantics in 2269 human and / or machine-readable form. At a minimum, this 2270 allows human users who add members to the collection to 2271 understand where to position them in the ordering. 2272 Value: unordered for an unordered collection, or a URI that 2273 uniquely identifies the semantics of the collection's 2274 ordering. The URI MAY point to a definition of the ordering 2275 semantics. The value custom may be used for a collection 2276 that is to be ordered, but for which the semantics are not 2277 being advertised. 2279 2281 8 XML Elements 2283 8.1 reference XML Element 2285 Name: reference 2286 Namespace: DAV: 2287 Purpose: A new value of the DAV:resourcetype property that identifies 2288 its resource as a referential resource. The 2289 DAV:resourcetype property of a referential resource MUST 2290 have this value. 2291 Value: EMPTY 2293 2295 8.2 direct XML Element 2297 Name: direct 2298 Namespace: DAV: 2299 Purpose: A value for the DAV:reftype property that identifies its 2300 resource as a direct reference. 2301 Value: EMPTY 2303 2305 8.3 redirect XML Element 2307 Name: redirect 2308 Namespace: DAV: 2309 Purpose: A value for the DAV:reftype property that identifies its 2310 resource as a redirect reference. 2312 Value: EMPTY 2314 2316 8.4 weak XML Element 2318 Name: weak 2319 Namespace: DAV: 2320 Purpose: A value of the DAV:refintegrity property. It means that the 2321 server does not enforce referential integrity for the 2322 reference to which the property belongs. 2323 Value: EMPTY 2325 2327 8.5 unordered XML Element 2329 Name: unordered 2330 Namespace: DAV: 2331 Purpose: A value of the DAV:orderingtype property that indicates that 2332 the collection is not ordered. That is, the client cannot 2333 depend on the repeatability of the ordering of results from 2334 a PROPFIND request. 2335 Value: EMPTY 2337 2339 8.6 custom XML Element 2341 Name: custom 2342 Namespace: DAV: 2343 Purpose: A value of the DAV:orderingtype property that indicates that 2344 the collection is ordered, but the semantics of the ordering 2345 are not being advertised. 2346 Value: EMPTY 2348 2350 8.7 order XML Element 2352 Name: order 2353 Namespace: DAV: 2354 Purpose: For use with the new ORDERPATCH method. Describes a change 2355 to be made in a collection ordering. 2356 Value: A description of the new positions of collection members in 2357 the collection's ordering. 2359 2361 8.8 ordermember XML Element 2363 Name: ordermember 2364 Namespace: DAV: 2365 Purpose: Occurs in the order XML Element, and describes the new 2366 position of a single collection member in the collection's 2367 ordering. 2368 Value: An href containing a relative URI, and a description of its 2369 new position in the ordering. The href XML element is 2370 defined in [WebDAV], Section 11.3. 2372 2374 8.9 position XML Element 2376 Name: position 2377 Namespace: DAV: 2378 Purpose: Occurs in the member XML element. Describes the new 2379 position in a collection's ordering of one of the 2380 collection's members. 2381 Value: The new position can be described as first in the 2382 collection's ordering, last in the collection's ordering, 2383 before some other member of the collection, or after some 2384 other member of the collection. 2386 2388 8.10 first XML Element 2390 Name: first 2391 Namespace: DAV: 2392 Purpose: Occurs in the position XML element. Describes the 2393 collection member's position as first in the collection's 2394 ordering. 2395 Value: EMPTY 2397 2399 8.11 last XML Element 2401 Name: last 2402 Namespace: DAV: 2403 Purpose: Occurs in the position XML element. Describes the 2404 collection member's position as last in the collection's 2405 ordering. 2406 Value: EMPTY 2408 2410 8.12 before XML Element 2412 Name: before 2413 Namespace: DAV: 2414 Purpose: Occurs in the position XML element. Describes the 2415 collection member's position as coming before some other 2416 collection member in the collection's ordering. 2417 Value: href of the member it precedes in the ordering 2419 2421 8.13 after XML Element 2422 Name: after 2423 Namespace: DAV: 2424 Purpose: Occurs in the position XML element. Describes the 2425 collection member's position as coming after some other 2426 collection member in the collection's ordering. 2427 Value: href of the member it follows in the ordering 2429 2431 9 Extensions to the DAV:response XML Element for Multi-Status Responses 2433 As described in Sections 4.5 and 4.6, the DAV:location property and the 2434 DAV:reftype property may be returned in the DAV:response element of a 2435 207 Multi-Status response, to allow clients to resubmit their requests 2436 to the target resource of a redirect reference. 2438 As described in Section 4.13, the DAV:reftype and DAV:reftarget 2439 properties may be returned in the DAV:response element of a 207 Multi- 2440 Status response, to indicate that a problem is not with a direct 2441 reference, but with its target resource. 2443 Whenever these properties are included in a Multi-Status response, they 2444 will be placed in a DAV:prop element associated with the href to which 2445 they apply. This structure provides a framework for future extensions 2446 by other standards that may need to include additional properties in 2447 their responses. 2449 Consequently, the definition of the DAV:response XML element changes to 2450 the following: 2452 2455 10 Capability Discovery 2457 10.1 Using OPTIONS 2459 Since referencing and ordering are independent capabilities, a resource 2460 MAY support either or both. A resource that provides referencing MUST 2461 support redirect references, and MAY in addition support direct 2462 references. A response to an OPTIONS request MUST indicate which of 2463 these capabilities the resource supports. 2465 This specification defines two new methods: MKREF in support of 2466 referencing, and ORDERPATCH in support of ordering. The response MUST 2467 indicate which of these methods the resource allows. In addition, the 2468 response MUST include the DAV header, as described in Sections 9.1 and 2469 15 of [WebDAV]. Three new compliance classes are defined here for use 2470 with the DAV header: basicref, directref, and orderedcoll. 2472 When responding to an OPTIONS request, only a collection or a null 2473 resource can include orderedcoll in the value of the DAV header. By 2474 including orderedcoll, the resource indicates that its immediate member 2475 URIs can be ordered. It implies nothing about whether any collections 2476 identified by its member URIs can be ordered. 2478 When responding to an OPTIONS request, any type of resource can include 2479 basicref or directref in the value of the DAV header. Including 2480 basicref indicates that the server permits a redirect reference at the 2481 request URI. Including directref indicates that the server permits a 2482 direct reference at the request URI. 2484 10.2 Example: Capability Discovery 2486 Request: 2488 OPTIONS /somecollection/ HTTP/1.1 2489 HOST: somehost.org 2491 Response: 2493 HTTP/1.1 200 OK 2494 Date: Tue, 20 Jan 1998 20:52:29 GMT 2495 Connection: close 2496 Accept-Ranges: none 2497 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 2498 PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, ORDERPATCH 2499 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, 2500 PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, ORDERPATCH 2501 DAV: 1, 2, basicref, directref, orderedcoll 2503 This response indicates that the resource /somecollection/ is level 1 2504 and level 2 compliant, as defined in [WebDAV]. In addition, 2505 /somecollection/ supports ordering and is in a part of the server 2506 namespace that allows creation of redirect and direct references. (In 2507 light of the semantics of MKREF, the resource currently at 2508 /somecollection/ would have to be deleted before a reference could be 2509 created at that URI.) 2511 11 Dependencies on Other Specifications 2513 TBD 2515 12 Security Considerations 2517 This section is provided to detail issues concerning security 2518 implications of which WebDAV applications need to be aware. 2520 All of the security considerations of HTTP/1.1 and the base WebDAV 2521 protocol also apply to WebDAV collections. In addition, referential 2522 resources and ordered collections introduce several new security 2523 concerns and increase the risk of some existing threats. These issues 2524 are detailed below. 2526 12.1 Privacy Concerns 2528 By creating references on a trusted server, it is possible for a hostile 2529 agent to induce users to send private information to a target on a 2530 different server. This risk is mitigated somewhat for redirect 2531 references, since clients are required to notify the user of the 2532 redirection for any request other than GET or HEAD. (See [HTTP], Section 2533 10.3.3 Moved Temporarily.) For direct references, clients can determine 2534 the resource type, reference type, and target location before sending a 2535 request, but are not required to notify users if the target is on 2536 another server. 2538 12.2 Redirect Loops 2540 Although redirect loops were already possible in HTTP 1.1, the 2541 introduction of referential resources creates a new avenue for clients 2542 to create loops accidentally or maliciously. If the referential 2543 resource and its target are on the same server, the server may be able 2544 to detect MKREF requests that would create loops. See also [HTTP], 2545 Section 10.3 "Redirection 3xx." 2547 12.3 References and Denial of Service 2549 Denial of service attacks were already possible by posting URLs that 2550 were intended for limited use at heavily used Web sites. The 2551 introduction of referential resources creates a new avenue for similar 2552 denial of service attacks. Clients can now create references at heavily 2553 used sites to target locations that were not designed for heavy usage. 2555 12.4 References May Reveal Private Locations 2557 There are several ways that the referencing mechanisms described here 2558 may reveal information about directory structures. First, the 2559 DAV:reftarget property of every reference contains the URI of the target 2560 resource. Anyone who has access to the reference can discover the 2561 directory path that leads to the target resource. The owner of the 2562 target resource may have wanted to limit knowledge of this directory 2563 structure. 2565 Sufficiently powerful access control mechanisms can control this risk to 2566 some extent. Property-level access control could prevent users from 2567 examining the DAV:reftarget property. (The Ref-Target header, which is 2568 returned in most responses to requests on direct references, reveals the 2569 same information, however.) In some environments, the owner of a 2570 resource might be able to use access control to prevent others from 2571 creating references to that resource. 2573 Second, although this specification does not require servers to maintain 2574 referential integrity, it does not prevent them from doing so. If a 2575 server updates a reference�s DAV:reftarget property when its target 2576 resource is moved, there is the risk that a private location will be 2577 revealed in the new value of DAV:reftarget. Clients can avoid this risk 2578 by doing a COPY followed by a DELETE rather than a MOVE. 2580 Finally, if backpointers are maintained on the target resource, the 2581 owners of references face these same risks. The directory structures 2582 where references are located are revealed to anyone who has access to 2583 the DAV:references property on a target resource. Moving a reference 2584 may reveal its new location to anyone with access to DAV:references on 2585 its target resource. 2587 12.5 DAV:references and Denial of Service 2589 If the server maintains the DAV:references property in response to 2590 references created in other administrative domains, it is exposed to 2591 hostile attempts to make it devote resources to adding references to the 2592 list. 2594 12.6 DAV:references and Malicious Deletion of Resources 2596 Servers that support the DAV:references property should insure that 2597 clients cannot create editable properties with the name DAV:references. 2598 An editable DAV:references property would constitute a security risk on 2599 servers that enforce referential integrity by deleting references when 2600 their target is deleted. These servers could be tricked into deleting a 2601 resource by listing it in the DAV:references property of some target 2602 resource. 2604 12.7 Denial of Service and DAV:orderingtype 2606 There may be some risk of denial of service at sites that are advertised 2607 in the DAV:orderingtype property of collections. However, it is 2608 anticipated that widely-deployed applications will use hard-coded values 2609 for frequently-used ordering semantics rather than looking up the 2610 semantics at the location specified by DAV:orderingtype. 2612 13 Internationalization Considerations 2614 This specification follows the practices of [WebDAV] in encoding all 2615 human-readable content using XML [XML] and in the treatment of names. 2616 Consequently, this specification complies with the IETF Character Set 2617 Policy [Alvestrand]. 2619 WebDAV applications MUST support the character set tagging, character 2620 set encoding, and the language tagging functionality of the XML 2621 specification. This constraint ensures that the human-readable content 2622 of this specification complies with [Alvestrand]. 2624 As in [WebDAV}, names in this specification fall into three categories: 2625 names of protocol elements such as methods and headers, names of XML 2626 elements, and names of properties. Naming of protocol elements follows 2627 the precedent of HTTP, using English names encoded in USASCII for 2628 methods and headers. The names of XML elements used in this 2629 specification are English names encoded in UTF-8. 2631 For error reporting, [WebDAV] follows the convention of HTTP/1.1 status 2632 codes, including with each status code a short, English description of 2633 the code (e.g., 423 Locked). Internationalized applications will ignore 2634 this message, and display an appropriate message in the user's language 2635 and character set. 2637 For rationales for these decisions and advice for application 2638 implementors, see [WebDAV]. 2640 14 IANA Considerations 2641 This document uses the namespaces defined by [WebDAV] for properties and 2642 XML elements. All other IANA considerations mentioned in [WebDAV] also 2643 apply to this document. 2645 15 Copyright 2647 To be supplied. 2649 16 Intellectual Property 2651 To be supplied. 2653 17 Acknowledgements 2655 This draft has benefited from thoughtful discussion by Jim Amsden, Steve 2656 Carter, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Rajiv 2657 Dulepet, David Durand, Roy Fielding, Yaron Goland, Fred Hitt, Alex 2658 Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, 2659 Daniel LaLiberte, Steve Martin, Surendra Koduru Reddy, Sam Ruby, Bradley 2660 Sergeant, Nick Shelness, John Stracke, John Tigue, John Turner, and 2661 others. 2663 18 References 2665 18.1 Normative References 2667 [URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource 2668 Identifiers (URI): Generic Syntax." RFC 2396. MIT/LCS, U.C. Irvine, 2669 Xerox. August, 1998. 2671 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement 2672 Levels." RFC 2119, BCP 14. Harvard University. March, 1997. 2674 [XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup 2675 Language (XML)." World Wide Web Consortium Recommendation REC-xml- 2676 19980210. http://www.w3.org/TR/1998/REC-xml-19980210. 2678 [HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee, 2679 "Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. UC Irvine, DEC, 2680 MIT/LCS. January, 1997. 2682 [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. 2683 Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." RFC 2518. 2684 Microsoft, U.C. Irvine, Netscape, Novell. February, 1999. 2686 18.2 Informational References 2688 [DASL] Saveen Reddy, D. Jensen, Surendra Reddy, R. Henderson, J. Davis, 2689 A. Babich, "DAV Searching & Locating." Draft-reddy-dasl-protocol-03. 2690 Internet Draft, work in progress. Microsoft, Novell, Oracle, Netscape, 2691 Xerox, Filenet. November, 1998. 2693 [CollReq] J. Slein, J. Davis, "Requirements for Advanced Collection 2694 Functionality in WebDAV." Draft-ietf-webdav-collection-reqts-02. 2696 Internet Draft, work in progress. Xerox. February, 1999. 2698 19 Authors' Addresses 2700 J. Slein 2701 Xerox Corporation 2702 800 Phillips Road, 105-50C 2703 Webster, NY 14580 2704 Email: jslein@crt.xerox.com 2706 J. Davis 2707 Xerox Corporation 2708 3333 Coyote Hill Road 2709 Palo Alto, CA 94304 2710 Email: jdavis@parc.xerox.com 2712 T. Chihaya 2713 DataChannel, Inc. 2714 155 108th Ave. N.E., Suite 400 2715 Bellevue, WA 98004 2716 Email: Tyson@DataChannel.com 2718 G. Clemm 2719 Rational Software Corporation 2720 20 Maguire Road 2721 Lexington, MA 02173-3104 2722 Email: gclemm@rational.com 2724 C. Fay 2725 FileNet Corporation 2726 3565 Harbor Boulevard 2727 Costa Mesa, CA 92626-1420 2728 Email: cfay@filenet.com 2730 E.J. Whitehead Jr. 2731 Dept. of Information and Computer Science 2732 University of California, Irvine 2733 Irvine, CA 92697-3425 2734 Email: ejw@ics.uci.edu 2736 A. Babich 2737 FileNet Corporation 2738 3565 Harbor Boulevard 2739 Costa Mesa, CA 92626-1420 2740 Email: ababich@filenet.com 2742 20 Appendices 2744 20.1 Appendix 1: Extensions to the WebDAV Document Type Definition 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2771 20.2 Appendix 2: Summary of Referencing Headers Required in Responses 2773 This section summarizes the rules that determine which referencing 2774 headers are included in responses to requests on references. The 2775 normative statements that are summarized here can be found in Sections 2776 4.5 - 4.10, 4.13, 4.14, 6.1, and 6.2. 2778 Reference Type | No-Passthrough | Method | Headers Included in 2779 | | | Response 2780 ----------------------------------------------------------------------- 2781 both |Present / Absent| All except | Ref-Type 2782 | | MKREF, UNLOCK | 2783 ----------------------------------------------------------------------- 2784 both |Present | GET, HEAD | Ref-Target 2785 ----------------------------------------------------------------------- 2786 direct |Absent | All except | Ref-Target 2787 | | MKREF, UNLOCK | 2788 ----------------------------------------------------------------------- 2789 redirect |Absent | COPY, LOCK, | Ref-Target 2790 | | DELETE, MOVE | 2792 o Every response to a request on a reference includes the Ref-Type 2793 header, so that the client knows that it was operating on a 2794 reference, and can understand the behavior of the reference. 2796 o Since [HTTP] requires responses to GET and HEAD to include all entity 2797 headers, Ref-Target is included in all responses to GET and HEAD 2798 requests on references with the No-Passthrough header. 2800 o For all other requests with the No-Passthrough header, the client is 2801 aware that it is operating on the reference rather than the target, 2802 so the Ref-Target header is OPTIONAL. 2804 o When the No-Passthrough header is absent from a request on a direct 2805 reference, the target resource is affected. Consequently, the Ref- 2806 Target header is required. This allows the client to tell what 2807 resource was affected by the operation. The exceptions are MKREF, 2808 since the client knows the value of Ref-Target that it sent in the 2809 request, and UNLOCK, which affects just the resources that were 2810 locked with the same lock token. 2812 o When the No-Passthrough header is absent from a request on a direct 2813 reference, in most cases the response is a 302 with the Location 2814 header. The Location header contains the URI of the target resource. 2815 Consequently, the Ref-Target header is OPTIONAL in the response. 2816 COPY, LOCK, DELETE, and MOVE do not return a 302 response, but 2817 instead operate on the reference. For these methods, a Ref-Target 2818 header is REQUIRED in the response. This allows the client to locate 2819 the target resource in case it wants to resubmit the request to the 2820 target. 2822 Requests on collections with Depth header greater than 0 typically get 2823 Multi-Status responses. Consequently, information about any references 2824 in the collection cannot be returned in headers. Instead, the 2825 corresponding DAV properties are returned in the DAV:response elements 2826 for the references. 2828 20.3 Appendix 3: Summary of Method Semantics for References 2830 This section summarizes the semantics of each HTTP and WebDAV method 2831 when the request-URI identifies a reference. The normative statements 2832 that are summarized here can be found in Sections 4.3 - 4.10. 2834 For each method, there are four cases to consider: 2836 o Request-URI identifies a redirect reference, and the No-Passthrough 2837 header is not used 2838 o Request-URI identifies a redirect reference, and the No-Passthrough 2839 header is present 2840 o Request-URI identifies a direct reference, and the No-Passthrough 2841 header is not used 2842 o Request-URI identifies a direct reference, and the No-Passthrough 2843 header is present 2845 When the No-Passthrough header is used, the situation is simple. For 2846 all methods, the request is applied to the reference, not to its target 2847 resource. 2849 The following table summarizes behavior for the cases where the No- 2850 Passthrough header is not used: 2852 METHOD | REDIRECT REFERENCE | DIRECT REFERENCE 2853 --------------------------------------------------------------------- 2854 GET | Respond with 302 status code | Apply method to target 2855 --------------------------------------------------------------------- 2856 HEAD | Respond with 302 status code | Apply method to target 2857 --------------------------------------------------------------------- 2858 OPTIONS | Respond with 302 status code | Apply method to target 2859 --------------------------------------------------------------------- 2860 PUT | Respond with 302 status code | Apply method to target 2861 --------------------------------------------------------------------- 2862 POST | Respond with 302 status code | Apply method to target 2863 --------------------------------------------------------------------- 2864 MKCOL | Respond with 302 status code | Apply method to target 2865 | | (fails unless dangling) 2866 --------------------------------------------------------------------- 2867 MKREF | Respond with 302 status code | Apply method to target 2868 | | (fails unless dangling) 2869 --------------------------------------------------------------------- 2870 PROPPATCH | Respond with 302 status code | Apply method to target 2871 --------------------------------------------------------------------- 2872 PROPFIND | Respond with 302 status code | Apply method to target 2873 ===================================================================== 2874 DELETE | Apply method to reference | Apply method to reference 2875 --------------------------------------------------------------------- 2876 MOVE | Apply method to reference | Apply method to reference 2877 ===================================================================== 2878 COPY | Apply method to reference | Apply method to target 2879 --------------------------------------------------------------------- 2880 LOCK | Apply method to reference | Apply method to target 2881 --------------------------------------------------------------------- 2882 UNLOCK | Apply method to reference | Apply method to target 2884 PROPFIND, DELETE, MOVE, COPY, LOCK, and UNLOCK can be applied to 2885 collections. In cases where the collection contains references, 2886 behavior for the references in the collection follows the same rules as 2887 the table describes for individual references. So, for example, if a 2888 PROPFIND encounters a redirect reference within a collection, it returns 2889 a 302 status code for that redirect reference in the Multi-Status 2890 response. If the PROPFIND encounters a direct reference, it returns the 2891 properties of the direct reference�s target resource in the Multi-Status 2892 response. 2894 Expires August 26, 1999