idnits 2.17.1 draft-ietf-webdav-collection-protocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-28) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 10 longer pages, the longest (page 1) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. (A line matching the expected section header was found, but with an unexpected indentation: ' 3.1 Overview' ) ** The document seems to lack an Authors' Addresses Section. ** There are 89 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** There are 44 instances of lines with control characters in the document. ** The abstract seems to contain references ([DASL]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 116: '... A server MUST advertise its co...' RFC 2119 keyword, line 145: '... Clients MUST use the M-PUT met...' RFC 2119 keyword, line 146: '...ction. (Clients MUST NOT use a plain ...' RFC 2119 keyword, line 167: '...ember header, it MUST set the DAV:reso...' RFC 2119 keyword, line 172: '...ember header, it MUST set the DAV:reft...' (33 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 5, 1998) is 9245 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 section? 'DASL' on line 110 looks like a reference -- Missing reference section? 'Slein' on line 561 looks like a reference -- Missing reference section? '1998' on line 561 looks like a reference Summary: 12 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 WEBDAV Working Group J. Slein 2 INTERNET DRAFT Xerox Corporation 3 June 5, 1998 4 Expires December 5, 1998 6 WebDAV Advanced Collections Protocol 8 Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its 12 areas, and its working groups. Note that other groups may also 13 distribute working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six 16 months and may be updated, replaced, or made obsolete by other 17 documents at any time. It is inappropriate to use Internet-Drafts 18 as reference material or to cite them other than as "work in 19 progress". 21 To view the entire list of current Internet-Drafts, please check 22 the "1id-abstracts.txt" listing contained in the Internet-Drafts 23 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 24 (Northern Europe), ftp.nis.garr.it (Southern Europe),munnari.oz.au 25 (Pacific Rim), ftp.ietf.org (US EastCoast), or ftp.isi.edu (US West 26 Coast). 28 Distribution of this document is unlimited. Please send comments 29 to the Distributed Authoring and Versioning (WebDAV) working group 30 at , which may be joined by sending a 31 message with subject "subscribe" to . 34 Discussions of the WEBDAV working group are archived at URL: 35 . 37 Abstract 39 The base WebDAV protocol [Goland et al., 1998] provides basic 40 support for collections. It defines a MKCOL method for creating 41 collections and specifies how other HTTP and WebDAV methods 42 interact with collections. It supports only internal members of 43 collections, which it defines as members whose URIs are 44 immediately relative to the URI of the collection. 46 Many applications, however, need more powerful collections. There 47 are two areas in particular where more powerful functionality is 48 often needed: referential members and ordering. 50 This draft specifies extensions to the base WebDAV protocol to 51 support these more powerful collections. 53 1 Terminology 55 The terminology used here differs from that in the base WebDAV 56 protocol specification [Goland et al., 1998], particularly in its 57 definition of internal member resource. 59 Collection 60 A resource that contains member resources 62 Member Resource 63 A resource contained by a collection 65 Referential Member Resource 66 A member resource that has no content of its own, but rather is 67 a reference to another resource 69 Strong Reference 70 A reference whose referential integrity is guaranteed by the 71 server 73 Weak Reference 74 A reference whose referential integrity is not guaranteed by the 75 server 77 Internal Member Resource 78 A member resource that either has content of its own or is 79 empty, but is not a reference to another resource 81 Target Resource 82 The resource referenced by a referential member of a collection 84 2 Introduction 86 The simple collections that the base WebDAV specification supports 87 are powerful enough to be widely useful. They provide for the 88 hierarchical organization of resources, with mechanisms for 89 creating and deleting collections, copying and moving them, 90 locking them, adding resources to them and deleting resources from 91 them, and getting listings of their members. Delete, copy, move, 92 list, and lock operations can be applied recursively, so that a 93 client can operate on whole hierarchies with a single request. 95 Many applications, however, need more powerful collections. There 96 are two areas in particular where more powerful functionality is 97 often needed: referential members and ordering. 99 Referential members make it possible for many collections, on the 100 same or different servers, to share the same resource. Because 101 the collections share the resource by referencing it, only one 102 physical copy of the resource need exist, and any changes made in 103 the resource are visible from all the collections that reference 104 it. 106 It is useful for many applications to be able to impose an 107 ordering on a collection. Orderings may be based on property 108 values, but they may be completely independent of any properties 109 on the collection's member resources. Orderings based on 110 properties can be obtained using a search protocol [DASL], but 111 orderings not based on properties need some other mechanism. 113 Since these two areas are independent of each other, servers may 114 elect to comply with the Referential Members section of this 115 specification or with the Ordered Collections section or both. 116 A server MUST advertise its compliance through its response to 117 an OPTIONS request, as specified in [Goland et al., 1998]. New 118 values for the DAV header are defined in Section 8 below to 119 support this requirement. 121 3 Referential Members 123 3.1 Overview 125 A referential member of a collection is a resource that has no 126 content of its own, but instead references another resource. The 127 resource it references may be in the same collection or anywhere 128 else. This target resource may be a collection or a simple 129 resource or another referential member of a collection, or any 130 other sort of resource that may be defined in the future. A 131 resource may be referenced by any number of referential members of 132 collections. (Req 3.1.1 - 3.1.3, 3.1.6, 3.1.15) 134 Since a referential member of a collection is a resource, it can 135 have properties just like any other resource. These properties are 136 completely independent of the properties on its target resource 137 (Req 3.1.9). A new DAV:reftarget property has as its value the 138 URI of the target resource (3.1.6). 140 3.2 Creating Referential Members of a Collection (Req 3.1.7) 142 (Add justification for using the extension mechanisms specified in 143 [Nielsen et al., 1998] "Mandatory Extensions in HTTP".) 145 Clients MUST use the M-PUT method to create a referential member 146 of a collection. (Clients MUST NOT use a plain PUT to create a 147 referential member of a collection. A PUT request with a 148 request-URI of an existing collection will fail.) The 149 request-URI of the M-PUT request identifies the collection to which 150 the new member is to be added. The server recognizes a request to 151 create a referential member, rather than an internal member, by the 152 presence of the Referential-Member header. This header identifies 153 the referential member being added. The Ref-Target header contains 154 the URI of the target resource. 156 An optional Ref-Integrity request header can be used to tell the 157 server not to create the referential member unless it can guarantee 158 referential integrity (Req 3.1.11). 160 An optional Position request header supports ordering by allowing 161 the client to specify where the new referential member is to be 162 placed in the collection's ordering. (This header can also be used 163 with M-PUT to create an internal collection member at a specific 164 position in the ordering.) 166 When a server processes an M-PUT request with the 167 Referential-Member header, it MUST set the DAV:resourcetype 168 property [defined in Goland et al, 1998] of the new resource to be 169 refmember (Req 3.1.12). 171 When a server processes an M-PUT request with the 172 Referential-Member header, it MUST set the DAV:reftarget property 173 to the URI of the target resource (Req 3.1.6). 175 When a server processes an M-PUT request with the 176 Referential-Member header, it MUST set the DAV:refintegrity 177 property (Req 3.1.13). 179 If DAV:refintegrity is T, the server MUST insure that the target 180 resource's DAV:refsource property reflects the new, strong 181 reference to that resource (Req 3.1.14). 183 The server SHOULD ignore any content submitted with a request to 184 create a referential member in a collection. 186 If an M-PUT request is submitted for an existing collection 187 member, the existing member's content and properties will be 188 overwritten. This behavior is analogous to the behavior of a plain 189 HTTP PUT method. If the Position header is absent in this case, 190 the server MUST leave the member at its previous position in the 191 collection ordering. If the Position header is present, the server 192 MUST remove it from its previous position, and then insert it at 193 the requested position. (Req 3.2.4) If the updated referential 194 member changes from weak to strong or from strong to weak, the 195 server MUST update the target's DAV:refsource property to reflect 196 the change. 198 Example: 200 Request: 202 M-PUT /~whitehead/dav/ HTTP/1.1 203 HOST: www.ics.uci.edu 204 Man: "DAV:Coll-headers" 205 Referential-Member: spec08.ref 206 Ref-Target: http://www.ics.uci.edu/i-d/draft-webdav-protocol-08.txt 207 Ref-Integrity: T 208 Position: After requirements.html 209 Content-Length: 0 211 Response: 213 HTTP/1.1 200 OK 215 3.3 Deleting Referential Members of a Collection (Req 3.1.8) 217 DELETE is the appropriate method to use to remove a referential 218 member from a collection. DELETE on a referential member has no 219 affect on its target resource unless the referential member is a 220 strong reference. In this case, the server MUST insure that the 221 DAV:refsource property of its target resource reflects this change. 223 Example: 225 Request: 227 DELETE /~whitehead/dav/spec08.ref HTTP/1.1 228 HOST: www.ics.uci.edu 230 Response: 232 HTTP/1.1 200 OK 234 The referential member spec08.ref of collection /~whitehead/dav/ 235 has been deleted, but its target resource on www.ietf.org still 236 exists. The DAV:refsource property of http://www.ics.uci.edu/ 237 i-d/draft-webdav-protocol-08.txt has been updated 238 so that it no longer shows a reference from spec08.ref. 240 3.4 Listing Referential Members of a Collection (Req 3.1.10) 242 Since a referential member of a collection is just a resource in 243 the collection, a listing of members of the collection shows 244 referential members along with internal members. That is, a 245 PROPFIND on a collection resource with Depth = 1 or infinity MUST 246 return a response XML element for each internal member and for each 247 referential member. 249 If Depth = infinity in the PROPFIND request, the server SHOULD NOT 250 follow references into any collections to which they may refer. 252 3.5 Other Operations on Referential Members of a Collection 254 In general, operations that modify resources, when applied to a 255 referential member of a collection, affect the referential member, 256 not its target resource (Req 3.1.4). There is only one exception 257 to this general rule: For strong references, operations on the 258 referential member may cause changes to the refsource property 259 of its target resource. 261 A LOCK operation on a referential member of a collection locks the 262 referential member, not its target. A LOCK on the collection with 263 Depth = 1 or infinity locks the referential members along with all 264 the other members of the collection, but not the targets of the 265 referential members. 267 A PROPPATCH on a referential member of a collection modifies the 268 properties of the referential member, not the properties of its 269 target resource. 271 A MOVE operation on a referential member of a collection moves the 272 referential member to a different collection, but has no effect on 273 the location of its target. If the referential member was a strong 274 reference at its old location, the server MUST remove its old URI 275 from the list in the target's refsource property. If the client 276 wants the referential member at its new location to be a strong 277 reference, it must use the M-MOVE method with the Ref-Integrity 278 header to perform the move. If the server is able to comply with 279 the request, it MUST add the referential member's new URI to the 280 list in the refsource property of its target. 282 A COPY operation on a referential member copies the referential 283 member, not its target resource, to another collection. If the 284 client wants the referential member in the new location to be a 285 strong reference, it must use the M-COPY method with the 286 Ref-Integrity header to perform the copy. If the server is able 287 to comply with the request, it MUST add the URI of the new copy to 288 the list in the refsource property of its target. 290 A PUT operation (or an M-PUT without a Referential-Member header) 291 creates an internal collection member, not a referential member. 292 If a strong reference is replaced by an internal member as a result 293 of a PUT or M-PUT, the server MUST remove the URI of the 294 referential member from the DAV:refsource property of its target. 296 Similarly, operations that retrieve information, when applied to a 297 referential member of a collection, retrieve information relating 298 to the referential member, not its target resource. A PROPFIND on 299 a referential member returns the properties of the referential 300 member, not the properties of its target resource. A GET on a 301 referential member of a collection returns its own content, which 302 is the URI of its target resource, not the content of its target 303 resource. 305 3.6 Operations on Targets of Referential Collection Members 307 Operations on targets of referential collection members have no 308 effect on the referential member unless the referential member is 309 a strong reference. When the target of a strong reference is 310 MOVEd, the server MUST update the DAV:reftarget property of the 311 referential member to reflect its new location. When a client 312 attempts to delete a target of a strong reference, the server 313 MUST maintain referential integrity, either by deleting the 314 strong reference at the same time, or by failing the request to 315 delete the target. 317 (Provide an error code and response type to tell the client the value of 318 the refsource property) 320 4 Ordered Collections 322 A new optional property DAV:ordering is defined to support ordered 323 collections. (Req 3.2.1) It is a property only of collections, 324 and is not required to be present on a collection. That is, even 325 compliant servers may have a mix of ordered and unordered 326 collections. The client decides whether a particular collection 327 is ordered or not. (Req 3.2.2) The value DAV:ordering is an 328 ordering-type (Req 3.2.3) followed by a list of the URIs of the 329 collection's members. Each collection member, whether internal or 330 referential, must be in the list exactly once (Req 3.2.4, 3.2.8), 331 and the list must not include any resource that is not a member of 332 the collection (Req 3.2.5). Only one ordering can be attached to 333 any collection (Req 3.2.5a). Multiple orderings of the same 334 resources can be achieved by creating multiple collections 335 referencing those resources, and attaching a different ordering to 336 each collection. 338 The ordering-type, represented by the new DAV:orderingtype XML 339 element,is an href identifying the semantics of the ordering. The 340 href SHOULD point to a resource that contains a definition of the 341 semantics of the ordering, allowing a human user or software 342 package to insert new collection members into the ordering 343 intelligently. (Req 3.2.3) 345 A client may order the members of a collection with the 346 DAV:ordering property of the collection. The client may use 347 PROPFIND to discover the current ordering of the collection, and 348 PROPPATCH on the ordering property to modify the ordering. It is 349 also possible to insert an internal or referential collection 350 member into the ordering at the time the member is is added to the 351 collection, by using the Position header with the M-PUT, M-COPY, 352 or M-MOVE request. (Req 3.2.9) 354 The DAV:ordering property is live only to the extent that the 355 server MUST remove an href from the ordering when a member is 356 removed from the collection, and the server MUST add the href to 357 the ordering whenever a member is added to the collection. It MUST 358 insert the new member at the location specified in the Position 359 header, if present in the M-PUT request; otherwise, it MUST append 360 the new member to the end of the ordering. If a PUT or M-Put causes 361 an existing resource to be replaced, and if the Position header 362 is absent, the server MUST leave the member at its previous 363 position in the collection ordering. If the Position header is 364 present, the server MUST remove the member from its previous 365 position, and then insert it at the requested position. Whenever 366 the server receives a PROPPATCH request on the DAV:ordering 367 property, it MUST verify that each member of the collection appears 368 in the ordering exactly once. (Reqs 3.2.4, 3.2.5) 370 When responding to a PROPFIND on a collection, the server MUST 371 order the response elements according to the DAV:ordering property 372 on the collection. (Req 3.2.6) 374 5 New Headers 376 5.1 Referential-Member Request Header 378 Referential-Member = "Referential-Member" ":" relative URI 380 The Referential-Member request header is used with the M-PUT method 381 to identify the new referential member to be added to the 382 collection. The URI is relative to the collection identified by 383 the request-URI. It is a required header in requests to add a 384 referential member to a collection. 386 5.2 Ref-Target Request Header 388 Ref-Target = "Ref-Target" ":" URI 390 The Ref-Target request header is used with the M-PUT method to 391 identify the target resource of the new referential member being 392 added to a collection. It is a required header in requests to add 393 a referential member to a collection. 395 5.2 Ref-Integrity Request Header 397 Ref-Integrity = "Ref-Integrity" ":" ("T" | "F") 399 The Ref-Integrity header specifies whether the server should 400 enforce referential integrity for a referential member of a 401 collection being created with M-PUT. If the value of the header is 402 "T", the server MUST fail the request unless it can guarantee 403 referential integrity. If the header is not used, the server MUST 404 treat the request as if it has a Ref-Integrity header set to "F". 406 5.3 Position Request Header 408 Position = "Position" ":" ("First" | "Last" | ("At" index) | 409 (("Before" | "After") URI)) 410 index = integer 412 The Position header may be used with M-PUT to tell the server 413 where in the collection ordering to position the collection member 414 being added. It may be used for both internal and referential 415 members. 417 If the Position request header is not used, then: 419 If the request is replacing an existing resource, the server 420 MUST preserve the present ordering. 422 If the request is adding a new member to the collection, the 423 server MUST append the new member to the end of the list in the 424 DAV:ordering property (if the collection is ordered). 426 6 New Properties 428 6.1 reftarget Property 430 Name: reftarget 431 Namespace: DAV: 432 Purpose: A property of referential collection members that 433 provides an efficient way for clients to discover 434 the URI of the target resource. 435 Value: URI of the target resource. 437 439 6.2 refsource Property 440 Name: refsource 441 Namespace: DAV: 442 Purpose: A property of targets of strong referential 443 collection members that provides a list of all 444 strong referential collection members that 445 reference the resource. Aids the server in 446 maintaining referential integrity, and allows 447 clients to discover which strong referential 448 members reference the target resource. 449 Value: List of URIs of strong referential collection 450 members that reference the resource. 452 454 6.3 refintegrity Property 456 Name: refintegrity 457 Namespace: DAV: 458 Purpose: A property of referential collection members that 459 indicates whether the server guarantees referential 460 integrity for that reference. 461 Value: "T" for strong references, "F" for weak references. 463 465 6.4 ordering Property 467 Name: ordering 468 Namespace: DAV: 469 Purpose: A property of a collection, specifying the order 470 of the members of the collection. 471 Value: A typed list of URIs of the members of the 472 collection. Each member of the collection, whether 473 internal or referential, must be in the list 474 exactly once. 476 478 7 New XML Elements 480 7.1 orderingtype XML Element 482 Name: orderingtype 483 Namespace: DAV: 484 Purpose: Uniquely identifies the semantics of the ordering 485 being used. SHOULD also provide an explanation of 486 the semantics in human and / or machine-readable 487 form. At a minimum, this allows human users who 488 add members to the collection to understand where 489 to position them in the ordering. 490 Value: URI that uniquely identifies the semantics of the 491 ordering and that SHOULD point to an definition of 492 the ordering semantics. 494 495 7.2 refmember XML Element 497 Name: refmember 498 Namespace: DAV: 499 Purpose: A new value of the DAV:resourcetype property that 500 identifies its resource as a referential member of 501 a collection. The DAV:resourcetype property of a 502 referential member of a collection MUST have this 503 value. 504 Value: EMPTY 506 508 8 Compliance 510 Section 14 of [Goland et al, 1998] defined a DAV header for use 511 when responding to OPTIONS requests. This header provides a way 512 for clients to discover which parts of WebDAV a resource supports. 513 The WebDAV specifications define numbered compliance classes 514 corresponding to collections of related functions that resources 515 may support. When the server receives an OPTIONS request, it lists 516 the classes that the request-URI supports in the DAV response 517 header. 519 Since this specification defines two independent sets of 520 functionality, it defines two new compliance classes. A WebDAV 521 server may support neither, one or the other, or both for any 522 resource. 524 8.1 Class 3 526 This new compliance class indicates compliance with Section 3 527 "Referential Members" of this specification. Servers that comply 528 with Section 3 MUST list this class in the DAV response header 529 when they respond to an OPTIONS request. 531 8.2 Class 4 533 This new compliance class indicates compliance with Section 4 534 "Ordered Collections" of this specification. Servers that comply 535 with Section 4 MUST list this class in the DAV response header 536 when they respond to an OPTIONS request. 538 9 Dependencies on Other Specifications 540 [Nielsen et al., 1998] "Mandatory Extensions in HTTP." 542 10 Security Considerations 544 11 Internationalization Considerations 546 12 IANA Considerations 548 13 Copyright 549 14 Intellectual Property 551 15 Acknowledgements 553 16 References 555 [Goland et al., 1998] Y. Y. Goland, E. J. Whitehead, Jr., A. 556 Faizi, S. R. Carter, D. Jensen, "Extensions for Distributed 557 Authoring on the World Wide Web - WebDAV." Draft-ietf-webdav- 558 protocol-08. Internet Draft, work in progress. Microsoft, 559 U.C. Irvine, Netscape, Novell. April, 1998. 561 [Slein, 1998] J. Slein, "Requirements for Advanced Collection 562 Functionality in WebDAV." Draft-ietf-webdav-collection-reqts-01. 563 Internet Draft, work in progress. Xerox, 1998. 565 [Nielsen et al., 1998] H. F. Nielsen, P. Leach, S. Lawrence, 566 "Mandatory Extensions in HTTP." Draft-ietf-http-ext-mandatory-00. 567 Internet Draft, work in progress. W3C, Microsoft, Agranat, 1998. 569 17 Authors' Addresses 571 J. Slein 572 Xerox Corporation 573 800 Phillips Road, 105-50C 574 Webster, NY 14580 575 Email: slein@wrc.xerox.com 577 Expires December 5, 1998