WebDAV Collections Protocol Redmond, June 16, 1998

Referential Member A Referential Member of a collection is a resource. (Req 3.1.15) It has NO CONTENT It can have properties (Req 3.1.9), and always has certain DAV properties. Most importantly, the value of DAV:reftarget is the URI of its target resource, satisfying Req 3.1.6 that it is possible to obtain the URI of the target resource of any referential resource. The DAV:resourcetype property of a referential member always has the value refmember. Satisfies Req 3.1.12 that it be possible to discover whether a collection member is internal or referential.

Strong Reference Strong references satisfy requirement 3.1.11that it be possible to request creation of a referential member for which the server guarantees referential integrity. DAV:refintegrity = “T” for strong references. Satisfies requirement 3.1.13 that it be possible to discover whether a referential member is strong or weak. To support this guarantee, the target resource has a DAV:refsource property whose value is a list of the URIs of all strong references to it. This property also satisfies requirement 3.1.14 that it be possible to discover whether a resource is the target of a strong reference.

Weak Reference DAV:refintegrity = “F” for these resources, satisfying requirement 3.1.13 that it be possible to discover whether a referential member is weak or strong.

Creating Referential Members (revised) ADDREF /~whitehead/dav/ HTTP/1.1 Host: www.ics.uci.edu 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 Referential-Member and Ref-Target headers must be present when creating a referential member. Referential-Member gives the URI of the member itself. Ref-Target gives the URI of its target resource. Value gets stored in the DAV:reftarget property. Ref-Integrity header is optional. If not present, server assumes F. If present with value = “T”, server must fail the request if it can’t guarantee referential integrity. Server always sets DAV:refintegrity property based on this header, or with the default value F. Also sets target resource’s DAV:refsource property when it creates a strong reference. Content-Length header should be 0. Server should ignore any content. Position header is optional and supports ordering -- we’ll talk about it later. Jim suggests making the header names consistent, either all “Referential-” or all “Ref-”.

Deleting Referential Members Use the HTTP DELETE method No effect on target except for updates to its DAV:refsource property when a strong reference is deleted

Listing Collection Members Use the DAV PROPFIND method Listing will include both internal and referential members If Depth = infinity, the server SHOULD NOT (MUST NOT?) follow references into any collections to which they may refer LA discussion led to recommendation not to follow references into target collections: Would have to check for cycles Risk very deep hierarchies Jim thinks the LA discussion supported the stronger statement that servers MUST NOT follow references into target collections.

Other Operations on Referential Members (revised) LOCK, PROPPATCH, MOVE, COPY affect the referential member, not its target resource Use MOVE and COPY with the Ref-Integrity header to create a strong reference at the destination GET and PROPFIND retrieve the headers / properties of the referential member, not of its target resource The general principle is that operations on a referential member do not affect its target. If you want to operate on the target, consult the DAV:reftarget property for the URI of the target, and then operate directly on it. Request MUST fail if the server can’t comply with the Ref-Integrity header. This includes cases where the resource is being moved from a compliant location to a non-compliant location.

Operations on Target Resources Operations on targets have no effect on referential members except as needed to maintain referential integrity for strong references MOVE on target causes a strong reference’s DAV:reftarget property to be updated DELETE on target of a strong reference: Server decides how to enforce referential integrity Server makes the choice: delete the reference with the target, or decline to delete the target (Declining to delete the target is a security risk -- clients can prevent servers from ever deleting anything by creating strong references) (Other possible strategies: If the target of a strong reference is deleted, it becomes an internal member of one of the collections that has a strong reference to it. Let the owner of the target resource decide how integrity is to be maintained.)

Ordered Collections Implemented as a new DAV:ordering property of collections, whose value is a list of hrefs to the collection members, together with an orderingtype, which is an href to a definition of the semantics of the ordering. “Pages ordered in sequence for printing” “Simplest to most complex” “Articles ordered as they should be read to coordinate with lectures” “Alphabetical by author” “ORDER BY Author ASC”

Characteristics of Orderings At most 1 ordering per collection Client decides whether a collection is ordered If a collection is ordered, each collection member belongs to the ordering exactly once Only members of the collection can belong to its ordering orderingtype SHOULD point to a resource that describes the semantics of the ordering

