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
Datatracker
Report a datatracker bug
draft-ietf-webdav-collection-protocol-00
Internet-Draft
| Document | Document type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
Expired & archived
|
|
|---|---|---|---|
| Select version | |||
| Compare versions | |||
| Author | |||
| RFC stream |
|
||
| Other formats | |||
| Additional resources | Mailing list discussion |