tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 4918


HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

Part 2 of 5, p. 17 to 44
Prev RFC Part       Next RFC Part


prevText      Top      Up      ToC       Page 17 
6.  Locking

   The ability to lock a resource provides a mechanism for serializing
   access to that resource.  Using a lock, an authoring client can
   provide a reasonable guarantee that another principal will not modify
   a resource while it is being edited.  In this way, a client can
   prevent the "lost update" problem.

   This specification allows locks to vary over two client-specified
   parameters, the number of principals involved (exclusive vs. shared)
   and the type of access to be granted.  This document defines locking
   for only one access type, write.  However, the syntax is extensible,
   and permits the eventual specification of locking for other access

Top      Up      ToC       Page 18 
6.1.  Lock Model

   This section provides a concise model for how locking behaves.  Later
   sections will provide more detail on some of the concepts and refer
   back to these model statements.  Normative statements related to LOCK
   and UNLOCK method handling can be found in the sections on those
   methods, whereas normative statements that cover any method are
   gathered here.

   1.  A lock either directly or indirectly locks a resource.

   2.  A resource becomes directly locked when a LOCK request to a URL
       of that resource creates a new lock.  The "lock-root" of the new
       lock is that URL.  If at the time of the request, the URL is not
       mapped to a resource, a new empty resource is created and
       directly locked.

   3.  An exclusive lock (Section 6.2) conflicts with any other kind of
       lock on the same resource, whether either lock is direct or
       indirect.  A server MUST NOT create conflicting locks on a

   4.  For a collection that is locked with a depth-infinity lock L, all
       member resources are indirectly locked.  Changes in membership of
       such a collection affect the set of indirectly locked resources:

       *  If a member resource is added to the collection, the new
          member resource MUST NOT already have a conflicting lock,
          because the new resource MUST become indirectly locked by L.

       *  If a member resource stops being a member of the collection,
          then the resource MUST no longer be indirectly locked by L.

   5.  Each lock is identified by a single globally unique lock token
       (Section 6.5).

   6.  An UNLOCK request deletes the lock with the specified lock token.
       After a lock is deleted, no resource is locked by that lock.

   7.  A lock token is "submitted" in a request when it appears in an
       "If" header (Section 7, "Write Lock", discusses when token
       submission is required for write locks).

   8.  If a request causes the lock-root of any lock to become an
       unmapped URL, then the lock MUST also be deleted by that request.

Top      Up      ToC       Page 19 
6.2.  Exclusive vs. Shared Locks

   The most basic form of lock is an exclusive lock.  Exclusive locks
   avoid having to deal with content change conflicts, without requiring
   any coordination other than the methods described in this

   However, there are times when the goal of a lock is not to exclude
   others from exercising an access right but rather to provide a
   mechanism for principals to indicate that they intend to exercise
   their access rights.  Shared locks are provided for this case.  A
   shared lock allows multiple principals to receive a lock.  Hence any
   principal that has both access privileges and a valid lock can use
   the locked resource.

   With shared locks, there are two trust sets that affect a resource.
   The first trust set is created by access permissions.  Principals who
   are trusted, for example, may have permission to write to the
   resource.  Among those who have access permission to write to the
   resource, the set of principals who have taken out a shared lock also
   must trust each other, creating a (typically) smaller trust set
   within the access permission write set.

   Starting with every possible principal on the Internet, in most
   situations the vast majority of these principals will not have write
   access to a given resource.  Of the small number who do have write
   access, some principals may decide to guarantee their edits are free
   from overwrite conflicts by using exclusive write locks.  Others may
   decide they trust their collaborators will not overwrite their work
   (the potential set of collaborators being the set of principals who
   have write permission) and use a shared lock, which informs their
   collaborators that a principal may be working on the resource.

   The WebDAV extensions to HTTP do not need to provide all of the
   communications paths necessary for principals to coordinate their
   activities.  When using shared locks, principals may use any out-of-
   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 is
   to let collaborators know who else may be working on a resource.

   Shared locks are included because experience from Web-distributed
   authoring systems has indicated that exclusive locks are often too
   rigid.  An exclusive lock is used to enforce a particular editing
   process: take out an exclusive lock, read the resource, perform
   edits, write the resource, release the lock.  This editing process
   has the problem that locks are not always properly released, for
   example, when a program crashes or when a lock creator leaves without

Top      Up      ToC       Page 20 
   unlocking a resource.  While both timeouts (Section 6.6) and
   administrative action can be used to remove an offending lock,
   neither mechanism may be available when needed; the timeout may be
   long or the administrator may not be available.

   A successful request for a new shared lock MUST result in the
   generation of a unique lock associated with the requesting principal.
   Thus, if five principals have taken out shared write locks on the
   same resource, there will be five locks and five lock tokens, one for
   each principal.

6.3.  Required Support

   A WebDAV-compliant resource is not required to support locking in any
   form.  If the resource does support locking, it may choose to support
   any combination of exclusive and shared locks for any access types.

   The reason for this flexibility is that locking policy strikes to the
   very heart of the resource management and versioning systems employed
   by various storage repositories.  These repositories require control
   over what sort of locking will be made available.  For example, some
   repositories only support shared write locks, while others only
   provide support for exclusive write locks, while yet others use no
   locking at all.  As each system is sufficiently different to merit
   exclusion of certain locking features, this specification leaves
   locking as the sole axis of negotiation within WebDAV.

