[Search] [pdf|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 04                                                
     WEBDAV Working Group                                          J. Slein
     INTERNET DRAFT                                       Xerox Corporation
     <draft-ietf-webdav-collection-protocol-00>                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 <w3c-dist-auth@w3.org>, which may be joined by sending a
        message with subject "subscribe" to <w3c-dist-auth-
        request@w3.org>.

        Discussions of the WEBDAV working group are archived at URL:
        <http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth>.

     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.

        <!ELEMENT reftarget href>

    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.

        <!ELEMENT refsource href+>

    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.

        <!ELEMENT refintegrity ("T" | "F")>

    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.

        <!ELEMENT ordering (orderingtype, href*) >

    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.

        <!ELEMENT orderingtype href >

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

        <!ELEMENT refmember 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