Manipulating Orderings (revised) Retrieve the current DAV:ordering property with PROPFIND Modify DAV:ordering with PROPPATCH Use the Position header with PUT, MOVE, or COPY to insert a member into the ordering at the time it is added to the collection If you don’t specify a position in the ordering when adding a member, the server positions it at the end of the ordering (because every member of the collection is required to be in the ordering exactly once). This position can be modified later using PROPPATCH. There is no special method for creating an ordering. There is no header for MKCOL to say that it is an ordered collection. The upshot of this is that an ordering gets created the first time someone adds a member with the Position header or does a PROPPATCH with DAV:ordering. If there are a bunch of members already in the collection at that time, what happens? (Maybe attempt to use Position fails, and client must do PROPPATCH). If we add a header for MKCOL, need a way to change your mind later -- use PROPPATCH. Problems about near-simultaneous operations on orderings: 2 clients both try to insert a new member at Position = 3, the last one wins. A client requests a new member to be inserted after URI xxx, but in the mean time URI xxx has been removed from the collection, the request fails.

PROPPATCH Example PROPPATCH /coll-1/ HTTP/1.1 Host: www.foo.com Content-Type: text/xml Content-Length: xxxx <?xml version=“1.0” ?> <?xml:namespace ns=“DAV:” prefix=“D” ?> <D:propertyupdate> <D:set> <D:prop> <D:ordering> <D:orderingtype> <href>http://www.foo.com/semantics/s1.txt</href> </D:orderingtype> <href>map</href> <href>history</href> <href>culture</href> </D:ordering> </D:prop> </D:set> </D:propertyupdate>

Position Header Example PUT /coll1/history HTTP/1.1 Host: www.foo.com Content-Type: text/plain Content-Length: xxxx Position: After map <entity body> Position header lets you say: First Last At <sequence number> Before <URI> After <URI>

Server Responsibilities Remove href from ordering when member is removed from collection Add href to ordering when member is added to collection At requested position if Position header is used At end of ordering otherwise Verify values of DAV:ordering submitted with PROPPATCH Respond to PROPFIND with ordered listing if collection is ordered If the PROPPATCH request doesn’t follow the rules (each collection member must be in the ordering exactly once, no hrefs in the ordering for resources that are not collection members), the request MUST fail.

Creating an Ordered Collection (proposal) Ordered header for use with MKCOL Value is URI of ordering semantics Example MKCOL /collection1/ HTTP/1.1 Host: www.foo.com Ordered: http://www.foo.com/semantics/s1.txt Since orderings are properties of collections, it makes more sense to create them when the collection is created than incidentally when the first member is added or by PROPPATCH after creation of the collection. You can change your mind about the ordering semantics later by PROPPATCH. You can change your mind later about whether the collection is ordered by PROPPATCH. Would an ordering still get created automatically if someone did PUT or ADDREF with Position on an unordered collection? Can you still directly create the DAV:ordering property with PROPPATCH?

Implementation Note (proposal) Recommend that clients follow Mandatory Extensions specification when they want method to fail if server doesn’t recognize ordering headers Ordered header with MKCOL Position header with PUT, MOVE, or COPY Define URI for extension semantics DAV:OrderedCollectionHeaders

Issues MOVE or COPY a collection that has referential members MOVE or COPY an ordered collection Let client choose whether Ref-Integrity, Ordered, and Position headers are optional or mandatory? How to enforce referential integrity for requests to DELETE a target resource Potential problems for ordering requests without transactions PROPPATCH vs. headers for manipulating orderings? Or allow both? What should happen to requests to MOVE or COPY a collection with ref members, if the destination doesn’t comply with DAV referencing? Proposal: As in DAV spec, if can’t MOVE or COPY any member of a colleciton, MUST NOT move or copy any member of the collection. What about MOVE or COPY an ordered collection to a location that does not support ordering? The spec currently says the server MUST fail a request if it can’t comply with the Ref-Integrity or Position header, but maybe we should let the client say whether it wants the request to fail. There are lots of options for how to maintain referential integrity. The spec currently lets the server decide, and gives it 2 options: delete strong references when the target is deleted, or decline to delete a target of strong references. Other possibilities include making the target an internal member of one of the collections from which it was referenced, letting the owner of the target decide how ref integrity should be enforced, . . . Since we don’t have transactions, there are potential problems for ordering requests: 2 clients ask to add a member to an ordering at position 3 -- the last request wins. A client asks to add a member to an ordering after URI xxx, which has just been deleted -- etc. Decide whether to allow clients to use PROPPATCH to manipulate orderings, or only do it indirectly through headers, or allow both.

Information Draft protocol specification is at: http://www.ics.uci.edu/~ejw/authoring/collection/draft-ietf-webdav-collection-protocol-00.txt Author can be reached at: slein@wrc.xerox.com