WEBDAV Working Group J. Slein INTERNET DRAFT Xerox Corporation June 5, 1998 Expires December 5, 1998 WebDAV Advanced Collections Protocol Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe),munnari.oz.au (Pacific Rim), ftp.ietf.org (US EastCoast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Please send comments to the Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject "subscribe" to . Discussions of the WEBDAV working group are archived at URL: . Abstract The base WebDAV protocol [Goland et al., 1998] provides basic support for collections. It defines a MKCOL method for creating collections and specifies how other HTTP and WebDAV methods interact with collections. It supports only internal members of collections, which it defines as members whose URIs are immediately relative to the URI of the collection. Many applications, however, need more powerful collections. There are two areas in particular where more powerful functionality is often needed: referential members and ordering. This draft specifies extensions to the base WebDAV protocol to support these more powerful collections. 1 Terminology The terminology used here differs from that in the base WebDAV protocol specification [Goland et al., 1998], particularly in its definition of internal member resource. Slein Page 1 INTERNET-DRAFT WebDAV Collection Protocol June 1998 Collection A resource that contains member resources Member Resource A resource contained by a collection Referential Member Resource A member resource that has no content of its own, but rather is a reference to another resource Strong Reference A reference whose referential integrity is guaranteed by the server Weak Reference A reference whose referential integrity is not guaranteed by the server Internal Member Resource A member resource that either has content of its own or is empty, but is not a reference to another resource Target Resource The resource referenced by a referential member of a collection 2 Introduction The simple collections that the base WebDAV specification supports are powerful enough to be widely useful. They provide for the hierarchical organization of resources, with mechanisms for creating and deleting collections, copying and moving them, locking them, adding resources to them and deleting resources from them, and getting listings of their members. Delete, copy, move, list, and lock operations can be applied recursively, so that a client can operate on whole hierarchies with a single request. Many applications, however, need more powerful collections. There are two areas in particular where more powerful functionality is often needed: referential members and ordering. Referential members make it possible for many collections, on the same or different servers, to share the same resource. Because the collections share the resource by referencing it, only one physical copy of the resource need exist, and any changes made in the resource are visible from all the collections that reference it. It is useful for many applications to be able to impose an ordering on a collection. Orderings may be based on property values, but they may be completely independent of any properties on the collection's member resources. Orderings based on properties can be obtained using a search protocol [DASL], but orderings not based on properties need some other mechanism. Slein Page 2 INTERNET-DRAFT WebDAV Collection Protocol June 1998 Since these two areas are independent of each other, servers may elect to comply with the Referential Members section of this specification or with the Ordered Collections section or both. A server MUST advertise its compliance through its response to an OPTIONS request, as specified in [Goland et al., 1998]. New values for the DAV header are defined in Section 8 below to support this requirement. 3 Referential Members 3.1 Overview A referential member of a collection is a resource that has no content of its own, but instead references another resource. The resource it references may be in the same collection or anywhere else. This target resource may be a collection or a simple resource or another referential member of a collection, or any other sort of resource that may be defined in the future. A resource may be referenced by any number of referential members of collections. (Req 3.1.1 - 3.1.3, 3.1.6, 3.1.15) Since a referential member of a collection is a resource, it can have properties just like any other resource. These properties are completely independent of the properties on its target resource (Req 3.1.9). A new DAV:reftarget property has as its value the URI of the target resource (3.1.6). 3.2 Creating Referential Members of a Collection (Req 3.1.7) (Add justification for using the extension mechanisms specified in [Nielsen et al., 1998] "Mandatory Extensions in HTTP".) Clients MUST use the M-PUT method to create a referential member of a collection. (Clients MUST NOT use a plain PUT to create a referential member of a collection. A PUT request with a request-URI of an existing collection will fail.) The request-URI of the M-PUT request identifies the collection to which the new member is to be added. The server recognizes a request to create a referential member, rather than an internal member, by the presence of the Referential-Member header. This header identifies the referential member being added. The Ref-Target header contains the URI of the target resource. An optional Ref-Integrity request header can be used to tell the server not to create the referential member unless it can guarantee referential integrity (Req 3.1.11). An optional Position request header supports ordering by allowing the client to specify where the new referential member is to be placed in the collection's ordering. (This header can also be used with M-PUT to create an internal collection member at a specific position in the ordering.) When a server processes an M-PUT request with the Referential-Member header, it MUST set the DAV:resourcetype Slein Page 3 INTERNET-DRAFT WebDAV Collection Protocol June 1998 property [defined in Goland et al, 1998] of the new resource to be refmember (Req 3.1.12). When a server processes an M-PUT request with the Referential-Member header, it MUST set the DAV:reftarget property to the URI of the target resource (Req 3.1.6). When a server processes an M-PUT request with the Referential-Member header, it MUST set the DAV:refintegrity property (Req 3.1.13). If DAV:refintegrity is T, the server MUST insure that the target resource's DAV:refsource property reflects the new, strong reference to that resource (Req 3.1.14). The server SHOULD ignore any content submitted with a request to create a referential member in a collection. If an M-PUT request is submitted for an existing collection member, the existing member's content and properties will be overwritten. This behavior is analogous to the behavior of a plain HTTP PUT method. If the Position header is absent in this case, the server MUST leave the member at its previous position in the collection ordering. If the Position header is present, the server MUST remove it from its previous position, and then insert it at the requested position. (Req 3.2.4) If the updated referential member changes from weak to strong or from strong to weak, the server MUST update the target's DAV:refsource property to reflect the change. Example: Request: M-PUT /~whitehead/dav/ HTTP/1.1 HOST: www.ics.uci.edu Man: "DAV:Coll-headers" Referential-Member: spec08.ref Ref-Target: http://www.ics.uci.edu/i-d/draft-webdav-protocol-08.txt Ref-Integrity: T Position: After requirements.html Content-Length: 0 Response: HTTP/1.1 200 OK 3.3 Deleting Referential Members of a Collection (Req 3.1.8) DELETE is the appropriate method to use to remove a referential member from a collection. DELETE on a referential member has no affect on its target resource unless the referential member is a strong reference. In this case, the server MUST insure that the DAV:refsource property of its target resource reflects this change. Slein Page 4 INTERNET-DRAFT WebDAV Collection Protocol June 1998 Example: Request: DELETE /~whitehead/dav/spec08.ref HTTP/1.1 HOST: www.ics.uci.edu Response: HTTP/1.1 200 OK The referential member spec08.ref of collection /~whitehead/dav/ has been deleted, but its target resource on www.ietf.org still exists. The DAV:refsource property of http://www.ics.uci.edu/ i-d/draft-webdav-protocol-08.txt has been updated so that it no longer shows a reference from spec08.ref. 3.4 Listing Referential Members of a Collection (Req 3.1.10) Since a referential member of a collection is just a resource in the collection, a listing of members of the collection shows referential members along with internal members. That is, a PROPFIND on a collection resource with Depth = 1 or infinity MUST return a response XML element for each internal member and for each referential member. If Depth = infinity in the PROPFIND request, the server SHOULD NOT follow references into any collections to which they may refer. 3.5 Other Operations on Referential Members of a Collection In general, operations that modify resources, when applied to a referential member of a collection, affect the referential member, not its target resource (Req 3.1.4). There is only one exception to this general rule: For strong references, operations on the referential member may cause changes to the refsource property of its target resource. A LOCK operation on a referential member of a collection locks the referential member, not its target. A LOCK on the collection with Depth = 1 or infinity locks the referential members along with all the other members of the collection, but not the targets of the referential members. A PROPPATCH on a referential member of a collection modifies the properties of the referential member, not the properties of its target resource. A MOVE operation on a referential member of a collection moves the referential member to a different collection, but has no effect on the location of its target. If the referential member was a strong reference at its old location, the server MUST remove its old URI from the list in the target's refsource property. If the client Slein Page 5 INTERNET-DRAFT WebDAV Collection Protocol June 1998 wants the referential member at its new location to be a strong reference, it must use the M-MOVE method with the Ref-Integrity header to perform the move. If the server is able to comply with the request, it MUST add the referential member's new URI to the list in the refsource property of its target. A COPY operation on a referential member copies the referential member, not its target resource, to another collection. If the client wants the referential member in the new location to be a strong reference, it must use the M-COPY method with the Ref-Integrity header to perform the copy. If the server is able to comply with the request, it MUST add the URI of the new copy to the list in the refsource property of its target. A PUT operation (or an M-PUT without a Referential-Member header) creates an internal collection member, not a referential member. If a strong reference is replaced by an internal member as a result of a PUT or M-PUT, the server MUST remove the URI of the referential member from the DAV:refsource property of its target. Similarly, operations that retrieve information, when applied to a referential member of a collection, retrieve information relating to the referential member, not its target resource. A PROPFIND on a referential member returns the properties of the referential member, not the properties of its target resource. A GET on a referential member of a collection returns its own content, which is the URI of its target resource, not the content of its target resource. 3.6 Operations on Targets of Referential Collection Members Operations on targets of referential collection members have no effect on the referential member unless the referential member is a strong reference. When the target of a strong reference is MOVEd, the server MUST update the DAV:reftarget property of the referential member to reflect its new location. When a client attempts to delete a target of a strong reference, the server MUST maintain referential integrity, either by deleting the strong reference at the same time, or by failing the request to delete the target. (Provide an error code and response type to tell the client the value of the refsource property) 4 Ordered Collections A new optional property DAV:ordering is defined to support ordered collections. (Req 3.2.1) It is a property only of collections, and is not required to be present on a collection. That is, even compliant servers may have a mix of ordered and unordered collections. The client decides whether a particular collection is ordered or not. (Req 3.2.2) The value DAV:ordering is an ordering-type (Req 3.2.3) followed by a list of the URIs of the collection's members. Each collection member, whether internal or referential, must be in the list exactly once (Req 3.2.4, 3.2.8), Slein Page 6 INTERNET-DRAFT WebDAV Collection Protocol June 1998 and the list must not include any resource that is not a member of the collection (Req 3.2.5). Only one ordering can be attached to any collection (Req 3.2.5a). Multiple orderings of the same resources can be achieved by creating multiple collections referencing those resources, and attaching a different ordering to each collection. The ordering-type, represented by the new DAV:orderingtype XML element,is an href identifying the semantics of the ordering. The href SHOULD point to a resource that contains a definition of the semantics of the ordering, allowing a human user or software package to insert new collection members into the ordering intelligently. (Req 3.2.3) A client may order the members of a collection with the DAV:ordering property of the collection. The client may use PROPFIND to discover the current ordering of the collection, and PROPPATCH on the ordering property to modify the ordering. It is also possible to insert an internal or referential collection member into the ordering at the time the member is is added to the collection, by using the Position header with the M-PUT, M-COPY, or M-MOVE request. (Req 3.2.9) The DAV:ordering property is live only to the extent that the server MUST remove an href from the ordering when a member is removed from the collection, and the server MUST add the href to the ordering whenever a member is added to the collection. It MUST insert the new member at the location specified in the Position header, if present in the M-PUT request; otherwise, it MUST append the new member to the end of the ordering. If a PUT or M-Put causes an existing resource to be replaced, and if the Position header is absent, the server MUST leave the member at its previous position in the collection ordering. If the Position header is present, the server MUST remove the member from its previous position, and then insert it at the requested position. Whenever the server receives a PROPPATCH request on the DAV:ordering property, it MUST verify that each member of the collection appears in the ordering exactly once. (Reqs 3.2.4, 3.2.5) When responding to a PROPFIND on a collection, the server MUST order the response elements according to the DAV:ordering property on the collection. (Req 3.2.6) 5 New Headers 5.1 Referential-Member Request Header Referential-Member = "Referential-Member" ":" relative URI The Referential-Member request header is used with the M-PUT method to identify the new referential member to be added to the collection. The URI is relative to the collection identified by the request-URI. It is a required header in requests to add a referential member to a collection. Slein Page 7 INTERNET-DRAFT WebDAV Collection Protocol June 1998 5.2 Ref-Target Request Header Ref-Target = "Ref-Target" ":" URI The Ref-Target request header is used with the M-PUT method to identify the target resource of the new referential member being added to a collection. It is a required header in requests to add a referential member to a collection. 5.2 Ref-Integrity Request Header Ref-Integrity = "Ref-Integrity" ":" ("T" | "F") The Ref-Integrity header specifies whether the server should enforce referential integrity for a referential member of a collection being created with M-PUT. If the value of the header is "T", the server MUST fail the request unless it can guarantee referential integrity. If the header is not used, the server MUST treat the request as if it has a Ref-Integrity header set to "F". 5.3 Position Request Header Position = "Position" ":" ("First" | "Last" | ("At" index) | (("Before" | "After") URI)) index = integer The Position header may be used with M-PUT to tell the server where in the collection ordering to position the collection member being added. It may be used for both internal and referential members. If the Position request header is not used, then: If the request is replacing an existing resource, the server MUST preserve the present ordering. If the request is adding a new member to the collection, the server MUST append the new member to the end of the list in the DAV:ordering property (if the collection is ordered). 6 New Properties 6.1 reftarget Property Name: reftarget Namespace: DAV: Purpose: A property of referential collection members that provides an efficient way for clients to discover the URI of the target resource. Value: URI of the target resource. 6.2 refsource Property Slein Page 8 INTERNET-DRAFT WebDAV Collection Protocol June 1998 Name: refsource Namespace: DAV: Purpose: A property of targets of strong referential collection members that provides a list of all strong referential collection members that reference the resource. Aids the server in maintaining referential integrity, and allows clients to discover which strong referential members reference the target resource. Value: List of URIs of strong referential collection members that reference the resource. 6.3 refintegrity Property Name: refintegrity Namespace: DAV: Purpose: A property of referential collection members that indicates whether the server guarantees referential integrity for that reference. Value: "T" for strong references, "F" for weak references. 6.4 ordering Property Name: ordering Namespace: DAV: Purpose: A property of a collection, specifying the order of the members of the collection. Value: A typed list of URIs of the members of the collection. Each member of the collection, whether internal or referential, must be in the list exactly once. 7 New XML Elements 7.1 orderingtype XML Element Name: orderingtype Namespace: DAV: Purpose: Uniquely identifies the semantics of the ordering being used. SHOULD also provide an explanation of the semantics in human and / or machine-readable form. At a minimum, this allows human users who add members to the collection to understand where to position them in the ordering. Value: URI that uniquely identifies the semantics of the ordering and that SHOULD point to an definition of the ordering semantics. Slein Page 9 INTERNET-DRAFT WebDAV Collection Protocol June 1998 7.2 refmember XML Element Name: refmember Namespace: DAV: Purpose: A new value of the DAV:resourcetype property that identifies its resource as a referential member of a collection. The DAV:resourcetype property of a referential member of a collection MUST have this value. Value: EMPTY 8 Compliance Section 14 of [Goland et al, 1998] defined a DAV header for use when responding to OPTIONS requests. This header provides a way for clients to discover which parts of WebDAV a resource supports. The WebDAV specifications define numbered compliance classes corresponding to collections of related functions that resources may support. When the server receives an OPTIONS request, it lists the classes that the request-URI supports in the DAV response header. Since this specification defines two independent sets of functionality, it defines two new compliance classes. A WebDAV server may support neither, one or the other, or both for any resource. 8.1 Class 3 This new compliance class indicates compliance with Section 3 "Referential Members" of this specification. Servers that comply with Section 3 MUST list this class in the DAV response header when they respond to an OPTIONS request. 8.2 Class 4 This new compliance class indicates compliance with Section 4 "Ordered Collections" of this specification. Servers that comply with Section 4 MUST list this class in the DAV response header when they respond to an OPTIONS request. 9 Dependencies on Other Specifications [Nielsen et al., 1998] "Mandatory Extensions in HTTP." 10 Security Considerations 11 Internationalization Considerations 12 IANA Considerations 13 Copyright Slein Page 10 INTERNET-DRAFT WebDAV Collection Protocol June 1998 14 Intellectual Property 15 Acknowledgements 16 References [Goland et al., 1998] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. Jensen, "Extensions for Distributed Authoring on the World Wide Web - WebDAV." Draft-ietf-webdav- protocol-08. Internet Draft, work in progress. Microsoft, U.C. Irvine, Netscape, Novell. April, 1998. [Slein, 1998] J. Slein, "Requirements for Advanced Collection Functionality in WebDAV." Draft-ietf-webdav-collection-reqts-01. Internet Draft, work in progress. Xerox, 1998. [Nielsen et al., 1998] H. F. Nielsen, P. Leach, S. Lawrence, "Mandatory Extensions in HTTP." Draft-ietf-http-ext-mandatory-00. Internet Draft, work in progress. W3C, Microsoft, Agranat, 1998. 17 Authors' Addresses J. Slein Xerox Corporation 800 Phillips Road, 105-50C Webster, NY 14580 Email: slein@wrc.xerox.com Expires December 5, 1998 Slein Page 11