As per Relevance of the word collection, we have this rfc below:
Network Working Group Y.
Request for Comments: 2518
Category: Standards Track E.
UC
A.
S.
D.
February 1999
HTTP Extensions for Distributed Authoring --
Status of this
This document specifies an Internet standards track protocol for
Internet community, and requests discussion and suggestions
improvements. Please refer to the current edition of the "
Official Protocol Standards" (STD 1) for the standardization
and status of this protocol. Distribution of this memo is unlimited
Copyright
Copyright (C) The Internet Society (1999). All Rights Reserved
This document specifies a set of methods, headers, and content-
ancillary to HTTP/1.1 for the management of resource properties
creation and management of resource collections,
manipulation, and resource locking (collision avoidance).
Table of
ABSTRACT............................................................1
1 INTRODUCTION .....................................................5
2 NOTATIONAL CONVENTIONS ...........................................7
3 TERMINOLOGY ......................................................7
4 DATA MODEL FOR RESOURCE PROPERTIES ...............................8
4.1 The Resource Property Model ...................................8
4.2 Existing Metadata Proposals ...................................8
4.3 Properties and HTTP Headers ...................................9
4.4 Property Values ...............................................9
4.5 Property Names ...............................................10
4.6 Media Independent Links ......................................10
5 COLLECTIONS OF WEB RESOURCES ....................................11
Goland, et al. Standards Track [Page 1]
RFC 2518 WEBDAV February 1999
5.1 HTTP URL Namespace Model .....................................11
5.2 Collection Resources .........................................11
5.3 Creation and Retrieval of Collection Resources ...............12
5.4 Source Resources and Output Resources ........................13
6 LOCKING .........................................................14
6.1 Exclusive Vs. Shared Locks ...................................14
6.2 Required Support .............................................16
6.3 Lock Tokens ..................................................16
6.4 opaquelocktoken Lock Token URI Scheme ........................16
6.4.1 Node Field Generation Without the IEEE 802 Address ........17
6.5 Lock Capability Discovery ....................................19
6.6 Active Lock Discovery ........................................19
6.7 Usage Considerations .........................................19
7 WRITE LOCK ......................................................20
7.1 Methods Restricted by Write Locks ............................20
7.2 Write Locks and Lock Tokens ..................................20
7.3 Write Locks and Properties ...................................20
7.4 Write Locks and Null Resources ...............................21
7.5 Write Locks and Collections ..................................21
7.6 Write Locks and the If Request Header ........................22
7.6.1 Example - Write Lock ......................................22
7.7 Write Locks and COPY/MOVE ....................................23
7.8 Refreshing Write Locks .......................................23
8 HTTP METHODS FOR DISTRIBUTED AUTHORING ..........................23
8.1 PROPFIND .....................................................24
8.1.1 Example - Retrieving Named Properties .....................25
8.1.2 Example - Using allprop to Retrieve All Properties ........26
8.1.3 Example - Using propname to Retrieve all Property Names ...29
8.2 PROPPATCH ....................................................31
8.2.1 Status Codes for use with 207 (Multi-Status) ..............31
8.2.2 Example - PROPPATCH .......................................32
8.3 MKCOL Method .................................................33
8.3.1 Request ...................................................33
8.3.2 Status Codes ..............................................33
8.3.3 Example - MKCOL ...........................................34
8.4 GET, HEAD for Collections ....................................34
8.5 POST for Collections .........................................35
8.6 DELETE .......................................................35
8.6.1 DELETE for Non-Collection Resources .......................35
8.6.2 DELETE for Collections ....................................36
8.7 PUT ..........................................................36
8.7.1 PUT for Non-Collection Resources ..........................36
8.7.2 PUT for Collections .......................................37
8.8 COPY Method ..................................................37
8.8.1 COPY for HTTP/1.1 resources ...............................37
8.8.2 COPY for Properties .......................................38
8.8.3 COPY for Collections ......................................38
8.8.4 COPY and the Overwrite Header .............................39
Goland, et al. Standards Track [Page 2]
RFC 2518 WEBDAV February 1999
8.8.5 Status Codes ..............................................39
8.8.6 Example - COPY with Overwrite .............................40
8.8.7 Example - COPY with No Overwrite ..........................40
8.8.8 Example - COPY of a Collection ............................41
8.9 MOVE Method ..................................................42
8.9.1 MOVE for Properties .......................................42
8.9.2 MOVE for Collections ......................................42
8.9.3 MOVE and the Overwrite Header .............................43
8.9.4 Status Codes ..............................................43
8.9.5 Example - MOVE of a Non-Collection ........................44
8.9.6 Example - MOVE of a Collection ............................44
8.10 LOCK Method ..................................................45
8.10.1 Operation .................................................46
8.10.2 The Effect of Locks on Properties and Collections .........46
8.10.3 Locking Replicated Resources ..............................46
8.10.4 Depth and Locking .........................................46
8.10.5 Interaction with other Methods ............................47
8.10.6 Lock Compatibility Table ..................................47
8.10.7 Status Codes ..............................................48
8.10.8 Example - Simple Lock Request .............................48
8.10.9 Example - Refreshing a Write Lock .........................49
8.10.10 Example - Multi-Resource Lock Request ....................50
8.11 UNLOCK Method ................................................51
8.11.1 Example - UNLOCK ..........................................52
9 HTTP HEADERS FOR DISTRIBUTED AUTHORING ..........................52
9.1 DAV Header ...................................................52
9.2 Depth Header .................................................52
9.3 Destination Header ...........................................54
9.4 If Header ....................................................54
9.4.1 No-tag-list Production ....................................55
9.4.2 Tagged-list Production ....................................55
9.4.3 not Production ............................................56
9.4.4 Matching Function .........................................56
9.4.5 If Header and Non-DAV Compliant Proxies ...................57
9.5 Lock-Token Header ............................................57
9.6 Overwrite Header .............................................57
9.7 Status-URI Response Header ...................................57
9.8 Timeout Request Header .......................................58
10 STATUS CODE EXTENSIONS TO HTTP/1.1 ............................59
10.1 102 Processing ...............................................59
10.2 207 Multi-Status .............................................59
10.3 422 Unprocessable Entity .....................................60
10.4 423 Locked ...................................................60
10.5 424 Failed Dependency ........................................60
10.6 507 Insufficient Storage .....................................60
11 MULTI-STATUS RESPONSE .........................................60
12 XML ELEMENT DEFINITIONS .......................................61
12.1 activelock XML Element .......................................61
Goland, et al. Standards Track [Page 3]
RFC 2518 WEBDAV February 1999
12.1.1 depth XML Element .........................................61
12.1.2 locktoken XML Element .....................................61
12.1.3 timeout XML Element .......................................61
12.2 collection XML Element .......................................62
12.3 href XML Element .............................................62
12.4 link XML Element .............................................62
12.4.1 dst XML Element ...........................................62
12.4.2 src XML Element ...........................................62
12.5 lockentry XML Element ........................................63
12.6 lockinfo XML Element .........................................63
12.7 lockscope XML Element ........................................63
12.7.1 exclusive XML Element .....................................63
12.7.2 shared XML Element ........................................63
12.8 locktype XML Element .........................................64
12.8.1 write XML Element .........................................64
12.9 multistatus XML Element ......................................64
12.9.1 response XML Element ......................................64
12.9.2 responsedescription XML Element ...........................65
12.10 owner XML Element ...........................................65
12.11 prop XML element ............................................66
12.12 propertybehavior XML element ................................66
12.12.1 keepalive XML element ....................................66
12.12.2 omit XML element .........................................67
12.13 propertyupdate XML element ..................................67
12.13.1 remove XML element .......................................67
12.13.2 set XML element ..........................................67
12.14 propfind XML Element ........................................68
12.14.1 allprop XML Element ......................................68
12.14.2 propname XML Element .....................................68
13 DAV PROPERTIES ................................................68
13.1 creationdate Property ........................................69
13.2 displayname Property .........................................69
13.3 getcontentlanguage Property ..................................69
13.4 getcontentlength Property ....................................69
13.5 getcontenttype Property ......................................70
13.6 getetag Property .............................................70
13.7 getlastmodified Property .....................................70
13.8 lockdiscovery Property .......................................71
13.8.1 Example - Retrieving the lockdiscovery Property ...........71
13.9 resourcetype Property ........................................72
13.10 source Property .............................................72
13.10.1 Example - A source Property ..............................72
13.11 supportedlock Property ......................................73
13.11.1 Example - Retrieving the supportedlock Property ..........73
14 INSTRUCTIONS FOR PROCESSING XML IN DAV ........................74
15 DAV COMPLIANCE CLASSES ........................................75
15.1 Class 1 ......................................................75
15.2 Class 2 ......................................................75
Goland, et al. Standards Track [Page 4]
RFC 2518 WEBDAV February 1999
16 INTERNATIONALIZATION CONSIDERATIONS ...........................76
17 SECURITY CONSIDERATIONS .......................................77
17.1 Authentication of Clients ....................................77
17.2 Denial of Service ............................................78
17.3 Security through Obscurity ...................................78
17.4 Privacy Issues Connected to Locks ............................78
17.5 Privacy Issues Connected to Properties .......................79
17.6 Reduction of Security due to Source Link .....................79
17.7 Implications of XML External Entities ........................79
17.8 Risks Connected with Lock Tokens .............................80
18 IANA CONSIDERATIONS ...........................................80
19 INTELLECTUAL PROPERTY .........................................81
20 ACKNOWLEDGEMENTS ..............................................82
21 REFERENCES ....................................................82
21.1 Normative References .........................................82
21.2 Informational References .....................................83
22 AUTHORS' ADDRESSES ............................................84
23 APPENDICES ....................................................86
23.1 Appendix 1 - WebDAV Document Type Definition .................86
23.2 Appendix 2 - ISO 8601 Date and Time Profile ..................88
23.3 Appendix 3 - Notes on Processing XML Elements ................89
23.3.1 Notes on Empty XML Elements ...............................89
23.3.2 Notes on Illegal XML Processing ...........................89
23.4 Appendix 4 -- XML Namespaces for WebDAV ......................92
23.4.1 Introduction ..............................................92
23.4.2 Meaning of Qualified Names ................................92
24 FULL COPYRIGHT STATEMENT ......................................94
1
This document describes an extension to the HTTP/1.1 protocol
allows clients to perform remote web content authoring operations
This extension provides a coherent set of methods, headers,
entity body formats, and response entity body formats that
operations for
Properties: The ability to create, remove, and query
about Web pages, such as their authors, creation dates, etc. Also
the ability to link pages of any media type to related pages
Collections: The ability to create sets of documents and to
a hierarchical membership listing (like a directory listing in a
system).
Goland, et al. Standards Track [Page 5]
RFC 2518 WEBDAV February 1999
Locking: The ability to keep more than one person from working on
document at the same time. This prevents the "lost update problem,"
in which modifications are lost as first one author then
writes changes without merging the other author's changes
Namespace Operations: The ability to instruct the server to copy
move Web resources
Requirements and rationale for these operations are described in
companion document, "Requirements for a Distributed Authoring
Versioning Protocol for the World Wide Web" [RFC2291].
The sections below provide a detailed introduction to
properties (section 4), collections of resources (section 5),
locking operations (section 6). These sections introduce
abstractions manipulated by the WebDAV-specific HTTP
described in section 8, "HTTP Methods for Distributed Authoring".
In HTTP/1.1, method parameter information was exclusively encoded
HTTP headers. Unlike HTTP/1.1, WebDAV encodes method
information either in an Extensible Markup Language (XML) [REC-XML
request entity body, or in an HTTP header. The use of XML to
method parameters was motivated by the ability to add extra
elements to existing structures, providing extensibility; and
XML's ability to encode information in ISO 10646 character sets
providing internationalization support. As a rule of thumb
parameters are encoded in XML entity bodies when they have
length, or when they may be shown to a human user and hence
encoding in an ISO 10646 character set. Otherwise, parameters
encoded within HTTP headers. Section 9 describes the new
headers used with WebDAV methods
In addition to encoding method parameters, XML is used in WebDAV
encode the responses from methods, providing the extensibility
internationalization advantages of XML for method output, as well
input
XML elements used in this specification are defined in section 12.
The XML namespace extension (Appendix 4) is also used in
specification in order to allow for new XML elements to be
without fear of colliding with other element names
While the status codes provided by HTTP/1.1 are sufficient
describe most error conditions encountered by WebDAV methods,
are some errors that do not fall neatly into the existing categories
New status codes developed for the WebDAV methods are defined
section 10. Since some WebDAV methods may operate over
Goland, et al. Standards Track [Page 6]
RFC 2518 WEBDAV February 1999
resources, the Multi-Status response has been introduced to
status information for multiple resources. The Multi-Status
is described in section 11.
WebDAV employs the property mechanism to store information about
current state of the resource. For example, when a lock is taken
on a resource, a lock information property describes the
state of the lock. Section 13 defines the properties used within
WebDAV specification
Finishing off the specification are sections on what it means to
compliant with this specification (section 15),
internationalization support (section 16), and on security (
17).
2 Notational
Since this document describes a set of extensions to the HTTP/1.1
protocol, the augmented BNF used herein to describe protocol
is exactly the same as described in section 2.1 of [RFC2068].
this augmented BNF uses the basic production rules provided
section 2.2 of [RFC2068], these rules apply to this document as well
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
document are to be interpreted as described in RFC 2119 [RFC2119].
3
URI/URL - A Uniform Resource Identifier and Uniform Resource Locator
respectively. These terms (and the distinction between them)
defined in [RFC2396].
Collection - A resource that contains a set of URIs, termed
URIs, which identify member resources and meets the requirements
section 5 of this specification
Member URI - A URI which is a member of the set of URIs contained
a collection
Internal Member URI - A Member URI that is immediately relative
the URI of the collection (the definition of immediately relative
given in section 5.2).
Property - A name/value pair that contains descriptive
about a resource
Goland, et al. Standards Track [Page 7]
RFC 2518 WEBDAV February 1999
Live Property - A property whose semantics and syntax are enforced
the server. For example, the live "getcontentlength" property
its value, the length of the entity returned by a GET request
automatically calculated by the server
Dead Property - A property whose semantics and syntax are
enforced by the server. The server only records the value of a
property; the client is responsible for maintaining the
of the syntax and semantics of a dead property
Null Resource - A resource which responds with a 404 (Not Found)
any HTTP/1.1 or DAV method except for PUT, MKCOL, OPTIONS and LOCK
A NULL resource MUST NOT appear as a member of its parent collection
4 Data Model for Resource
4.1 The Resource Property
Properties are pieces of data that describe the state of a resource
Properties are data about data
Properties are used in distributed authoring environments to
for efficient discovery and management of resources. For example,
'subject' property might allow for the indexing of all resources
their subject, and an 'author' property might allow for the
of what authors have written which documents
The DAV property model consists of name/value pairs. The name of
property identifies the property's syntax and semantics, and
an address by which to refer to its syntax and semantics
There are two categories of properties: "live" and "dead". A
property has its syntax and semantics enforced by the server.
properties include cases where a) the value of a property is read
only, maintained by the server, and b) the value of the property
maintained by the client, but the server performs syntax checking
submitted values. All instances of a given live property MUST
with the definition associated with that property name. A
property has its syntax and semantics enforced by the client;
server merely records the value of the property verbatim
4.2 Existing Metadata
Properties have long played an essential role in the maintenance
large document repositories, and many current proposals contain
notion of a property, or discuss web metadata more generally.
include PICS [REC-PICS], PICS-NG, XML, Web Collections, and
proposals on representing relationships within HTML. Work on PICS-
Goland, et al. Standards Track [Page 8]
RFC 2518 WEBDAV February 1999
and Web Collections has been subsumed by the Resource
Framework (RDF) metadata activity of the World Wide Web Consortium
RDF consists of a network-based data model and an XML
of that model
Some proposals come from a digital library perspective.
include the Dublin Core [RFC2413] metadata set and the
Framework [WF], a container architecture for different
schemas. The literature includes many examples of metadata
including MARC [USMARC], a bibliographic metadata format, and
technical report bibliographic format employed by the Dienst
[RFC1807]. Additionally, the proceedings from the first IEEE
conference describe many community-specific metadata sets
Participants of the 1996 Metadata II Workshop in Warwick, UK [WF],
noted that "new metadata sets will develop as the
infrastructure matures" and "different communities will propose
design, and be responsible for different types of metadata."
observations can be corroborated by noting that many community
specific sets of metadata already exist, and there is
motivation for the development of new forms of metadata as
communities increasingly make their data available in digital form
requiring a metadata format to assist data location and cataloging
4.3 Properties and HTTP
Properties already exist, in a limited sense, in HTTP
headers. However, in distributed authoring environments a
large number of properties are needed to describe the state of
resource, and setting/returning them all through HTTP headers
inefficient. Thus a mechanism is needed which allows a principal
identify a set of properties in which the principal is interested
to set or retrieve just those properties
4.4 Property
The value of a property when expressed in XML MUST be well formed
XML has been chosen because it is a flexible, self-describing
structured data format that supports rich schema definitions,
because of its support for multiple character sets. XML's self
describing nature allows any property's value to be extended
adding new elements. Older clients will not break when
encounter extensions because they will still have the data
in the original schema and will ignore elements they do
understand. XML's support for multiple character sets allows
human-readable property to be encoded and read in a character
familiar to the user. XML's support for multiple human languages
Goland, et al. Standards Track [Page 9]
RFC 2518 WEBDAV February 1999
using the "xml:lang" attribute, handles cases where the
character set is employed by multiple human languages
4.5 Property
A property name is a universally unique identifier that is
with a schema that provides information about the syntax
semantics of the property
Because a property's name is universally unique, clients can
upon consistent behavior for a particular property across
resources, on the same and across different servers, so long as
property is "live" on the resources in question, and
implementation of the live property is faithful to its definition
The XML namespace mechanism, which is based on URIs [RFC2396],
used to name properties because it prevents namespace collisions
provides for varying degrees of administrative control
The property namespace is flat; that is, no hierarchy of
is explicitly recognized. Thus, if a property A and a property A/
exist on a resource, there is no recognition of any
between the two properties. It is expected that a
specification will eventually be produced which will address
relating to hierarchical properties
Finally, it is not possible to define the same property twice on
single resource, as this would cause a collision in the resource'
property namespace
4.6 Media Independent
Although HTML resources support links to other resources, the
needs more general support for links between resources of any
type (media types are also known as MIME types, or content types).
WebDAV provides such links. A WebDAV link is a special type
property value, formally defined in section 12.4, that allows
connections to be established between resources of any media type
The property value consists of source and destination
Resource Identifiers (URIs); the property name identifies the
type
Goland, et al. Standards Track [Page 10]
RFC 2518 WEBDAV February 1999
5 Collections of Web
This section provides a description of a new type of Web resource
the collection, and discusses its interactions with the HTTP
namespace. The purpose of a collection resource is to
collection-like objects (e.g., file system directories) within
server's namespace
All DAV compliant resources MUST support the HTTP URL namespace
specified herein
5.1 HTTP URL Namespace
The HTTP URL namespace is a hierarchical namespace where
hierarchy is delimited with the "/" character
An HTTP URL namespace is said to be consistent if it meets
following conditions: for every URL in the HTTP hierarchy
exists a collection that contains that URL as an internal member
The root, or top-level collection of the namespace
consideration is exempt from the previous rule
Neither HTTP/1.1 nor WebDAV require that the entire HTTP
namespace be consistent. However, certain WebDAV methods
prohibited from producing results that cause
inconsistencies
Although implicit in [RFC2068] and [RFC2396], any resource,
collection resources, MAY be identified by more than one URI.
example, a resource could be identified by multiple HTTP URLs
5.2 Collection
A collection is a resource whose state consists of at least a list
internal member URIs and a set of properties, but which may
additional state such as entity bodies returned by GET. An
member URI MUST be immediately relative to a base URI of
collection. That is, the internal member URI is equal to
containing collection's URI plus an additional segment for non
collection resources, or additional segment plus trailing slash "/"
for collection resources, where segment is defined in section 3.3
[RFC2396].
Any given internal member URI MUST only belong to the
once, i.e., it is illegal to have multiple instances of the same
in a collection. Properties defined on collections behave exactly
do properties on non-collection resources
Goland, et al. Standards Track [Page 11]
RFC 2518 WEBDAV February 1999
For all WebDAV compliant resources A and B, identified by URIs U
V, for which U is immediately relative to V, B MUST be a
that has U as an internal member URI. So, if the resource with
http://foo.com/bar/blah is WebDAV compliant and if the resource
URL http://foo.com/bar/ is WebDAV compliant then the resource
URL http://foo.com/bar/ must be a collection and must contain
http://foo.com/bar/blah as an internal member
Collection resources MAY list the URLs of non-WebDAV
children in the HTTP URL namespace hierarchy as internal members
are not required to do so. For example, if the resource with
http://foo.com/bar/blah is not WebDAV compliant and the
http://foo.com/bar/ identifies a collection then
http://foo.com/bar/blah may or may not be an internal member of
collection with URL http://foo.com/bar/.
If a WebDAV compliant resource has no WebDAV compliant children
the HTTP URL namespace hierarchy then the WebDAV compliant
is not required to be a collection
There is a standing convention that when a collection is referred
by its name without a trailing slash, the trailing slash
automatically appended. Due to this, a resource may accept a
without a trailing "/" to point to a collection. In this case
SHOULD return a content-location header in the response pointing
the URI ending with the "/". For example, if a client invokes
method on http://foo.bar/blah (no trailing slash), the
http://foo.bar/blah/ (trailing slash) may respond as if the
were invoked on it, and should return a content-location header
http://foo.bar/blah/ in it. In general clients SHOULD use the "/"
form of collection names
A resource MAY be a collection but not be WebDAV compliant. That is
the resource may comply with all the rules set out in
specification regarding how a collection is to behave
necessarily supporting all methods that a WebDAV compliant
is required to support. In such a case the resource may return
DAV:resourcetype property with the value DAV:collection but MUST
return a DAV header containing the value "1" on an OPTIONS response
5.3 Creation and Retrieval of Collection
This document specifies the MKCOL method to create new
resources, rather than using the existing HTTP/1.1 PUT or
method, for the following reasons
Goland, et al. Standards Track [Page 12]
RFC 2518 WEBDAV February 1999
In HTTP/1.1, the PUT method is defined to store the request body
the location specified by the Request-URI. While a
format for a collection can readily be constructed for use with PUT
the implications of sending such a description to the server
undesirable. For example, if a description of a collection
omitted some existing resources were PUT to a server, this might
interpreted as a command to remove those members. This would
PUT to perform DELETE functionality, which is undesirable since
changes the semantics of PUT, and makes it difficult to
DELETE functionality with an access control scheme based on methods
While the POST method is sufficiently open-ended that a "create
collection" POST command could be constructed, this is
because it would be difficult to separate access control
collection creation from other uses of POST
The exact definition of the behavior of GET and PUT on collections
defined later in this document
5.4 Source Resources and Output
For many resources, the entity returned by a GET method
matches the persistent state of the resource, for example, a GIF
stored on a disk. For this simple case, the URI at which a
is accessed is identical to the URI at which the source (
persistent state) of the resource is accessed. This is also the
for HTML source files that are not processed by the server prior
transmission
However, the server can sometimes process HTML resources before
are transmitted as a return entity body. For example, a server
side-include directive within an HTML file might instruct a server
replace the directive with another value, such as the current date
In this case, what is returned by GET (HTML plus date) differs
the persistent state of the resource (HTML plus directive).
Typically there is no way to access the HTML resource containing
unprocessed directive
Sometimes the entity returned by GET is the output of a data
producing process that is described by one or more source
(that may not even have a location in the URI namespace). A
data-producing process may dynamically generate the state of
potentially large number of output resources. An example of this
a CGI script that describes a "finger" gateway process that maps
of the namespace of a server into finger requests, such
http://www.foo.bar.org/finger_gateway/user@host
Goland, et al. Standards Track [Page 13]
RFC 2518 WEBDAV February 1999
In the absence of distributed authoring capabilities, it
acceptable to have no mapping of source resource(s) to the
namespace. In fact, preventing access to the source resource(s)
desirable security benefits. However, if remote editing of
source resource(s) is desired, the source resource(s) should be
a location in the URI namespace. This source location should not
one of the locations at which the generated output is retrievable
since in general it is impossible for the server to
requests for source resources from requests for process
resources. There is often a many-to-many relationship between
resources and output resources
On WebDAV compliant servers the URI of the source resource(s) may
stored in a link on the output resource with type DAV:source (
section 13.10 for a description of the source link property).
Storing the source URIs in links on the output resources places
burden of discovering the source on the authoring client. Note
the value of a source link is not guaranteed to point to the
source. Source links may break or incorrect values may be entered
Also note that not all servers will allow the client to set
source link value. For example a server which generates source
on the fly for its CGI files will most likely not allow a client
set the source link value
6
The ability to lock a resource provides a mechanism for
access to that resource. Using a lock, an authoring client
provide a reasonable guarantee that another principal will not
a resource while it is being edited. In this way, a client
prevent the "lost update" problem
This specification allows locks to vary over two client-
parameters, the number of principals involved (exclusive vs. shared
and the type of access to be granted. This document defines
for only one access type, write. However, the syntax is extensible
and permits the eventual specification of locking for other
types
6.1 Exclusive Vs. Shared
The most basic form of lock is an exclusive lock. This is a
where the access right in question is only granted to a
principal. The need for this arbitration results from a desire
avoid having to merge results
Goland, et al. Standards Track [Page 14]
RFC 2518 WEBDAV February 1999
However, there are times when the goal of a lock is not to
others from exercising an access right but rather to provide
mechanism for principals to indicate that they intend to
their access rights. Shared locks are provided for this case.
shared lock allows multiple principals to receive a lock. Hence
principal with appropriate access can get the lock
With shared locks there are two trust sets that affect a resource
The first trust set is created by access permissions. Principals
are trusted, for example, may have permission to write to
resource. Among those who have access permission to write to
resource, the set of principals who have taken out a shared lock
must trust each other, creating a (typically) smaller trust
within the access permission write set
Starting with every possible principal on the Internet, in
situations the vast majority of these principals will not have
access to a given resource. Of the small number who do have
access, some principals may decide to guarantee their edits are
from overwrite conflicts by using exclusive write locks. Others
decide they trust their collaborators will not overwrite their
(the potential set of collaborators being the set of principals
have write permission) and use a shared lock, which informs
collaborators that a principal may be working on the resource
The WebDAV extensions to HTTP do not need to provide all of
communications paths necessary for principals to coordinate
activities. When using shared locks, principals may use any out
band communication channel to coordinate their work (e.g., face-to
face interaction, written notes, post-it notes on the screen
telephone conversation, Email, etc.) The intent of a shared lock
to let collaborators know who else may be working on a resource
Shared locks are included because experience from web
authoring systems has indicated that exclusive locks are often
rigid. An exclusive lock is used to enforce a particular
process: take out an exclusive lock, read the resource,
edits, write the resource, release the lock. This editing
has the problem that locks are not always properly released,
example when a program crashes, or when a lock owner leaves
unlocking a resource. While both timeouts and administrative
can be used to remove an offending lock, neither mechanism may
available when needed; the timeout may be long or the
may not be available
Goland, et al. Standards Track [Page 15]
RFC 2518 WEBDAV February 1999
6.2 Required
A WebDAV compliant server is not required to support locking in
form. If the server does support locking it may choose to
any combination of exclusive and shared locks for any access types
The reason for this flexibility is that locking policy strikes to
very heart of the resource management and versioning systems
by various storage repositories. These repositories require
over what sort of locking will be made available. For example,
repositories only support shared write locks while others
provide support for exclusive write locks while yet others use
locking at all. As each system is sufficiently different to
exclusion of certain locking features, this specification
locking as the sole axis of negotiation within WebDAV
6.3 Lock
A lock token is a type of state token, represented as a URI,
identifies a particular lock. A lock token is returned by
successful LOCK operation in the lockdiscovery property in
response body, and can also be found through lock discovery on
resource
Lock token URIs MUST be unique across all resources for all time
This uniqueness constraint allows lock tokens to be submitted
resources and servers without fear of confusion
This specification provides a lock token URI scheme
opaquelocktoken that meets the uniqueness requirements.
resources are free to return any URI scheme so long as it meets
uniqueness requirements
Having a lock token provides no special access rights. Anyone
find out anyone else's lock token by performing lock discovery
Locks MUST be enforced based upon whatever authentication
is used by the server, not based on the secrecy of the token values
6.4 opaquelocktoken Lock Token URI
The opaquelocktoken URI scheme is designed to be unique across
resources for all time. Due to this uniqueness quality, a client
submit an opaque lock token in an If header on a resource other
the one that returned it
All resources MUST recognize the opaquelocktoken scheme and,
minimum, recognize that the lock token does not refer to
outstanding lock on the resource
Goland, et al. Standards Track [Page 16]
RFC 2518 WEBDAV February 1999
In order to guarantee uniqueness across all resources for all
the opaquelocktoken requires the use of the Universal
Identifier (UUID) mechanism, as described in [ISO-11578].
Opaquelocktoken generators, however, have a choice of how they
these tokens. They can either generate a new UUID for every
token they create or they can create a single UUID and then
extension characters. If the second method is selected then
program generating the extensions MUST guarantee that the
extension will never be used twice with the associated UUID
OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] ; The
production is the string representation of a UUID, as defined
[ISO-11578]. Note that white space (LWS) is not allowed
elements of this production
Extension = path ; path is defined in section 3.2.1 of RFC 2068
[RFC2068]
6.4.1 Node Field Generation Without the IEEE 802
UUIDs, as defined in [ISO-11578], contain a "node" field
contains one of the IEEE 802 addresses for the server machine.
noted in section 17.8, there are several security risks
with exposing a machine's IEEE 802 address. This section provides
alternate mechanism for generating the "node" field of a UUID
does not employ an IEEE 802 address. WebDAV servers MAY use
algorithm for creating the node field when generating UUIDs.
text in this section is originally from an Internet-Draft by
Leach and Rich Salz, who are noted here to properly attribute
work
The ideal solution is to obtain a 47 bit cryptographic quality
number, and use it as the low 47 bits of the node ID, with the
significant bit of the first octet of the node ID set to 1. This
is the unicast/multicast bit, which will never be set in IEEE 802
addresses obtained from network cards; hence, there can never be
conflict between UUIDs generated by machines with and without
cards
If a system does not have a primitive to generate
quality random numbers, then in most systems there are usually
fairly large number of sources of randomness available from which
can be generated. Such sources are system specific, but
include
Goland, et al. Standards Track [Page 17]
RFC 2518 WEBDAV February 1999
- the percent of memory in
- the size of main memory in
- the amount of free main memory in
- the size of the paging or swap file in
- free bytes of paging or swap
- the total size of user virtual address space in
- the total available user address space
- the size of boot disk drive in
- the free disk space on boot drive in
- the current
- the amount of time since the system
- the individual sizes of files in various system
- the creation, last read, and modification times of files
various system
- the utilization factors of various system resources (heap, etc.)
- current mouse cursor
- current caret
- current number of running processes,
- handles or IDs of the desktop window and the active
- the value of stack pointer of the
- the process and thread ID of
- various processor architecture specific performance
(instructions executed, cache misses, TLB misses
(Note that it is precisely the above kinds of sources of
that are used to seed cryptographic quality random number
on systems without special hardware for their construction.)
In addition, items such as the computer's name and the name of
operating system, while not strictly speaking random, will
differentiate the results from those obtained by other systems
The exact algorithm to generate a node ID using these data is
specific, because both the data available and the functions to
them are often very system specific. However, assuming that one
concatenate all the values from the randomness sources into a buffer
and that a cryptographic hash function such as MD5 is available,
any 6 bytes of the MD5 hash of the buffer, with the multicast
(the high bit of the first byte) set will be an appropriately
node ID
Other hash functions, such as SHA-1, can also be used. The
requirement is that the result be suitably random _ in the sense
the outputs from a set uniformly distributed inputs are
uniformly distributed, and that a single bit change in the input
be expected to cause half of the output bits to change
Goland, et al. Standards Track [Page 18]
RFC 2518 WEBDAV February 1999
6.5 Lock Capability
Since server lock support is optional, a client trying to lock
resource on a server can either try the lock and hope for the best
or perform some form of discovery to determine what lock
the server supports. This is known as lock capability discovery
Lock capability discovery differs from discovery of supported
control types, since there may be access control types
corresponding lock types. A client can determine what lock types
server supports by retrieving the supportedlock property
Any DAV compliant resource that supports the LOCK method MUST
the supportedlock property
6.6 Active Lock
If another principal locks a resource that a principal wishes
access, it is useful for the second principal to be able to find
who the first principal is. For this purpose the
property is provided. This property lists all outstanding locks
describes their type, and where available, provides their lock token
Any DAV compliant resource that supports the LOCK method MUST
the lockdiscovery property
6.7 Usage
Although the locking mechanisms specified here provide some help
preventing lost updates, they cannot guarantee that updates
never be lost. Consider the following scenario
Two clients A and B are interested in editing the resource '
index.html'. Client A is an HTTP client rather than a WebDAV client
and so does not know how to perform locking
Client A doesn't lock the document, but does a GET and
editing
Client B does LOCK, performs a GET and begins editing
Client B finishes editing, performs a PUT, then an UNLOCK
Client A performs a PUT, overwriting and losing all of B's changes
There are several reasons why the WebDAV protocol itself
prevent this situation. First, it cannot force all clients to
locking because it must be compatible with HTTP clients that do
comprehend locking. Second, it cannot require servers to
locking because of the variety of repository implementations, some
which rely on reservations and merging rather than on locking
Finally, being stateless, it cannot enforce a sequence of
like LOCK / GET / PUT / UNLOCK
Goland, et al. Standards Track [Page 19]
RFC 2518 WEBDAV February 1999
WebDAV servers that support locking can reduce the likelihood
clients will accidentally overwrite each other's changes by
clients to lock resources before modifying them. Such servers
effectively prevent HTTP 1.0 and HTTP 1.1 clients from
resources
WebDAV clients can be good citizens by using a lock / retrieve /
write /unlock sequence of operations (at least by default)
they interact with a WebDAV server that supports locking
HTTP 1.1 clients can be good citizens, avoiding overwriting
clients' changes, by using entity tags in If-Match headers with
requests that would modify resources
Information managers may attempt to prevent overwrites
implementing client-side procedures requiring locking
modifying WebDAV resources
7 Write
This section describes the semantics specific to the write lock type
The write lock is a specific instance of a lock type, and is the
lock type described in this specification
7.1 Methods Restricted by Write
A write lock MUST prevent a principal without the lock
successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE
DELETE, or MKCOL on the locked resource. All other current methods
GET in particular, function independently of the lock
Note, however, that as new methods are created it will be
to specify how they interact with a write lock
7.2 Write Locks and Lock
A successful request for an exclusive or shared write lock
result in the generation of a unique lock token associated with
requesting principal. Thus if five principals have a shared
lock on the same resource there will be five lock tokens, one
each principal
7.3 Write Locks and
While those without a write lock may not alter a property on
resource it is still possible for the values of live properties
change, even while locked, due to the requirements of their schemas
Goland, et al. Standards Track [Page 20]
RFC 2518 WEBDAV February 1999
Only dead properties and live properties defined to respect locks
guaranteed not to change while write locked
7.4 Write Locks and Null
It is possible to assert a write lock on a null resource in order
lock the name
A write locked null resource, referred to as a lock-null resource
MUST respond with a 404 (Not Found) or 405 (Method Not Allowed)
any HTTP/1.1 or DAV methods except for PUT, MKCOL, OPTIONS, PROPFIND
LOCK, and UNLOCK. A lock-null resource MUST appear as a member
its parent collection. Additionally the lock-null resource MUST
defined on it all mandatory DAV properties. Most of
properties, such as all the get* properties, will have no value as
lock-null resource does not support the GET method. Lock-
resources MUST have defined values for lockdiscovery
supportedlock properties
Until a method such as PUT or MKCOL is successfully executed on
lock-null resource the resource MUST stay in the lock-null state
However, once a PUT or MKCOL is successfully executed on a lock-
resource the resource ceases to be in the lock-null state
If the resource is unlocked, for any reason, without a PUT, MKCOL,
similar method having been successfully executed upon it then
resource MUST return to the null state
7.5 Write Locks and
A write lock on a collection, whether created by a "Depth: 0"
"Depth: infinity" lock request, prevents the addition or removal
member URIs of the collection by non-lock owners. As a consequence
when a principal issues a PUT or POST request to create a
resource under a URI which needs to be an internal member of a
locked collection to maintain HTTP namespace consistency, or issues
DELETE to remove a resource which has a URI which is an
internal member URI of a write locked collection, this request
fail if the principal does not have a write lock on the collection
However, if a write lock request is issued to a collection
member URIs identifying resources that are currently locked in
manner which conflicts with the write lock, the request MUST
with a 423 (Locked) status code
If a lock owner causes the URI of a resource to be added as
internal member URI of a locked collection then the new resource
be automatically added to the lock. This is the only mechanism
Goland, et al. Standards Track [Page 21]
RFC 2518 WEBDAV February 1999
allows a resource to be added to a write lock. Thus, for example,
the collection /a/b/ is write locked and the resource /c is moved
/a/b/c then resource /a/b/c will be added to the write lock
7.6 Write Locks and the If Request
If a user agent is not required to have knowledge about a lock
requesting an operation on a locked resource, the following
might occur. Program A, run by User A, takes out a write lock on
resource. Program B, also run by User A, has no knowledge of
lock taken out by Program A, yet performs a PUT to the
resource. In this scenario, the PUT succeeds because locks
associated with a principal, not a program, and thus program B
because it is acting with principal A's credential, is allowed
perform the PUT. However, had program B known about the lock,
would not have overwritten the resource, preferring instead
present a dialog box describing the conflict to the user. Due
this scenario, a mechanism is needed to prevent different
from accidentally ignoring locks taken out by other programs with
same authorization
In order to prevent these collisions a lock token MUST be
by an authorized principal in the If header for all locked
that a method may interact with or the method MUST fail.
example, if a resource is to be moved and both the source
destination are locked then two lock tokens must be submitted,
for the source and the other for the destination
7.6.1 Example - Write
>>
COPY /~fielding/index.html HTTP/1.1
Host: www.ics.uci.
Destination: http://www.ics.uci.edu/users/f/fielding/index.
If:
()
>>
HTTP/1.1 204 No
In this example, even though both the source and destination
locked, only one lock token must be submitted, for the lock on
destination. This is because the source resource is not modified
a COPY, and hence unaffected by the write lock. In this example,
agent authentication has previously occurred via a mechanism
the scope of the HTTP protocol, in the underlying transport layer
Goland, et al. Standards Track [Page 22]
RFC 2518 WEBDAV February 1999
7.7 Write Locks and COPY/
A COPY method invocation MUST NOT duplicate any write locks active
the source. However, as previously noted, if the COPY copies
resource into a collection that is locked with "Depth: infinity",
then the resource will be added to the lock
A successful MOVE request on a write locked resource MUST NOT
the write lock with the resource. However, the resource is subject
being added to an existing lock at the destination, as specified
section 7.5. For example, if the MOVE makes the resource a child of
collection that is locked with "Depth: infinity", then the
will be added to that collection's lock. Additionally, if a
locked with "Depth: infinity" is moved to a destination that
within the scope of the same lock (e.g., within the namespace
covered by the lock), the moved resource will again be a added to
lock. In both these examples, as specified in section 7.6, an
header must be submitted containing a lock token for both the
and destination
7.8 Refreshing Write
A client MUST NOT submit the same write lock request twice.
that a client is always aware it is resubmitting the same
request because it must include the lock token in the If header
order to make the request for a resource that is already locked
However, a client may submit a LOCK method with an If header
without a body. This form of LOCK MUST only be used to "refresh"
lock. Meaning, at minimum, that any timers associated with the
MUST be re-set
A server may return a Timeout header with a lock refresh that
different than the Timeout header returned when the lock
originally requested. Additionally clients may submit
headers of arbitrary value with their lock refresh requests
Servers, as always, may ignore Timeout headers submitted by
client
If an error is received in response to a refresh LOCK request
client SHOULD assume that the lock was not refreshed
8 HTTP Methods for Distributed
The following new HTTP methods use XML as a request and
format. All DAV compliant clients and resources MUST use XML
that are compliant with [REC-XML]. All XML used in either
or responses MUST be, at minimum, well formed. If a server
Goland, et al. Standards Track [Page 23]
RFC 2518 WEBDAV February 1999
ill-formed XML in a request it MUST reject the entire request with
400 (Bad Request). If a client receives ill-formed XML in a
then it MUST NOT assume anything about the outcome of the
method and SHOULD treat the server as malfunctioning
8.1
The PROPFIND method retrieves properties defined on the
identified by the Request-URI, if the resource does not have
internal members, or on the resource identified by the Request-
and potentially its member resources, if the resource is a
that has internal member URIs. All DAV compliant resources
support the PROPFIND method and the propfind XML element (
12.14) along with all XML elements defined for use with that element
A client may submit a Depth header with a value of "0", "1",
"infinity" with a PROPFIND on a collection resource with
member URIs. DAV compliant servers MUST support the "0", "1"
"infinity" behaviors. By default, the PROPFIND method without a
header MUST act as if a "Depth: infinity" header was included
A client may submit a propfind XML element in the body of the
method describing what information is being requested. It
possible to request particular property values, all property values
or a list of the names of the resource's properties. A client
choose not to submit a request body. An empty PROPFIND request
MUST be treated as a request for the names and values of
properties
All servers MUST support returning a response of content
text/xml or application/xml that contains a multistatus XML
that describes the results of the attempts to retrieve the
properties
If there is an error retrieving a property then a proper error
MUST be included in the response. A request to retrieve the value
a property which does not exist is an error and MUST be noted, if
response uses a multistatus XML element, with a response XML
which contains a 404 (Not Found) status value
Consequently, the multistatus XML element for a collection
with member URIs MUST include a response XML element for each
URI of the collection, to whatever depth was requested. Each
XML element MUST contain an href XML element that gives the URI
the resource on which the properties in the prop XML element
defined. Results for a PROPFIND on a collection resource
internal member URIs are returned as a flat list whose order
entries is not significant
Goland, et al. Standards Track [Page 24]
RFC 2518 WEBDAV February 1999
In the case of allprop and propname, if a principal does not have
right to know whether a particular property exists then the
should be silently excluded from the response
The results of this method SHOULD NOT be cached
8.1.1 Example - Retrieving Named
>>
PROPFIND /file HTTP/1.1
Host: www.foo.
Content-type: text/xml; charset="utf-8"
Content-Length:
encoding="utf-8" ?>
>>
HTTP/1.1 207 Multi-
Content-Type: text/xml; charset="utf-8"
Content-Length:
encoding="utf-8" ?>
response
http://www.foo.bar/file
Box type A
J.J. Johnson
HTTP/1.1 200 OK
Goland, et al. Standards Track [Page 25]
RFC 2518 WEBDAV February 1999
HTTP/1.1 403 Forbidden
The user does not have access
the DingALing property
response
There has been an access violation error
In this example, PROPFIND is executed on a non-collection
http://www.foo.bar/file. The propfind XML element specifies the
of four properties whose values are being requested. In this
only two properties were returned, since the principal issuing
request did not have sufficient access rights to see the third
fourth properties
8.1.2 Example - Using allprop to Retrieve All
>>
PROPFIND /container/ HTTP/1.1
Host: www.foo.
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length:
encoding="utf-8" ?>
>>
HTTP/1.1 207 Multi-
Content-Type: text/xml; charset="utf-8"
Content-Length:
encoding="utf-8" ?>
response
http://www.foo.bar/container/
Box type A
Goland, et al. Standards Track [Page 26]
RFC 2518 WEBDAV February 1999
Hadrian
1997-12-01T17:42:21-08:00
Example
collection/>
HTTP/1.1 200 OK
response
response
http://www.foo.bar/container/front.html
Box type B
1997-12-01T18:27:21-08:00
Example HTML
4525
text/