6.4.  Lock Creator and Privileges

   The creator of a lock has special privileges to use the lock to
   modify the resource.  When a locked resource is modified, a server
   MUST check that the authenticated principal matches the lock creator
   (in addition to checking for valid lock token submission).

   The server MAY allow privileged users other than the lock creator to
   destroy a lock (for example, the resource owner or an administrator).
   The 'unlock' privilege in [RFC3744] was defined to provide that

   There is no requirement for servers to accept LOCK requests from all
   users or from anonymous users.

   Note that having a lock does not confer full privilege to modify the
   locked resource.  Write access and other privileges MUST be enforced
   through normal privilege or authentication mechanisms, not based on
   the possible obscurity of lock token values.

Top      Up      ToC       Page 21 
6.5.  Lock Tokens

   A lock token is a type of state token that identifies a particular
   lock.  Each lock has exactly one unique lock token generated by the
   server.  Clients MUST NOT attempt to interpret lock tokens in any

   Lock token URIs MUST be unique across all resources for all time.
   This uniqueness constraint allows lock tokens to be submitted across
   resources and servers without fear of confusion.  Since lock tokens
   are unique, a client MAY submit a lock token in an If header on a
   resource other than the one that returned it.

   When a LOCK operation creates a new lock, the new lock token is
   returned in the Lock-Token response header defined in Section 10.5,
   and also in the body of the response.

   Servers MAY make lock tokens publicly readable (e.g., in the DAV:
   lockdiscovery property).  One use case for making lock tokens
   readable is so that a long-lived lock can be removed by the resource
   owner (the client that obtained the lock might have crashed or
   disconnected before cleaning up the lock).  Except for the case of
   using UNLOCK under user guidance, a client SHOULD NOT use a lock
   token created by another client instance.

   This specification encourages servers to create Universally Unique
   Identifiers (UUIDs) for lock tokens, and to use the URI form defined
   by "A Universally Unique Identifier (UUID) URN Namespace"
   ([RFC4122]).  However, servers are free to use any URI (e.g., from
   another scheme) so long as it meets the uniqueness requirements.  For
   example, a valid lock token might be constructed using the
   "opaquelocktoken" scheme defined in Appendix C.

   Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"

6.6.  Lock Timeout

   A lock MAY have a limited lifetime.  The lifetime is suggested by the
   client when creating or refreshing the lock, but the server
   ultimately chooses the timeout value.  Timeout is measured in seconds
   remaining until lock expiration.

   The timeout counter MUST be restarted if a refresh lock request is
   successful (see Section 9.10.2).  The timeout counter SHOULD NOT be
   restarted at any other time.

   If the timeout expires, then the lock SHOULD be removed.  In this
   case the server SHOULD act as if an UNLOCK method was executed by the

Top      Up      ToC       Page 22 
   server on the resource using the lock token of the timed-out lock,
   performed with its override authority.

   Servers are advised to pay close attention to the values submitted by
   clients, as they will be indicative of the type of activity the
   client intends to perform.  For example, an applet running in a
   browser may need to lock a resource, but because of the instability
   of the environment within which the applet is running, the applet may
   be turned off without warning.  As a result, the applet is likely to
   ask for a relatively small timeout value so that if the applet dies,
   the lock can be quickly harvested.  However, a document management
   system is likely to ask for an extremely long timeout because its
   user may be planning on going offline.

   A client MUST NOT assume that just because the timeout has expired,
   the lock has immediately been removed.

   Likewise, a client MUST NOT assume that just because the timeout has
   not expired, the lock still exists.  Clients MUST assume that locks
   can arbitrarily disappear at any time, regardless of the value given
   in the Timeout header.  The Timeout header only indicates the
   behavior of the server if extraordinary circumstances do not occur.
   For example, a sufficiently privileged user may remove a lock at any
   time, or the system may crash in such a way that it loses the record
   of the lock's existence.

6.7.  Lock Capability Discovery

   Since server lock support is optional, a client trying to lock a
   resource on a server can either try the lock and hope for the best,
   or perform some form of discovery to determine what lock capabilities
   the server supports.  This is known as lock capability discovery.  A
   client can determine what lock types the server supports by
   retrieving the DAV:supportedlock property.

   Any DAV-compliant resource that supports the LOCK method MUST support
   the DAV:supportedlock property.

6.8.  Active Lock Discovery

   If another principal locks a resource that a principal wishes to
   access, it is useful for the second principal to be able to find out
   who the first principal is.  For this purpose the DAV:lockdiscovery
   property is provided.  This property lists all outstanding locks,
   describes their type, and MAY even provide the lock tokens.

   Any DAV-compliant resource that supports the LOCK method MUST support
   the DAV:lockdiscovery property.

