WEBDAV Working Group J. Slein, Xerox Corporation INTERNET DRAFT J. Davis, Xerox Corporation February 26, 1999 Expires August 26, 1999 Requirements for Advanced Collection Functionality in WebDAV Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 obsoleted 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 list Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. Distribution of this document is unlimited. Please send comments to the Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject "subscribe" to . Discussions of the WEBDAV working group are archived at URL: . Abstract The base WebDAV protocol [WebDAV] provides basic support for collections. It defines a MKCOL method for creating collections and specifies how other HTTP and WebDAV methods interact with collections. It supports internal members of collections, which it defines as members whose URIs are immediately relative to the URI of the collection. This draft sets out requirements for more advanced, optional collection functionality. It extends the base functionality in two general directions: support for referential resources, and support for ordered collections. A separate WebDAV specification is expected to define protocol elements providing the functionality described here. 1 Terminology The terminology used here follows and extends that in the base WebDAV protocol specification [WebDAV]. Collection A resource that contains a set of URIs, termed member URIs, which identify member resources Slein & Davis Page 1 INTERNET-DRAFT WebDAV Collection Requirements February 1999 Member URI A URI which is a member of the set of URIs contained by a collection Referential Resource (or Reference) A resource that has no body of its own (though it does have properties), but rather is a reference to another resource Ordinary Resource A resource that is not a reference to another resource Target Resource The resource referenced by a referential resource Direct Reference A reference that is resolved by the server without any client action, giving the client the illusion that it is operating directly on the target resource Redirect Reference A reference that requires client action before it can be resolved, so that the client is aware that a reference is mediating between it and the target resource Strong Reference A reference whose referential integrity is enforced by the server Weak Reference A reference whose referential integrity is not enforced by the server Referential Integrity The integrity of a reference is preserved as long as it points to the same resource it pointed to when it was created. Its integrity may be destroyed if the target resource is moved without updating the reference to reflect its new location, or if the target resource is deleted. 2 Introduction and Rationale The simple collections that the base WebDAV specification supports are powerful enough to be widely useful. They provide for the hierarchical organization of resources, with mechanisms for creating and deleting collections, copying and moving them, locking them, adding resources to them and deleting resources from them, and getting listings of their members. Delete, copy, move, list, and lock operations can be applied recursively, so that a client can operate on whole hierarchies with a single request. Many applications, however, need more powerful collections. There are two areas in particular where more powerful functionality is often needed: referential resources and ordering. This draft details the additional functionality that is needed in these two Slein & Davis Page 2 INTERNET-DRAFT WebDAV Collection Requirements February 1999 areas. 2.1 Referential Resources Referential resources make it possible for many collections, on the same or different servers, to share the same resource. Because the collections share the resource by referencing it, only one physical copy of the resource need exist, and any changes made in the resource are visible from all the collections that reference it. So, for example, the mathematics department at one university can create a collection of information on fractals that contains the URIs of some local resources, but also references resources at several other universities. In another scenario, a manufacturing company develops and maintains its product maintenance manuals on the Web. There is a separate collection for each product manual. Each manual is divided into sections, one section for every product component. Since many of the company’s products contain some of the same components, many of the product maintenance manuals have sections in common. Each manual may have some unique sections, whose URIs are internal members of its collection. But for product components that are common to multiple products, the manual's collection references a resource in a shared library. Strong references and weak references are both useful in different contexts. Some applications cannot tolerate broken links. A software development application, for example, must be able to rely on the integrity of references to component modules. Such applications must be able to request strong references. Other applications may want to reference target resources on multiple servers, where referential integrity cannot be enforced, and may be less concerned about possible broken references. Both strong references and weak references should eventually be supported by WebDAV. Similarly, both redirect and direct references may be useful. Redirect references are simple for servers to implement, but require client action before they can be resolved. Direct references are more difficult for servers to implement, particularly if target resources may be on a different server, but are simpler for clients to use. A client need not be aware that a direct reference is mediating between it and the resource it is accessing. 2.2 Ordered Collections For many applications, it is useful to be able to impose an ordering on a collection. In the product manual application above, the sections of each manual may be ordered so that they can be printed together as a book. A configuration management application might use a collection to represent a version series, in which case the "derives from" relationship might be represented Slein & Davis Page 3 INTERNET-DRAFT WebDAV Collection Requirements February 1999 as an ordering on the collection. A collection ordering may sometimes be based on property values. An example of such an ordering is one that is alphabetical by author’s last name, or one from most recent to oldest last- modified-date. An ordering need not be based on property values, however. A professor may order a collection of course readings in the sequence that makes sense to coordinate them with her lectures, where there is no property on the member resources that could be used to create this ordering. This set of requirements is primarily concerned with orderings that are not based on property values. Another useful distinction is between server-maintained and client-maintained orderings. In server-maintained orderings, the server enforces the semantics of the ordering by placing each collection member at the appropriate position in the ordering; clients cannot alter the ordering. In client-maintained orderings, the client places each collection member in the ordering based on its understanding of the semantics of the ordering; the server does nothing to validate the client's positioning of the member in the ordering. This set of requirements is concerned only with client-maintained orderings. WebDAV already provides tools that could be used for creating and maintaining ordered collections. For example, using only the base WebDAV specification, an application could create a WebDAV property called "Order" on a collection resource. The value of this property might be a list of the collection's member URIs. What the base WebDAV specification does not do is standardize a single way to represent orderings for collections. Different applications and services should be able to operate on the same collection without private agreements about how to manage and examine its order. To make this possible, there needs to be a standard way to manipulate and retrieve the order of a collection, and a standard representation of the ordering. In any situation where collaborative management of a collection takes place, and different authoring tools or WebDAV servers might be used by the collaborators, standardization is important. It is also important where a different tool may be used to view the collection from the one that was used to create it. So for example, two users from different organizations, using different authoring tools, are working together to create a collection. One of the tools uses a property on the collection called "Order" to store an ordering of the collection. The other tool uses a property called "SequenceNumber" on the resources identified by the collection's member URIs. If each user adds some members to the collection, there will be no reliable ordering. 3 Requirements Slein & Davis Page 4 INTERNET-DRAFT WebDAV Collection Requirements February 1999 3.1 Referential Resources Requirements 3.1.1 - 3.1.9 apply to referential resources in general. Requirements 3.1.10 - 3.1.13 apply to referential resources only in the context of collections. Requirements 3.1.14 - 3.1.15 apply only to redirect references. Requirements 3.1.16 - 3.1.17 apply only to direct references. Requirements 3.1.18 - 3.1.22 relate to strong references and enforcement of referential integrity. 3.1.1 A single target resource may be referenced by multiple referential resources. This is the primary benefit that referential resources bring. They allow resources to be shared by multiple collections, which may reside on the same server as the shared resource or on other servers. 3.1.2 It is possible to create a referential resource. 3.1.3 It is possible to delete a referential resource. It is important to note that this is a different operation from deleting the reference’s target resource. It must be possible to delete a reference without deleting its target. 3.1.4 It is possible to set and retrieve the properties of a reference, distinct from those of its target. There are properties like "who created this reference" and "when was this reference created", "what type of reference is this", and "is referential integrity maintained for this reference" that clearly belong to the reference, and not to its target resource, which may be referenced by many different referential resources. Clients must be able to set properties on a reference, and retrieve the properties of a reference. 3.1.5 More generally, there is a way to cause any operation to be applied to the reference itself, rather than to its target. Although the more common case is for the client to use a reference to operate on its target resource, there will be cases where clients need to operate on the reference itself. They may need to view the HTTP headers of the referential resource, retrieve its capabilities, lock it, etc. 3.1.6 Operations on a target resource do not affect references to it except as needed to enforce referential integrity. We do not expect operations on a target to affect references to it. Locking a target does not cause the references to it to be locked. Modifying the properties of a target does not cause changes in the properties of references to it. Etc. This requirement is qualified to allow for strong references. For Slein & Davis Page 5 INTERNET-DRAFT WebDAV Collection Requirements February 1999 strong references, some operations on targets must cause changes in the references to them. For example, if the target of a strong reference is moved, the reference must change to reflect the new location of the target. 3.1.7 For any target resource, it is possible to request a list of the references to it. There are many scenarios that use this capability. On a server that does not provide strong references, a client may, as a good citizen, want to check for references before deleting a resource. Some servers enforce referential integrity by blocking deletes for resources that have references to them. In this case, a client may need to discover the references in order to delete them before deleting their target. 3.1.8 A plain HTTP 1.1 browser or a non-referencing WebDAV client is able to use a referential resource to access its target. This minimal level of compatibility with older clients is needed to make deployment of WebDAV collection functionality feasible. References are a new type of resource whose main purpose is to allow ordinary resources to be shared by multiple collections. Although referencing clients may be needed to create and manipulate these new resources, older clients should be able to read and make use of the collections built using references. 3.1.9 There is no requirement that references be acyclic. From a practical standpoint, servers generally cannot control what happens on other servers. If a reference R on one server points to a target T on another server, R's server cannot prevent T from being changed to point back to R. In addition, there may be applications where cyclic references are desirable. 3.1.10 A listing of the members of a collection shows both its ordinary members and its referential members. A listing of collection members with Depth = 1 or Depth = infinity shows all URIs in the collection, whether they identify ordinary resources or referential resources. 3.1.11 Multiple referential resources with the same target may have URIs in the same collection. It is often useful to allow the same resource to be referenced in a collection multiple times. Typically, these are cases where the collection is ordered. Consider a case where a collection represents a book, with one member URI for each page in the book. A particular graphic needs to appear in several places in the book, and so its URI needs to appear in the collection several times. 3.1.12 A single collection may contain both the URI of a reference and the URI of its target resource. Slein & Davis Page 6 INTERNET-DRAFT WebDAV Collection Requirements February 1999 In the example just described, the collection might contain the URI of the graphic, and also the URIs of several references to the graphic, so that the graphic can appear multiple times in the book. 3.1.13 For any target resource, it is possible to discover what collections reference it. Though generally useful, this capability is especially critical for Document Management Systems that populate collections entirely via references. Users of these systems may wish to see what collections a particular resource belongs to, and to be able to navigate to any of those collections. 3.1.14 For any redirect reference, it is possible to obtain the URI of its target resource. This follows from the definition of a redirect reference, which is not resolved automatically. The reference must give the client access to the URI of the target resource in order for the client to redirect its request to the target resource. 3.1.15 For any resource, it is possible to discover whether it is a redirect reference. Since operations on redirect references are not passed through to their targets automatically, it is important for clients to be able to discover which resources are redirect references. Then the client can resolve the references in order to perform operations on their targets. 3.1.16 Operations on a direct reference, except for those that alter the membership of the collection that contains it, are automatically applied to its target resource. The purpose of direct references is to simplify operations for clients by hiding from them the fact that a reference is mediating between their requests and the target resource. To achieve this purpose, most operations must be passed through to the target resource automatically. However, operations that alter collection membership should not be passed through to the target. Examples of these operations are delete and move operations. The purpose of references is to allow collections to include resources that exist elsewhere. Deleting or moving a reference's URI from a collection should affect only that collection, not any other collection of which the target resource is a member, either internally or by reference. 3.1.17 For any resource, it is possible to discover whether it is a direct reference. Since the behavior of direct references is different from the behavior of redirect references, it is important for clients to be able to discover whether they are operating on a direct Slein & Davis Page 7 INTERNET-DRAFT WebDAV Collection Requirements February 1999 reference. 3.1.18 It is possible to request creation of a referential resource for which the server will enforce referential integrity. For some applications, broken references are unacceptable. Breakage may be unavoidable when a target resource resides on a different server from the referential resource that references it. Servers can, however, maintain the integrity of referential resources when they receive MOVE or DELETE requests for target resources under their own control. For applications that require referential integrity, it must be possible to specify in a request for creation of a referential resource that its integrity be enforced. A referential resource whose integrity is enforced by the server is called a strong reference. 3.1.19 It is possible when creating a reference to request that the server not enforce referential integrity for that reference. In some circumstances users may want to be able to create dangling references. For example, an administrator may want to populate a directory with references before their target resources have been created. When updating a site, he may want to remove target resources for a short period without having to destroy and recreate all the references to them. 3.1.20 These requirements are silent as to what policy should be used to enforce referential integrity. A server enforces the integrity of a reference if it ensures that the reference will not be broken, or enables the reference's owner to ensure that the reference will not be broken. There are many policies that could be adopted to fulfill this commitment. For example, a server could refuse to allow a target to be deleted while there are strong references to the target. Alternatively, the server could delete the strong references along with the target. Alternatively, the server could flag the strong references "Target Deleted" when it deletes the target. Or the server could notify the owners of all strong references when it deletes a target, allowing the owners to take whatever action they wish. These requirements say nothing about what policy should be used to enforce referential integrity. 3.1.21 It is possible to discover whether a referential resource is a strong reference or a weak reference. Knowing whether a referential resource is strong or weak allows a client to intelligently choose its own strategy for working with referential resources. For example, if a client does not know whether a particular reference is strong or weak, it may choose to recreate that referential resource to be sure of referential integrity; but if it knows that the reference is strong, it will not bother to do this. Slein & Davis Page 8 INTERNET-DRAFT WebDAV Collection Requirements February 1999 3.1.22 It is possible to discover whether a resource is the target of a strong reference. This requirement insures that both ends of a referential integrity relationship have the same information available. 3.2 Ordered Collections 3.2.1 Ordering is sufficiently standardized that different applications and servers can operate on the same ordering without private agreements. Applications and servers can apply an ordering to a collection’s members or discover the ordering of a collection's members without private agreements. They can also modify an ordering, at least with the help of a human user for semantics (See 3.2.3), without private agreements. This is the minimum that is needed to support collaborative management of an ordered collection, where different authoring tools might be used by the collaborators. It is also what allows a different tool to be used to view the collection from the one that was used to create it. Finally, it is needed in order for servers to list collection members in order, as required by 3.2.6. 3.2.2 A collection is not required to be ordered. A WebDAV server may support collections without supporting ordered collections. Even if the server supports ordered collections, there is no requirement that every collection on that server be ordered. Since these requirements concern only client-maintained orderings, clients will decide whether any given collection is ordered. The remaining requirements apply only to collections that are ordered. 3.2.3 The semantics of an ordering are discoverable. The semantics of an ordering is the principle or rule according to which the collection members are ordered. This principle must be discoverable if someone (or some application) other than the one that created a collection is to be able to add a member to it and determine where it makes sense to position the new member in the collection's ordering. In some cases it may be possible for the semantics to be expressed in a machine-usable way, so that an application could automatically position a new member in the ordering. In other cases the semantics may require a human user to apply them. In either case they should be discoverable. 3.2.4 Each collection member appears in the ordering exactly once. It would be possible to support orderings that contain only a Slein & Davis Page 9 INTERNET-DRAFT WebDAV Collection Requirements February 1999 subset of the collection members, or orderings that can contain a single collection member more than once. It is not necessary, however, since the same result can be achieved by creating a new collection with exactly the desired members, and including each member of the new collection in its ordering exactly once. This requirement implies that the server will check, whenever a member is added to an ordering, to make sure that it is not already in the ordering. It also implies that either the protocol itself or the server will insure that whenever a new member is added to a collection, it is also added to the collection ordering. 3.2.5 An ordering does not include any resources that are not members of the collection. The server must insure that when a member is removed from a collection, it is also removed from the collection's ordering. 3.2.6 When a client requests a listing of the members of a collection, this listing is returned in the order specified by the collection. This requirement frees clients from the burden of applying the ordering to the member listing. 3.2.7 It is possible to order the members of a collection in a client-specified way, not necessarily based on property values. Orderings that are based on property values can be obtained by a search protocol that supports sorted result sets. This set of requirements is not concerned with such orderings. It is intended primarily to support orderings that cannot be obtained by sorting on property values. A property is not always available that can serve as the basis for a desired ordering. For example, a professor may wish to order a collection of course readings in the sequence that coordinates the readings with her lectures. But the properties of resources at the Web site are standardized and do not include one that is appropriate to use for this purpose. Even if the professor in the example could create a "sequencenumber" property to use in sorting the collection, this strategy would be undesirable unless she knew she would not be adding any readings or changing the order of her lectures once the values of sequencenumber were set. Inserting a new reading into the sequence would require updating the sequencenumber property of each reading that comes after the new one in the sequence. Ordered collections are intended to support this sort of case, where sorting based on a property value is impossible or inefficient. 3.2.8 A single ordering may contain both ordinary and referential resources. The professor in the previous example may store some readings as Slein & Davis Page 10 INTERNET-DRAFT WebDAV Collection Requirements February 1999 internal members of the collection, but reference others from servers at another university. Nevertheless, all the readings need to be included in the ordering for her students’ use. 4 Acknowledgements This draft has benefited from thoughtful discussion by Jim Amsden, Alan Babich, Steve Carter, Geoffrey Clemm, Ken Coar, Ellis Cohen, Bruce Cragun, Spencer Dawkins, Rajiv Dulepet, David Durand, Chuck Fay, Roy Fielding, Yaron Goland, Fred Hitt, Alex Hopmann, Marcus Jager, Chris Kaler, Manoj Karichainula, Rohit Khare, Daniel LaLiberte, Steve Martin, Surendra Koduru Reddy, Sam Ruby, Nick Shelness, John Stracke, John Turner, Jim Whitehead, and others. 5 References [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." work in progress, Draft-ietf-webdav-protocol-09. Microsoft, U.C. Irvine, Netscape, Novell. November, 1998. 6 Authors' Addresses J. Slein Xerox Corporation 800 Phillips Road Webster, NY 14580 Email: jslein@crt.xerox.com J. Davis Xerox Corporation 3333 Coyote Hill Road Palo Alto, CA 94304 Email: jdavis@parc.xerox.com Expires August 26, 1999 Slein & Davis Page 11