5. Collections of Web Resources

This section provides a description of a type of Web resource, the collection, and discusses its interactions with the HTTP URL namespace and with HTTP methods. The purpose of a collection resource is to model collection-like objects (e.g., file system directories) within a server's namespace.

All DAV-compliant resources MUST support the HTTP URL namespace model specified herein.

5.1 HTTP URL Namespace Model

The HTTP URL namespace is a hierarchical namespace where the hierarchy is delimited with the "/" character.

An HTTP URL namespace is said to be consistent if it meets the following conditions: for every URL in the HTTP hierarchy there exists a collection that contains that URL as an internal member URL. The root, or top-level collection of the namespace under consideration, is exempt from the previous rule. The top-level collection of the namespace under consideration is not necessarily the collection identified by the absolute path '/' -- it may be identified by one or more path segments (e.g., /servlets/webdav/...)

Neither HTTP/1.1 nor WebDAV requires that the entire HTTP URL namespace be consistent -- a WebDAV-compatible resource may not have a parent collection. However, certain WebDAV methods are prohibited from producing results that cause namespace inconsistencies.

As is implicit in [RFC2616] and [RFC3986], any resource, including collection resources, MAY be identified by more than one URI. For example, a resource could be identified by multiple HTTP URLs.

5.2 Collection Resources

Collection resources differ from other resources in that they also act as containers. Some HTTP methods apply only to a collection, but some apply to some or all of the resources inside the container defined by the collection. When the scope of a method is not clear, the client can specify what depth to apply. Depth can be either zero levels (only the collection), one level (the collection and directly contained resources), or infinite levels (the collection and all contained resources recursively).

A collection's state consists of at least a set of mappings between path segments and resources, and a set of properties on the collection itself. In this document, a resource B will be said to be contained in the collection resource A if there is a path segment mapping that maps to B and that is contained in A. A collection MUST contain at most one mapping for a given path segment, i.e., it is illegal to have the same path segment mapped to more than one resource.

Properties defined on collections behave exactly as do properties on non-collection resources. A collection MAY have additional state such as entity bodies returned by GET.

For all WebDAV-compliant resources A and B, identified by URLs "U" and "V", respectively, such that "V" is equal to "U/SEGMENT", A MUST be a collection that contains a mapping from "SEGMENT" to B. So, if resource B with URL http://example.com/bar/blah is WebDAV compliant and if resource A with URL http://example.com/bar/ is WebDAV compliant, then resource A must be a collection and must contain exactly one mapping from "blah" to B.

Although commonly a mapping consists of a single segment and a resource, in general, a mapping consists of a set of segments and a resource. This allows a server to treat a set of segments as equivalent (i.e., either all of the segments are mapped to the same resource, or none of the segments are mapped to a resource). For example, a server that performs case-folding on segments will treat the segments "ab", "Ab", "aB", and "AB" as equivalent. A client can then use any of these segments to identify the resource. Note that a PROPFIND result will select one of these equivalent segments to identify the mapping, so there will be one PROPFIND response element per mapping, not one per segment in the mapping.

Collection resources MAY have mappings to non-WebDAV-compliant resources in the HTTP URL namespace hierarchy but are not required to do so. For example, if resource X with URL http://example.com/bar/blah is not WebDAV compliant and resource A with URL http://example.com/bar/ identifies a WebDAV collection, then A may or may not have a mapping from "blah" to X.

If a WebDAV-compliant resource has no WebDAV-compliant internal members in the HTTP URL namespace hierarchy, then the WebDAV-compliant resource is not required to be a collection.

There is a standing convention that when a collection is referred to by its name without a trailing slash, the server MAY handle the request as if the trailing slash were present. In this case, it SHOULD return a Content-Location header in the response, pointing to the URL ending with the "/". For example, if a client invokes a method on http://example.com/blah (no trailing slash), the server may respond as if the operation were invoked on http://example.com/blah/ (trailing slash), and should return a Content-Location header with the value http://example.com/blah/. Wherever a server produces a URL referring to a collection, the server SHOULD include the trailing slash. In general, clients SHOULD use the trailing slash form of collection names. If clients do not use the trailing slash form the client needs to be prepared to see a redirect response. Clients will find the DAV:resourcetype property more reliable than the URL to find out if a resource is a collection.

Clients MUST be able to support the case where WebDAV resources are contained inside non-WebDAV resources. For example, if an OPTIONS response from http://example.com/servlet/dav/collection indicates WebDAV support, the client cannot assume that http://example.com/servlet/dav/ or its parent necessarily are WebDAV collections.

A typical scenario in which mapped URLs do not appear as members of their parent collection is the case where a server allows links or redirects to non-WebDAV resources. For instance, "/col/link" might not appear as a member of "/col/", although the server would respond with a 302 status to a GET request to "/col/link"; thus, the URL "/col/link" would indeed be mapped. Similarly, a dynamically-generated page might have a URL mapping from "/col/index.html", thus this resource might respond with a 200 OK to a GET request yet not appear as a member of "/col/".

Some mappings to even WebDAV-compliant resources might not appear in the parent collection. An example for this case are servers that support multiple alias URLs for each WebDAV-compliant resource. A server may implement case-insensitive URLs, thus "/col/a" and "/col/A" identify the same resource, yet only either "a" or "A" is reported upon listing the members of "/col". In cases where a server treats a set of segments as equivalent, the server MUST expose only one preferred segment per mapping, consistently chosen, in PROPFIND responses.