Top      Up      ToC       Page 23 
7.  Write Lock

   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 only
   lock type described in this specification.

   An exclusive write lock protects a resource: it prevents changes by
   any principal other than the lock creator and in any case where the
   lock token is not submitted (e.g., by a client process other than the
   one holding the lock).

   Clients MUST submit a lock-token they are authorized to use in any
   request that modifies a write-locked resource.  The list of
   modifications covered by a write-lock include:

   1.  A change to any of the following aspects of any write-locked

       *  any variant,

       *  any dead property,

       *  any live property that is lockable (a live property is
          lockable unless otherwise defined.)

   2.  For collections, any modification of an internal member URI.  An
       internal member URI of a collection is considered to be modified
       if it is added, removed, or identifies a different resource.
       More discussion on write locks and collections is found in
       Section 7.4.

   3.  A modification of the mapping of the root of the write lock,
       either to another resource or to no resource (e.g., DELETE).

   Of the methods defined in HTTP and WebDAV, PUT, POST, PROPPATCH,
   LOCK, UNLOCK, MOVE, COPY (for the destination resource), DELETE, and
   MKCOL are affected by write locks.  All other HTTP/WebDAV methods
   defined so far -- GET in particular -- function independently of a
   write lock.

   The next few sections describe in more specific terms how write locks
   interact with various operations.

Top      Up      ToC       Page 24 
7.1.  Write Locks and Properties

   While those without a write lock may not alter a property on a
   resource it is still possible for the values of live properties to
   change, even while locked, due to the requirements of their schemas.
   Only dead properties and live properties defined as lockable are
   guaranteed not to change while write locked.

7.2.  Avoiding Lost Updates

   Although the write locks provide some help in preventing lost
   updates, they cannot guarantee that updates will 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 begins

   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 cannot
   prevent this situation.  First, it cannot force all clients to use
   locking because it must be compatible with HTTP clients that do not
   comprehend locking.  Second, it cannot require servers to support
   locking because of the variety of repository implementations, some of
   which rely on reservations and merging rather than on locking.
   Finally, being stateless, it cannot enforce a sequence of operations
   like LOCK / GET / PUT / UNLOCK.

   WebDAV servers that support locking can reduce the likelihood that
   clients will accidentally overwrite each other's changes by requiring
   clients to lock resources before modifying them.  Such servers would
   effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying

   WebDAV clients can be good citizens by using a lock / retrieve /
   write /unlock sequence of operations (at least by default) whenever
   they interact with a WebDAV server that supports locking.

Top      Up      ToC       Page 25 
   HTTP 1.1 clients can be good citizens, avoiding overwriting other
   clients' changes, by using entity tags in If-Match headers with any
   requests that would modify resources.

   Information managers may attempt to prevent overwrites by
   implementing client-side procedures requiring locking before
   modifying WebDAV resources.

7.3.  Write Locks and Unmapped URLs

   WebDAV provides the ability to send a LOCK request to an unmapped URL
   in order to reserve the name for use.  This is a simple way to avoid
   the lost-update problem on the creation of a new resource (another
   way is to use If-None-Match header specified in Section 14.26 of
   [RFC2616]).  It has the side benefit of locking the new resource
   immediately for use of the creator.

   Note that the lost-update problem is not an issue for collections
   because MKCOL can only be used to create a collection, not to
   overwrite an existing collection.  When trying to lock a collection
   upon creation, clients can attempt to increase the likelihood of
   getting the lock by pipelining the MKCOL and LOCK requests together
   (but because this doesn't convert two separate operations into one
   atomic operation, there's no guarantee this will work).

   A successful lock request to an unmapped URL MUST result in the
   creation of a locked (non-collection) resource with empty content.
   Subsequently, a successful PUT request (with the correct lock token)
   provides the content for the resource.  Note that the LOCK request
   has no mechanism for the client to provide Content-Type or Content-
   Language, thus the server will use defaults or empty values and rely
   on the subsequent PUT request for correct values.

   A resource created with a LOCK is empty but otherwise behaves in
   every way as a normal resource.  It behaves the same way as a
   resource created by a PUT request with an empty body (and where a
   Content-Type and Content-Language was not specified), followed by a
   LOCK request to the same resource.  Following from this model, a
   locked empty resource:

   o  Can be read, deleted, moved, and copied, and in all ways behaves
      as a regular non-collection resource.

   o  Appears as a member of its parent collection.

   o  SHOULD NOT disappear when its lock goes away (clients must
      therefore be responsible for cleaning up their own mess, as with
      any other operation or any non-empty resource).

Top      Up      ToC       Page 26 
   o  MAY NOT have values for properties like DAV:getcontentlanguage
      that haven't been specified yet by the client.

   o  Can be updated (have content added) with a PUT request.

   o  MUST NOT be converted into a collection.  The server MUST fail a
      MKCOL request (as it would with a MKCOL request to any existing
      non-collection resource).

   o  MUST have defined values for DAV:lockdiscovery and DAV:
      supportedlock properties.

   o  The response MUST indicate that a resource was created, by use of
      the "201 Created" response code (a LOCK request to an existing
      resource instead will result in 200 OK).  The body must still
      include the DAV:lockdiscovery property, as with a LOCK request to
      an existing resource.

   The client is expected to update the locked empty resource shortly
   after locking it, using PUT and possibly PROPPATCH.

   Alternatively and for backwards compatibility to [RFC2518], servers
   MAY implement Lock-Null Resources (LNRs) instead (see definition in
   Appendix D).  Clients can easily interoperate both with servers that
   support the old model LNRs and the recommended model of "locked empty
   resources" by only attempting PUT after a LOCK to an unmapped URL,
   not MKCOL or GET, and by not relying on specific properties of LNRs.

7.4.  Write Locks and Collections

   There are two kinds of collection write locks.  A depth-0 write lock
   on a collection protects the collection properties plus the internal
   member URLs of that one collection, while not protecting the content
   or properties of member resources (if the collection itself has any
   entity bodies, those are also protected).  A depth-infinity write
   lock on a collection provides the same protection on that collection
   and also provides write lock protection on every member resource.

   Expressed otherwise, a write lock of either kind protects any request
   that would create a new resource in a write locked collection, any
   request that would remove an internal member URL of a write locked
   collection, and any request that would change the segment name of any
   internal member.

   Thus, a collection write lock protects all the following actions:

   o  DELETE a collection's direct internal member,

Top      Up      ToC       Page 27 
   o  MOVE an internal member out of the collection,

   o  MOVE an internal member into the collection,

   o  MOVE to rename an internal member within a collection,

   o  COPY an internal member into a collection, and

   o  PUT or MKCOL request that would create a new internal member.

   The collection's lock token is required in addition to the lock token
   on the internal member itself, if it is locked separately.

   In addition, a depth-infinity lock affects all write operations to
   all members of the locked collection.  With a depth-infinity lock,
   the resource identified by the root of the lock is directly locked,
   and all its members are indirectly locked.

   o  Any new resource added as a descendant of a depth-infinity locked
      collection becomes indirectly locked.

   o  Any indirectly locked resource moved out of the locked collection
      into an unlocked collection is thereafter unlocked.

   o  Any indirectly locked resource moved out of a locked source
      collection into a depth-infinity locked target collection remains
      indirectly locked but is now protected by the lock on the target
      collection (the target collection's lock token will thereafter be
      required to make further changes).

   If a depth-infinity write LOCK request is issued to a collection
   containing member URLs identifying resources that are currently
   locked in a manner that conflicts with the new lock (see Section 6.1,
   point 3), the request MUST fail with a 423 (Locked) status code, and
   the response SHOULD contain the 'no-conflicting-lock' precondition.

   If a lock request causes the URL of a resource to be added as an
   internal member URL of a depth-infinity locked collection, then the
   new resource MUST be automatically protected by the lock.  For
   example, if the collection /a/b/ is write locked and the resource /c
   is moved to /a/b/c, then resource /a/b/c will be added to the write

Top      Up      ToC       Page 28 
7.5.  Write Locks and the If Request Header

   A user agent has to demonstrate knowledge of a lock when requesting
   an operation on a locked resource.  Otherwise, the following scenario
   might occur.  In the scenario, program A, run by User A, takes out a
   write lock on a resource.  Program B, also run by User A, has no
   knowledge of the lock taken out by program A, yet performs a PUT to
   the locked resource.  In this scenario, the PUT succeeds because
   locks are associated with a principal, not a program, and thus
   program B, because it is acting with principal A's credential, is
   allowed to perform the PUT.  However, had program B known about the
   lock, it would not have overwritten the resource, preferring instead
   to present a dialog box describing the conflict to the user.  Due to
   this scenario, a mechanism is needed to prevent different programs
   from accidentally ignoring locks taken out by other programs with the
   same authorization.

   In order to prevent these collisions, a lock token MUST be submitted
   by an authorized principal for all locked resources that a method may
   change or the method MUST fail.  A lock token is submitted when it
   appears in an If header.  For example, if a resource is to be moved
   and both the source and destination are locked, then two lock tokens
   must be submitted in the If header, one for the source and the other
   for the destination.

7.5.1.  Example - Write Lock and COPY


     COPY /~fielding/index.html HTTP/1.1
     If: <>


     HTTP/1.1 204 No Content

   In this example, even though both the source and destination are
   locked, only one lock token must be submitted (the one for the lock
   on the destination).  This is because the source resource is not
   modified by a COPY, and hence unaffected by the write lock.  In this
   example, user agent authentication has previously occurred via a
   mechanism outside the scope of the HTTP protocol, in the underlying
   transport layer.

Top      Up      ToC       Page 29 
7.5.2.  Example - Deleting a Member of a Locked Collection

   Consider a collection "/locked" with an exclusive, depth-infinity
   write lock, and an attempt to delete an internal member "/locked/


     DELETE /locked/member HTTP/1.1


     HTTP/1.1 423 Locked
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:error xmlns:D="DAV:">

   Thus, the client would need to submit the lock token with the request
   to make it succeed.  To do that, various forms of the If header (see
   Section 10.4) could be used.

   "No-Tag-List" format:

     If: (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)

   "Tagged-List" format, for "":

     If: <>

   "Tagged-List" format, for "":

     If: <>

   Note that, for the purpose of submitting the lock token, the actual
   form doesn't matter; what's relevant is that the lock token appears
   in the If header, and that the If header itself evaluates to true.

Top      Up      ToC       Page 30 
7.6.  Write Locks and COPY/MOVE

   A COPY method invocation MUST NOT duplicate any write locks active on
   the source.  However, as previously noted, if the COPY copies the
   resource into a collection that is locked with a depth-infinity lock,
   then the resource will be added to the lock.

   A successful MOVE request on a write locked resource MUST NOT move
   the write lock with the resource.  However, if there is an existing
   lock at the destination, the server MUST add the moved resource to
   the destination lock scope.  For example, if the MOVE makes the
   resource a child of a collection that has a depth-infinity lock, then
   the resource will be added to that collection's lock.  Additionally,
   if a resource with a depth-infinity lock is moved to a destination
   that is within the scope of the same lock (e.g., within the URL
   namespace tree covered by the lock), the moved resource will again be
   added to the lock.  In both these examples, as specified in
   Section 7.5, an If header must be submitted containing a lock token
   for both the source and destination.

7.7.  Refreshing Write Locks

   A client MUST NOT submit the same write lock request twice.  Note
   that a client is always aware it is resubmitting the same lock
   request because it must include the lock token in the If header in
   order to make the request for a resource that is already locked.

   However, a client may submit a LOCK request with an If header but
   without a body.  A server receiving a LOCK request with no body MUST
   NOT create a new lock -- this form of the LOCK request is only to be
   used to "refresh" an existing lock (meaning, at minimum, that any
   timers associated with the lock MUST be reset).

   Clients may submit Timeout headers of arbitrary value with their lock
   refresh requests.  Servers, as always, may ignore Timeout headers
   submitted by the client, and a server MAY refresh a lock with a
   timeout period that is different than the previous timeout period
   used for the lock, provided it advertises the new value in the LOCK
   refresh response.

   If an error is received in response to a refresh LOCK request, the
   client MUST NOT assume that the lock was refreshed.

Top      Up      ToC       Page 31 
8.  General Request and Response Handling

8.1.  Precedence in Error Handling

   Servers MUST return authorization errors in preference to other
   errors.  This avoids leaking information about protected resources
   (e.g., a client that finds that a hidden resource exists by seeing a
   423 Locked response to an anonymous request to the resource).

8.2.  Use of XML

   In HTTP/1.1, method parameter information was exclusively encoded in
   HTTP headers.  Unlike HTTP/1.1, WebDAV encodes method parameter
   information either in an XML ([REC-XML]) request entity body, or in
   an HTTP header.  The use of XML to encode method parameters was
   motivated by the ability to add extra XML elements to existing
   structures, providing extensibility; and by XML's ability to encode
   information in ISO 10646 character sets, providing
   internationalization support.

   In addition to encoding method parameters, XML is used in WebDAV to
   encode the responses from methods, providing the extensibility and
   internationalization advantages of XML for method output, as well as

   When XML is used for a request or response body, the Content-Type
   type SHOULD be application/xml.  Implementations MUST accept both
   text/xml and application/xml in request and response bodies.  Use of
   text/xml is deprecated.

   All DAV-compliant clients and resources MUST use XML parsers that are
   compliant with [REC-XML] and [REC-XML-NAMES].  All XML used in either
   requests or responses MUST be, at minimum, well formed and use
   namespaces correctly.  If a server receives XML that is not well-
   formed, then the server MUST reject the entire request with a 400
   (Bad Request).  If a client receives XML that is not well-formed in a
   response, then the client MUST NOT assume anything about the outcome
   of the executed method and SHOULD treat the server as malfunctioning.

   Note that processing XML submitted by an untrusted source may cause
   risks connected to privacy, security, and service quality (see
   Section 20).  Servers MAY reject questionable requests (even though
   they consist of well-formed XML), for instance, with a 400 (Bad
   Request) status code and an optional response body explaining the

Top      Up      ToC       Page 32 
8.3.  URL Handling

   URLs appear in many places in requests and responses.
   Interoperability experience with [RFC2518] showed that many clients
   parsing Multi-Status responses did not fully implement the full
   Reference Resolution defined in Section 5 of [RFC3986].  Thus,
   servers in particular need to be careful in handling URLs in
   responses, to ensure that clients have enough context to be able to
   interpret all the URLs.  The rules in this section apply not only to
   resource URLs in the 'href' element in Multi-Status responses, but
   also to the Destination and If header resource URLs.

   The sender has a choice between two approaches: using a relative
   reference, which is resolved against the Request-URI, or a full URI.
   A server MUST ensure that every 'href' value within a Multi-Status
   response uses the same format.

   WebDAV only uses one form of relative reference in its extensions,
   the absolute path.

      Simple-ref = absolute-URI | ( path-absolute [ "?" query ] )

   The absolute-URI, path-absolute and query productions are defined in
   Sections 4.3, 3.3, and 3.4 of [RFC3986].

   Within Simple-ref productions, senders MUST NOT:

   o  use dot-segments ("." or ".."), or

   o  have prefixes that do not match the Request-URI (using the
      comparison rules defined in Section 3.2.3 of [RFC2616]).

   Identifiers for collections SHOULD end in a '/' character.

8.3.1.  Example - Correct URL Handling

   Consider the collection with the internal
   member URL and the PROPFIND
   request below:


     PROPFIND /sample/ HTTP/1.1
     Depth: 1

Top      Up      ToC       Page 33 
   In this case, the server should return two 'href' elements containing

   o  '' and
      '', or

   o  '/sample/' and '/sample/a%20test'

   Note that even though the server may be storing the member resource
   internally as 'a test', it has to be percent-encoded when used inside
   a URI reference (see Section 2.1 of [RFC3986]).  Also note that a
   legal URI may still contain characters that need to be escaped within
   XML character data, such as the ampersand character.

8.4.  Required Bodies in Requests

   Some of these new methods do not define bodies.  Servers MUST examine
   all requests for a body, even when a body was not expected.  In cases
   where a request body is present but would be ignored by a server, the
   server MUST reject the request with 415 (Unsupported Media Type).
   This informs the client (which may have been attempting to use an
   extension) that the body could not be processed as the client

8.5.  HTTP Headers for Use in WebDAV

   HTTP defines many headers that can be used in WebDAV requests and
   responses.  Not all of these are appropriate in all situations and
   some interactions may be undefined.  Note that HTTP 1.1 requires the
   Date header in all responses if possible (see Section 14.18,

   The server MUST do authorization checks before checking any HTTP
   conditional header.

8.6.  ETag

   HTTP 1.1 recommends the use of ETags rather than modification dates,
   for cache control, and there are even stronger reasons to prefer
   ETags for authoring.  Correct use of ETags is even more important in
   a distributed authoring environment, because ETags are necessary
   along with locks to avoid the lost-update problem.  A client might
   fail to renew a lock, for example, when the lock times out and the
   client is accidentally offline or in the middle of a long upload.
   When a client fails to renew the lock, it's quite possible the
   resource can still be relocked and the user can go on editing, as
   long as no changes were made in the meantime.  ETags are required for
   the client to be able to distinguish this case.  Otherwise, the

Top      Up      ToC       Page 34 
   client is forced to ask the user whether to overwrite the resource on
   the server without even being able to tell the user if it has
   changed.  Timestamps do not solve this problem nearly as well as

   Strong ETags are much more useful for authoring use cases than weak
   ETags (see Section 13.3.3 of [RFC2616]).  Semantic equivalence can be
   a useful concept but that depends on the document type and the
   application type, and interoperability might require some agreement
   or standard outside the scope of this specification and HTTP.  Note
   also that weak ETags have certain restrictions in HTTP, e.g., these
   cannot be used in If-Match headers.

   Note that the meaning of an ETag in a PUT response is not clearly
   defined either in this document or in RFC 2616 (i.e., whether the
   ETag means that the resource is octet-for-octet equivalent to the
   body of the PUT request, or whether the server could have made minor
   changes in the formatting or content of the document upon storage).
   This is an HTTP issue, not purely a WebDAV issue.

   Because clients may be forced to prompt users or throw away changed
   content if the ETag changes, a WebDAV server SHOULD NOT change the
   ETag (or the Last-Modified time) for a resource that has an unchanged
   body and location.  The ETag represents the state of the body or
   contents of the resource.  There is no similar way to tell if
   properties have changed.

8.7.  Including Error Response Bodies

   HTTP and WebDAV did not use the bodies of most error responses for
   machine-parsable information until the specification for Versioning
   Extensions to WebDAV introduced a mechanism to include more specific
   information in the body of an error response (Section 1.6 of
   [RFC3253]).  The error body mechanism is appropriate to use with any
   error response that may take a body but does not already have a body
   defined.  The mechanism is particularly appropriate when a status
   code can mean many things (for example, 400 Bad Request can mean
   required headers are missing, headers are incorrectly formatted, or
   much more).  This error body mechanism is covered in Section 16.

8.8.  Impact of Namespace Operations on Cache Validators

   Note that the HTTP response headers "Etag" and "Last-Modified" (see
   [RFC2616], Sections 14.19 and 14.29) are defined per URL (not per
   resource), and are used by clients for caching.  Therefore servers
   must ensure that executing any operation that affects the URL
   namespace (such as COPY, MOVE, DELETE, PUT, or MKCOL) does preserve
   their semantics, in particular:

Top      Up      ToC       Page 35 
   o  For any given URL, the "Last-Modified" value MUST increment every
      time the representation returned upon GET changes (within the
      limits of timestamp resolution).

   o  For any given URL, an "ETag" value MUST NOT be reused for
      different representations returned by GET.

   In practice this means that servers

   o  might have to increment "Last-Modified" timestamps for every
      resource inside the destination namespace of a namespace operation
      unless it can do so more selectively, and

   o  similarly, might have to re-assign "ETag" values for these
      resources (unless the server allocates entity tags in a way so
      that they are unique across the whole URL namespace managed by the

   Note that these considerations also apply to specific use cases, such
   as using PUT to create a new resource at a URL that has been mapped
   before, but has been deleted since then.

   Finally, WebDAV properties (such as DAV:getetag and DAV:
   getlastmodified) that inherit their semantics from HTTP headers must
   behave accordingly.

9.  HTTP Methods for Distributed Authoring

9.1.  PROPFIND Method

   The PROPFIND method retrieves properties defined on the resource
   identified by the Request-URI, if the resource does not have any
   internal members, or on the resource identified by the Request-URI
   and potentially its member resources, if the resource is a collection
   that has internal member URLs.  All DAV-compliant resources MUST
   support the PROPFIND method and the propfind XML element
   (Section 14.20) along with all XML elements defined for use with that

   A client MUST submit a Depth header with a value of "0", "1", or
   "infinity" with a PROPFIND request.  Servers MUST support "0" and "1"
   depth requests on WebDAV-compliant resources and SHOULD support
   "infinity" requests.  In practice, support for infinite-depth
   requests MAY be disabled, due to the performance and security
   concerns associated with this behavior.  Servers SHOULD treat a
   request without a Depth header as if a "Depth: infinity" header was

Top      Up      ToC       Page 36 
   A client may submit a 'propfind' XML element in the body of the
   request method describing what information is being requested.  It is
   possible to:

   o  Request particular property values, by naming the properties
      desired within the 'prop' element (the ordering of properties in
      here MAY be ignored by the server),

   o  Request property values for those properties defined in this
      specification (at a minimum) plus dead properties, by using the
      'allprop' element (the 'include' element can be used with
      'allprop' to instruct the server to also include additional live
      properties that may not have been returned otherwise),

   o  Request a list of names of all the properties defined on the
      resource, by using the 'propname' element.

   A client may choose not to submit a request body.  An empty PROPFIND
   request body MUST be treated as if it were an 'allprop' request.

   Note that 'allprop' does not return values for all live properties.
   WebDAV servers increasingly have expensively-calculated or lengthy
   properties (see [RFC3253] and [RFC3744]) and do not return all
   properties already.  Instead, WebDAV clients can use propname
   requests to discover what live properties exist, and request named
   properties when retrieving values.  For a live property defined
   elsewhere, that definition can specify whether or not that live
   property would be returned in 'allprop' requests.

   All servers MUST support returning a response of content type text/
   xml or application/xml that contains a multistatus XML element that
   describes the results of the attempts to retrieve the various

   If there is an error retrieving a property, then a proper error
   result MUST be included in the response.  A request to retrieve the
   value of a property that does not exist is an error and MUST be noted
   with a 'response' XML element that contains a 404 (Not Found) status

   Consequently, the 'multistatus' XML element for a collection resource
   MUST include a 'response' XML element for each member URL of the
   collection, to whatever depth was requested.  It SHOULD NOT include
   any 'response' elements for resources that are not WebDAV-compliant.
   Each 'response' element MUST contain an 'href' element that contains
   the URL of the resource on which the properties in the prop XML
   element are defined.  Results for a PROPFIND on a collection resource
   are returned as a flat list whose order of entries is not

Top      Up      ToC       Page 37 
   significant.  Note that a resource may have only one value for a
   property of a given name, so the property may only show up once in
   PROPFIND responses.

   Properties may be subject to access control.  In the case of
   'allprop' and 'propname' requests, if a principal does not have the
   right to know whether a particular property exists, then the property
   MAY be silently excluded from the response.

   Some PROPFIND results MAY be cached, with care, as there is no cache
   validation mechanism for most properties.  This method is both safe
   and idempotent (see Section 9.1 of [RFC2616]).

9.1.1.  PROPFIND Status Codes

   This section, as with similar sections for other methods, provides
   some guidance on error codes and preconditions or postconditions
   (defined in Section 16) that might be particularly useful with

   403 Forbidden - A server MAY reject PROPFIND requests on collections
   with depth header of "Infinity", in which case it SHOULD use this
   error with the precondition code 'propfind-finite-depth' inside the
   error body.

9.1.2.  Status Codes for Use in 'propstat' Element

   In PROPFIND responses, information about individual properties is
   returned inside 'propstat' elements (see Section 14.22), each
   containing an individual 'status' element containing information
   about the properties appearing in it.  The list below summarizes the
   most common status codes used inside 'propstat'; however, clients
   should be prepared to handle other 2/3/4/5xx series status codes as

   200 OK - A property exists and/or its value is successfully returned.

   401 Unauthorized - The property cannot be viewed without appropriate

   403 Forbidden - The property cannot be viewed regardless of

   404 Not Found - The property does not exist.

Top      Up      ToC       Page 38 
9.1.3.  Example - Retrieving Named Properties


     PROPFIND /file HTTP/1.1
     Content-type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:propfind xmlns:D="DAV:">
       <D:prop xmlns:R="">


     HTTP/1.1 207 Multi-Status
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:multistatus xmlns:D="DAV:">
       <D:response xmlns:R="">
               <R:BoxType>Box type A</R:BoxType>
               <R:Name>J.J. Johnson</R:Name>
           <D:status>HTTP/1.1 200 OK</D:status>
           <D:status>HTTP/1.1 403 Forbidden</D:status>
           <D:responsedescription> The user does not have access to the
      DingALing property.

Top      Up      ToC       Page 39 
       <D:responsedescription> There has been an access violation error.

   In this example, PROPFIND is executed on a non-collection resource  The propfind XML element specifies the
   name of four properties whose values are being requested.  In this
   case, only two properties were returned, since the principal issuing
   the request did not have sufficient access rights to see the third
   and fourth properties.

9.1.4.  Example - Using 'propname' to Retrieve All Property Names


     PROPFIND /container/ HTTP/1.1
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <propfind xmlns="DAV:">


     HTTP/1.1 207 Multi-Status
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <multistatus xmlns="DAV:">
           <prop xmlns:R="">
           <status>HTTP/1.1 200 OK</status>

Top      Up      ToC       Page 40 
           <prop xmlns:R="">
           <status>HTTP/1.1 200 OK</status>

   In this example, PROPFIND is invoked on the collection resource, with a propfind XML element
   containing the propname XML element, meaning the name of all
   properties should be returned.  Since no Depth header is present, it
   assumes its default value of "infinity", meaning the name of the
   properties on the collection and all its descendants should be

   Consistent with the previous example, resource has six properties defined on it:
   bigbox and author in the ""
   namespace, and creationdate, displayname, resourcetype, and
   supportedlock in the "DAV:" namespace.

   The resource, a member of
   the "container" collection, has nine properties defined on it, bigbox
   in the "" namespace and creationdate,
   displayname, getcontentlength, getcontenttype, getetag,
   getlastmodified, resourcetype, and supportedlock in the "DAV:"

   This example also demonstrates the use of XML namespace scoping and
   the default namespace.  Since the "xmlns" attribute does not contain
   a prefix, the namespace applies by default to all enclosed elements.
   Hence, all elements that do not explicitly state the namespace to
   which they belong are members of the "DAV:" namespace.

Top      Up      ToC       Page 41 
9.1.5.  Example - Using So-called 'allprop'

   Note that 'allprop', despite its name, which remains for backward-
   compatibility, does not return every property, but only dead
   properties and the live properties defined in this specification.


     PROPFIND /container/ HTTP/1.1
     Depth: 1
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:propfind xmlns:D="DAV:">


     HTTP/1.1 207 Multi-Status
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:multistatus xmlns:D="DAV:">
           <D:prop xmlns:R="">
             <R:bigbox><R:BoxType>Box type A</R:BoxType></R:bigbox>
             <D:displayname>Example collection</D:displayname>

Top      Up      ToC       Page 42 
           <D:status>HTTP/1.1 200 OK</D:status>
           <D:prop xmlns:R="">
             <R:bigbox><R:BoxType>Box type B</R:BoxType>
             <D:displayname>Example HTML resource</D:displayname>
               >Mon, 12 Jan 1998 09:25:56 GMT</D:getlastmodified>
           <D:status>HTTP/1.1 200 OK</D:status>

   In this example, PROPFIND was invoked on the resource with a Depth header of 1, meaning
   the request applies to the resource and its children, and a propfind
   XML element containing the allprop XML element, meaning the request
   should return the name and value of all the dead properties defined
   on the resources, plus the name and value of all the properties
   defined in this specification.  This example illustrates the use of
   relative references in the 'href' elements of the response.

   The resource has six properties
   defined on it: 'bigbox' and 'author in the
   "" namespace, DAV:creationdate, DAV:
   displayname, DAV:resourcetype, and DAV:supportedlock.

Top      Up      ToC       Page 43 
   The last four properties are WebDAV-specific, defined in Section 15.
   Since GET is not supported on this resource, the get* properties
   (e.g., DAV:getcontentlength) are not defined on this resource.  The
   WebDAV-specific properties assert that "container" was created on
   December 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
   (DAV:creationdate), has a name of "Example collection" (DAV:
   displayname), a collection resource type (DAV:resourcetype), and
   supports exclusive write and shared write locks (DAV:supportedlock).

   The resource has nine
   properties defined on it:

   'bigbox' in the "" namespace (another
   instance of the "bigbox" property type), DAV:creationdate, DAV:
   displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
   DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.

   The DAV-specific properties assert that "front.html" was created on
   December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
   (DAV:creationdate), has a name of "Example HTML resource" (DAV:
   displayname), a content length of 4525 bytes (DAV:getcontentlength),
   a MIME type of "text/html" (DAV:getcontenttype), an entity tag of
   "zzyzx" (DAV:getetag), was last modified on Monday, January 12, 1998,
   at 09:25:56 GMT (DAV:getlastmodified), has an empty resource type,
   meaning that it is not a collection (DAV:resourcetype), and supports
   both exclusive write and shared write locks (DAV:supportedlock).

9.1.6.  Example - Using 'allprop' with 'include'


     PROPFIND /mycol/ HTTP/1.1
     Depth: 1
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:propfind xmlns:D="DAV:">

Top      Up      ToC       Page 44 
   In this example, PROPFIND is executed on the resource and its internal member resources.  The
   client requests the values of all live properties defined in this
   specification, plus all dead properties, plus two more live
   properties defined in [RFC3253].  The response is not shown.

(page 44 continued on part 3)

Next RFC Part