Extensions for Distributed Authoring and Versioning on the World Wide Web -- WEBDAV

It would seem best to implement a flat property namespace, inducing a natural isomorphism between DAV and most native file systems. Adopting such a model will not restrict RDBS from taking full advantage of their search facilities.

However, it seems that future trends might be toward hierarchical properties. Therefore, DAV requirements [Slein et al.] stipulate that the design of the flat property system MUST be such that it will be possible to add true hierarchical properties later without breaking downlevel clients. Specifically, a flat client MUST be able to speak to a hierarchical server and a hierarchical client MUST be able to speak to a flat server. Worst case either way MUST be that the request fails.

2.2.2.3 Property Names

The URI framework provides a mechanism to prevent namespace collision and for varying degrees of administrative control. Rather than reinvent these desirable features, DAV properties make use of them by requiring that all DAV property names MUST be URIs. Since a property is also an XML element, the name of the XML element is a URI.

The property namespace is flat, that is, it is not possible to string together a series of property names in order to refer to a hierarchy of properties. Thus it is possible to refer to a property B but not a property A/B, where is also a property defined on the resource.

Finally, it is not possible to define the same property twice as this would cause a collision in the resource's property namespace.

2.3 Schemas

Schema discovery is used to determine if a system supports a group of properties or XML elements. A property does not necessarily contain sufficient information to identify any schema(s) to which it may belong.

As with property names, schemas MUST use URIs as their names.

A resource declares its support for a schema by defining a property whose name is the same as the schema's. The property SHOULD contain the PropSchema XML element.

2.3.1 PropSchema XML Element

Name: http://www.ietf.org/standards/dav/PropSchema
Purpose: To provide information about properties
Schema: http://www.ietf.org/standards/dav/
Parent: Any
Values: [DTD] [DefinedProps]
Description:This property contains the definition of the schema. This definition consists of two parts. A DTD element that contains a DTD that declares all XML elements and DefinedProps that defines any properties associated with the schema. As with all XML it is possible to add extra XML elements. Therefore schemas may define extra XML elements which are to be included with their values.

2.3.2 DTD XML Element

Name: http://www.ietf.org/standards/dav/DTD
Purpose: To contain the DTD for XML elements associated with the schema.
Schema: http://www.ietf.org/standards/dav/
Parent: Any
Values: XML Declaration statements

2.3.3 DefinedProps XML Element

Name: http://www.ietf.org/standards/dav/DefinedProps
Purpose: To contain a list of properties defined by the schema.
Schema: http://www.ietf.org/standards/dav/
Parent: Any
Values: 1*PropEntries

2.3.4 PropEntries XML Element

Name: http://www.ietf.org/standards/dav/PropEntries
Purpose: To contain the name of a defined property, the DTD of its value, and its live/dead status.
Schema: http://www.ietf.org/standards/dav/
Parent: DefinedProps
Values: Prop [DTD] [Live]
Description:Prop contains the name of the property. The DTD contains the DTD of the property's value. Live, if defined, indicates that the property has semantics and syntax that are enforced by the server.

2.3.5 Live XML Element

Name: http://www.ietf.org/standards/dav/Live
Purpose: If present this indicates the server MUST enforce the syntax and semantics of the property.
Schema: http://www.ietf.org/standards/dav/
Parent: PropEntries

2.4 DAV Schema

2.4.1 DAV Property

2.4.2 Level XML Element

2.4.3 Prop XML element

2.4.4 PropLoc XML Attribute

2.4.5 Example

<?XML:Namespace href="http://www.ietf.org/standards/dav/" AS="D"/>
<?XML:Namespace href="AIIM:Dublin:" AS="A"/>
<D:Prop>
     <A:Author
         D:PropLoc="http://www.foo.com/resource/props/Author">
          Larry Masinter
     </A:Author>
</D:Prop>

The previous specifies that the property author exists on some unspecified resource and that the property can be directly referenced at http://www.foo.com/resource/props/Author. The resource upon which the property is defined must be determined from context.

2.5 Property Identifiers

2.5.1 Problem Definition

A server is free to assign whatever URI it chooses to identify an instance of a property defined on a resource. In fact, a server is free not to reveal the URI of an instance of a particular resource and instead require that the client access the property through PROPFIND and PROPPATCH. However, many servers will want to allow clients to directly manipulate properties. On these servers, a client can discover the URI of an instance of a property by performing a PROPFIND and examining the PropLoc attribute, if returned, of each property.

2.6 Link XML Element

2.6.1 Problem Description

2.6.2 Solution Requirements

2.6.3 Link XML Element

2.6.4 Src XML Element

2.6.5 Dst XML Element

2.6.6 Example

<?XML:Namespace
     href = "http://www.ietf.org/standards/dav/" AS = "D"/>
<?XML:Namespace
     href = "http://www.foocorp.com/Project/" AS = "F"/>
<D:Prop>
     <Source>
          <Link>
               <F:ProjFiles>Source</F:ProjFiles>
               <src>http://foo.bar/program</src>
               <dst>http://foo.bar/src/main.c</dst>
          </Link>
          <Link>
               <F:ProjFiles>Library</F:ProjFiles>
               <src>http://foo.bar/program</src>
               <dst>http://foo.bar/src/main.lib</dst>
          </Link>
          <Link>
               <F:ProjFiles>Makefile</F:ProjFiles>
               <src>http://foo.bar/program</src>
               <dst>http://foo.bar/src/makefile</dst>
     <Link>
     </Source>
</D:Prop>

In this example the resource http://foo.bar/program has a source property defined which contains three links. Each link contains three elements, two of which, src and dst, are part of the DAV schema defined in this document, and one which is defined by the schema http://www.foocorp.com/project/ (Source, Library, and Makefile). A client which only implements the elements in the DAV spec will not understand the foocorp elements and will ignore them, thus seeing the expected source and destination links. An enhanced client may know about the foocorp elements and be able to present the user with additional information about the links.

2.7 Multi-Status Response

2.7.1 Problem Definition

2.7.2 Solution Requirements

2.7.3 Multi-Status Response

2.7.3.1 MultiResponse

2.7.3.2 Response

2.7.3.3 Status

2.7.3.4 ResponseDescription

2.8 Properties and Methods

2.8.1 DELETE

2.8.2 GET

2.8.2.1 Example

GET /bar.html;prop=z39.50_authors HTTP/1.1
Host: foo.com

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: xxxx
E-tag: "1234"
Last-Modified: xxxx

<?XML:Namespace
     href = "http://www.ietf.org/standards/dav/" AS = "D"/>
<?XML:Namespace
     href = "http://www.w3.com/standards/z39.50/"AS = "Z"/>
<D:prop>
     <Z:Authors>
          <Z:Author>Jane Doe</Z:Author>
          <Z:Author>Joe Doe</Z:Author>
           <Z:Author>Lots o'Doe</Z:Author>
     </Z:Authors>
</D:prop>

2.8.3 PROPPATCH

All DAV compliant servers MUST process instructions which are specified using the PropertyUpdate, Create, and Remove XML elements of the DAV schema. The request message body MUST contain at least one PropertyUpdate XML element. Instruction processing MUST occur in the order instructions are received (i.e., from top to bottom), and MUST be performed atomically.

2.8.3.1 PropertyUpdate XML element

2.8.3.2 Create XML element

2.8.3.3 Remove XML element

2.8.3.4 Response

2.8.3.5 Response Codes

2.8.3.6 Example

PROPPATCH /bar.html HTTP/1.1
Host: www.foo.com
Content-Type: text/xml
Content-Length: xxxx

<?XML:Namespace
     href = "http://www.ietf.org/standards/dav/" AS = "D"/>
<?XML:Namespace
     href = "http://www.w3.com/standards/z39.50/" AS = "Z"/>
<D:PropertyUpdate>
     <Create>
          <prop>
               <Z:authors>
                    <Z:Author>Jim Whitehead</Z:Author>
                    <Z:Author>Roy Fielding</Z:Author>
               </Z:authors>
          </Prop>
     </Create>
     <Remove>
          <prop><Z:Copyright-Owner/></prop>
     </Remove>
</D:PropertyUpdate>

HTTP/1.1 405 Conflict
Content-Type: text/xml
Content-Length: xxxxx

<?XML:Namespace
     href="http://www.ietf.org/standards/dav/" AS = "D"/>
<?XML:Namespace
     href="http://www.w3.com/standards/z39.50/" AS = "Z"/>
<D:MultiResponse>
     <ResponseDescription> Copyright Owner can not be deleted or
altered.</ResponseDescription>
     <Response>
          <Prop><Z:authors/></Prop>
          <Status>HTTP/1.1 418 Atomicity Failure</Status>
     </Response>
     <Response>
          <Prop><Z:Copyright-Owner/></Prop>
          <Status>HTTP/1.1 405 Conflict</Status>
     </Response>
</D:MultiResponse>

2.8.4 PUT

2.8.5 PROPFIND

The response is a text/xml message body that contains a MultiResponse XML element which describes the results of the attempts to retrieve the various properties. If a property was successfully retrieved then its value MUST be returned in the prop XML element. In the case of Allprop and Findprop, if a principal does not have the right to know if a particular property exists, an error MUST NOT be returned. The results of this method SHOULD NOT be cached.

2.8.5.1 Propfind XML element

2.8.5.2 Allprop

2.8.5.3 Propname

2.8.5.4 PropFindResult XML element

2.8.5.5 Example 1 - Prop

PROPFIND  /container/ HTTP/1.1
Host: www.foo.bar
Content-Length: xxxx
Content-Type: text/xml

<?XML:Namespace href =
     "http://www.ietf.org/standards/dav/" AS = "G"/>
<?XML:Namespace href =
     "http://www.foo.bar/boxschema/" AS = "B"/>
<G:PROPFIND>
     <prop>
          <B:bigbox>
          <B:author>
          <B:DingALing>
          <B:Random>
     </prop>
</G:PROPFIND>

HTTP/1.1 207 Partial Success
Content-Type: text/xml
Content-Length: xxxxx

<?XML:Namespace
     href ="http://www.ietf.org/standards/dav/" AS = "S">
<?XML:Namespace href = "http://www.foo.bar/boxschema" AS = R">
<D:MultiResponse>
     <ResponseDescription> There has been an access violation
error. </ResponseDescription>
     <Response>
          <Prop>
               <R:bigbox D:Proploc="http://prop.com/BoxType">
                    <BoxType>Box type A</BoxType>
               </R:bigbox>
               <R:author D:Proploc="http://prop.com/Author">
                    <Name>J.J. Dingleheimerschmidt</Name>
               </R:author>
          </Prop>
          <Status>HTTP/1.1 200 Success</Status>
</Response>
     <Response>
          <Prop><R:DingALing/><R:Random/></>
          <Status>HTTP/1.1 403 Forbidden</Status>
          <ResponseDescription> The user does not have access to
the DingALink property. </ResponseDescription>
     </Response>
</D:MultiResponse>

The result will return all properties on the container. In this case only two properties were found. The principal did not have sufficient access rights to see the third and fourth properties so an error was returned.

2.8.5.6 Example 2 - Allprop

PROPFIND  /container/ HTTP/1.1
Host: www.foo.bar
Content-Length: xxxx
Content-Type: text/xml

<?XML:Namespace href =
     "http://www.ietf.org/standards/dav/" AS = "G"/>
<G:PROPFIND>
     <Allprop/>
</G:PROPFIND>

HTTP/1.1 200 Success
Content-Type: text/xml
Content-Length: xxxxx

<?XML:Namespace href =
     "http://www.ietf.org/standards/dav/" As = "S">
<?XML:Namespace href = "http://www.foo.bar/boxschema" AS = R">
<S:MultiResponse>
     <Prop>
          <R:bigbox D:Proploc="http://prop.com/BigBox">
               <BoxType>Box type A</BoxType>
          </R:bigbox>
          <R:author D:Proploc="http://prop.com/Author">
               <Name>Hadrian</Name>
          </R:author>
     </Prop>
     <Status>HTTP/1.1 200 Success</Status>
</S:MultiResponse>

This particular client only had the right to see two properties, BoxType and Author. No error is returned for the remaining properties, as the client does not even have sufficient rights to know they exist. If the client did have the right to know they existed but did not have the right to see their value, a 201 Partial Success with a multiresponse, as used in the previous example, would have been returned.

2.8.5.7 Example 3 - Propname

PROPFIND  /container/ HTTP/1.1
Host: www.foo.bar
Content-Length: xxxx
Content-Type: text/xml

<?XML:Namespace
     href = "http://www.ietf.org/standards/dav/" AS = "G"/>
<G:PROPFIND>
     <Propname/>
</G:PROPFIND>

HTTP/1.1 200 Success
Content-Type: text/xml
Content-Length: xxxxx

<?XML:Namespace
     href = "http://www.ietf.org/standards/dav/" As = "S">
<?XML:Namespace
     href = "http://www.foo.bar/boxschema" AS = "R">
<S:MultiResponse>
     <Prop>
          <R:bigbox D:Proploc="http://prop.com/BigBox"/>
          <R:author D:Proploc="http://prop.com/Author"/>
          <R:DingALing/>
          <R:Random/>
     </Prop>
     <Status>HTTP/1.1 200 Success</Status>
</S:MultiResponse>

3 A Proposal for Collections of Web Resources and Name Space Operations

3.1 Observations on the HTTP Object Model

3.1.1 Collection Resources

3.1.2 Creation and Retrieval of Collection Resources

3.1.2.1 Example

3.1.3 Source Resources and Output Resources

3.2 MKCOL Method

3.2.1 Problem Description

3.2.2 Solution Requirements

3.2.3 Request

3.2.3.1 MKCOL Without Request Body

3.2.3.2 MKCOL With Request Body

3.2.4 Response

3.2.5 Example

     MKCOL /webdisc/xfiles/ HTTP/1.1
     Host: www.server.org

     HTTP/1.1 201 Created

3.3 Standard DAV Properties

3.3.1 IsCollection Property

3.3.2 DisplayName Property

3.3.3 CreationDate3 Property

3.3.4 GETentity Property5

3.3.5 INDEXentity Property

3.3.6 Content-Type XML Element

3.3.7 Content-Length XML Element

3.3.8 Content-Language XML Element

3.3.9 Last-Modified XML Element

3.3.10 Etag XML Element

3.4 INDEX Method

3.4.1 Problem Description

3.4.2 Solution Requirements

3.4.3 The Request

For a collection, INDEX MUST return a list of its members. All WebDAV compliant resources MUST support the text/xml response entity described below. The INDEX result for a collection MAY also return a list of the members of child collections, to any depth.

Collections that respond to an INDEX method with a text/xml entity MUST contain only one ResInfo element. This ResInfo element contains an Href element, which gives the identifier(s) of the resource, a Prop element, which gives selected properties of the resource, and a Members element, which contains a ResInfo element for each member of the collection. The Prop element MUST contain at least the following properties, if they are defined and available: DisplayName, IsCollection, CreationDate, GETentity, and INDEXentity.

The response from INDEX is cacheable, and SHOULD be accompanied by an ETag header (see section 13.3.4 of RFC 2068). If GET and INDEX return different entities for the same resource state, they MUST return different entity tags.

3.4.4 The Response

3.4.5 ResInfo XML Element

3.4.6 Members XML Element

3.4.7 Href XML Element

3.4.8 Example

INDEX /user/yarong/dav_drafts/ HTTP/1.1
Host: www.microsoft.com

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: xxx
Last-Modified: Thu, 11 Sep 1997 23:45:12 GMT
ETag: "fooyyybar"

<?XML:Namespace
     href = "http://www.ietf.org/standards/dav/" as = "D"/>
<D:ResInfo>
     <XML:Href>
          http://www.microsoft.com/user/yarong/dav_drafts/
     </XML:Href>
     <Prop>
        <DisplayName>
          WebDAV working drafts directory
        </DisplayName>
        <IsCollection>true</IsCollection>
        <CreationDate>19970418T070304Z</CreationDate>
        <GETentity>
          <Content-Type>text/html</Content-Type>
          <Content-Length>2754</Content-Length>
          <Content-Language>en</Content-Language>
          <Last-Modified>
               Fri, 22 Aug 1997 10:11:26 GMT
          </Last-Modified>
          <Etag>"8675309"</Etag>
        </GETentity>
        <INDEXentity>
          <Content-Type>text/xml</Content-Type>
          <Content-Length>xxx</Content-Length>
          <Last-Modified>
               Thu, 11 Sep 1997 23:45:12 GMT
          </Last-Modified>
          <Etag>"fooyyybar"</Etag>
        </INDEXentity>
     </Prop>

     <Members>
        <ResInfo>
          <XML:Href>
          http://www.microsoft.com/user/yarong/dav_drafts/base
          </XML:Href>
          <Prop>
             <IsCollection
     D:PropLoc="http://www.microsoft.com/user/yarong/dav_drafts/b
     ase;props=IsCollection">
               False
             </IsCollection>
             <DisplayName>
               WebDAV Name Space Operations Draft
             </DisplayName>
             <Creation-Date>19970320T230525Z</Creation-Date>
             <GETentity>
               <Content-Type>application/msword</Content-Type>
               <Content-Length>1400</Content-Length>
               <Content-Language>en</Content-Language>
               <Last-Modified>
                    Fri, 22 Aug 1997 18:22:56 GMT
               </Last-Modified>
               <Etag>"8675309"</Etag>
             </GETentity>
          </Prop>
        </ResInfo>
     </Members>
</D:ResInfo>

This example shows the result of the INDEX method applied to the collection resource http://www.microsoft.com/user/yarong/dav_drafts/. It returns a response body in XML format, which gives information about the container and its sole member, http://www.microsoft.com/user/yarong/dav_drafts/base. The entry on the collection confirms that resource the INDEX was executed on is a collection. The result also contains the URI of the IsCollection property on the member resource.

3.5 Behavior of RFC 2068 Methods on Collections

3.5.1 GET, HEAD for Collections

3.5.2 POST for Collections

3.5.3 PUT for Collections

3.5.3.1 PUT for Non-Collection Resources

3.5.4 DELETE for Collections

3.5.5 DELETE Method for Non-Collection Resources

3.6 COPY Method

3.6.1 Problem Description

3.6.2 Solution Requirements

3.6.3 The Request

3.6.3.1 COPY for HTTP/1.1 resources

3.6.3.2 COPY for Properties

3.6.3.3 COPY for Collections

3.6.3.4 Type Interactions

3.6.4 The Response

3.6.5 Examples

3.6.5.1 Overwrite Example

COPY /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/users/f/fielding/index.html

HTTP/1.1 200 OK

3.6.5.2 No Overwrite Example

COPY /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/users/f/fielding/index.html
Overwrite: "false"

HTTP/1.1 412 Precondition Failed

3.7 MOVE Method

3.7.1 Problem Description

3.7.2 Solution Requirements

3.7.3 The Request

3.7.4 The Response

3.7.5 Examples

3.7.5.1 Overwrite Example

MOVE /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu
Destination: http://www.ics.uci.edu/users/f/fielding/index.html

HTTP/1.1 200 OK
Content-Location:
http://www.ics.uci.edu/users/f/fielding/index.html

3.8 ADDREF Method

3.8.1 Problem Definition

3.8.2 Solution Requirements

3.8.3 The Request

3.8.4 Example

ADDREF /~whitehead/dav/ HTTP/1.1
HOST: www.ics.udi.edu
Collection-Member: http://www.ietf.org/standards/dav/

HTTP/1.1 200 OK

3.9 DELREF Method

3.9.1 Problem Definition

3.9.2 Solution Requirements

3.9.3 The Request

3.9.4 Example

DELREF /~whitehead/dav/ HTTP/1.1
Host: www.ics.udi.edu
Collection-Member: http://www.ietf.org/standards/dav/

HTTP/1.1 200 OK

3.10 PATCH Method

3.10.1 Problem Definition

3.10.2 Solution Requirements

3.10.3 The Request

3.10.4 text/xml elements for PATCH

3.10.4.1 ResourceUpdate

3.10.4.2 Insert

Please note that in order to protect the white space contained in this XML element the following attribute/value MUST be included in the element: XML-SPACE = "PRESERVE".

3.10.4.3 Delete

3.10.4.4 Replace

3.10.4.5 Octet-Range Attribute

3.10.5 The Response

3.10.6 Examples

3.10.6.1 HTML file modification

Before:

     <HTML>
     <HEAD>
     <TITLE>Hello world HTML page</TITLE>
     </HEAD>
     <BODY>
     <P>Hello, world!</P>
     </BODY>
     </HTML>

PATCH Request: Response:

     PATCH hello.html HTTP/1.1
     Host: www.example.org
     Content-Type: text/xml
     Content-Length: xxx

                                   HTTP/1.1 100 Continue
     <?XML:Namespace href =
     "http://www.ietf.org/standards/dav/patch/" AS = "D"/>
     <D:ResourceUpdate>
          <Replace XML-SPACE = "PRESERVE"><octet-range>14</octet-range>
         &003CTITLE&003ENew Title&003C/TITLE&003E</Replace>
          <Delete><octet-range>38-50</Delete>
     <Insert XML-SPACE = "PRESERVE"><octet-range>86</>&003CP&003ENew paragraph&003C/P&003E</Insert>
     </D:ResourceUpdate>
                                   HTTP/1.1 200 OK

After:

     <HTML>
     <HEAD>
     <TITLE>New Title</TITLE>
     </HEAD>
     <BODY>
     <P>Hello, world!</P>
     <P>New paragraph</P>
     </BODY>
     </HTML>

3.11 Headers

3.11.1 Destination Header

3.11.2 Enforce-Live-Properties Header

     EnforceLiveProperties = "Enforce-Live-Properties" ":" ("*" |
     "Omit" | 1#(Property-Name))
     Property-Name = "<" URI ">"

3.11.3 Overwrite Header

     Overwrite = "Overwrite" ":" ("true" | "false")

3.11.4 Destroy Header

DestroyHeader = "Destroy" ":" #Choices

Choices = "VersionDestroy" | "NoUndelete" | "Undelete" | token |"<" URI ">" ; a token extension MUST NOT be used unless it is specified in a RFC16, otherwise a URI MUST be used for extensions.

3.11.5 Collection-Member Header

     CollectionMember = "Collection-Member" ":" URI

3.12 Links

3.12.1 Source Link Property Type

4 State Tokens

4.1 Overview

4.1.1 Problem Description

The fundamental issue with entity tags is that they can only be generated by a resource. However there are times when a client will want to be able to share state tokens between resources, potentially on different servers, as well as be able to generate certain types of lock tokens without first having to communicate with a server.

For example, a principal may wish to require that resource B have a certain state in order for a method to successfully execute on resource A. If the client submits an e-tag from resource B to resource A, then A has no way of knowing that the e-tag is meant to describe resource B.

Another example occurs when a principal wishes to predicate the successful completion of a method on the absence of any locks on a resource. It is not sufficient to submit an "If-None-Match: *" as this refers to the existence of an entity, not of a lock.

This draft defines the term "state token" as an identifier for a state of a resource. The sections below define requirements for state tokens and provide a state token syntax, along with two new headers which can accept the new state token syntax.

4.1.2 Solution Requirements

4.1.2.1 Syntax

This self-describing nature allows servers to accept tokens from other servers and potentially be able to coordinate state information cross resource and cross site through standardized protocols. For example, the execution of a request on resource A can be predicated on the state of resource B, where A and B are potentially on different servers.

Client Generable. The state token syntax must allow, when appropriate, for clients to generate a state token without having first communicated with a server.

One drawback of entity tags is that they are set by the server, and there is no interoperable algorithm for calculating an entity tag. Consequently, a client cannot generate an entity tag from a particular state of a resource. However, a state token which encodes an MD5 state hash could be calculated by a client based on a client-held state of a resource, and then submitted to a server in a conditional method invocation.

Another potential use for client generable state tokens is for a client to generate lock tokens with wild card fields, and hence be able to express conditionals such as: "only execute this GET if there are no write locks on this resource."

4.1.2.2 Conditonals

4.2 State Token Syntax

State-Token = "StateToken:" Type ":" Resources ":" State-Info
Type = "Type" "=" Caret-encoded-URL
Resources = "Res" "=" Caret-encoded-URL
Caret-encoded-URL = "^" Resource "^"
Resource = <A URI where all "^" characters are escaped>
State-Info = *(uchar | reserved)  ; uchar, reserved defined
section 3.2.1 of RFC 2068

This proposal has created a new URL scheme for state tokens because a state token names a network resource using its normal name, which is typically state-invariant, along with additional information that specifies a particular state of the resource. Encoding the state information into the native URL scheme of the network resource was not felt to be safe, since freedom from name space collisions could not be guaranteed. If this proposal is accepted, the StateToken URL scheme will need to be defined and registered with IANA.

State Token URLs begin with the URL scheme name "StateToken" rather than the name of the particular state token type they represent in order to make the URL self describing. Thus it is possible to examine the URL and know, at a minimum, that it is a state token.

Labeled name/value pairs are used within the token to allow new fields to be added. Processors of state tokens MUST be prepared to accept the fields in whatever order they are present and MUST ignore any fields they do not understand. The "Type" field specifies the type of the state information encoded in the state token. A URL is used in order to avoid namespace collisions.

The "Res" field identifies the resource for which the state token specifies a particular state. Since commas and spaces are acceptable URL characters, a caret is used to delimit a URL. Since a caret is an acceptable URL character, any instances of it must be escaped using the % escape convention.

The State-Info production is expanded upon in descriptions of specific state token types, and is intended to contain the state description information for a particular state token.

4.3 State Token Conditional Headers

4.3.1 If-State-Match

If-State-Match = "If-State-Match" ":" ("AND" | "OR") 1#("<" State-Token ">")

The If-State-Match header is intended to have similar functionality to the If-Match header defined in section 14.25 of RFC 2068.

If the AND keyword is used and all of the state tokens identify the state of the resource, then the server MAY perform the requested method. If the OR keyword is used and any of the state tokens identifies the current state of the resource, then server MAY perform the requested method. If neither of the keyword requirements is met, the server MUST NOT perform the requested method, and MUST return a 412 (Precondition Failed) response.

4.3.2 If-None-State-Match

If-None-State-Match = "If-None-State-Match" ":" 1#("<" State-Token ">")

The If-None-State-Match header is intended to have similar functionality to the If-None-Match header defined in section 14.26 of RFC 2068.

If any of the state tokens identifies the current state of the resource, the server MUST NOT perform the requested method. Instead, if the request method was GET, HEAD, INDEX, or GETMETA, the server SHOULD respond with a 304 (Not Modified) response, including the cache-related entity-header fields (particularly ETag) of the current state of the resource. For all other request methods, the server MUST respond with a status of 412 (Precondition Failed).

If none of the state tokens identifies the current state of the resource, the server MAY perform the requested method.

Note that the "AND" and "OR" keywords specified with the If-State-Match header are intentionally not defined for If-None-State-Match, because this functionality is not required.

4.4 State Token Header

State-Token-Header = "State-Token" ":" 1#("<" State-Token ">")

The State Token header is intended to have similar functionality to the etag header defined in section 14.20 of RFC 2068. The purpose of the tag is to return state tokens defined on a resource in a response. The contents of the state-token are not guaranteed to be exhaustive and are generally used to return a new state token that has been defined as the result of a method. For example, if a LOCK method were successfully executed on a resource the response would include a state token header with the lock state token included.

4.5 E-Tags

5 Locking

5.1 Problem Description - Overview

This draft allows locks to vary over two parameters, the number of principals involved and the type of access to be granted. This draft will only provide for the definition of locking for one access type, write. However, the syntax is extensible enough to allow for the specification of other access types. It is a goal of this proposal that it use the same access verbs as will be defined in the access control draft.

5.1.1 Exclusive Vs. Shared Locks

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 right. Shared locks are provided for this case. A shared lock allows multiple principals to receive a lock, hence any 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 who are trusted, for example, may have permission to write the resource, those who are not, don't. Among those who have access permission to write the resource, the set of principals who have taken out a shared lock also must trust each other, creating a (probably) 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 in conjunction with a precondition header (If-State-Match) that checks for existence of the lock prior to writing the resource. Others may decide they trust their collaborators (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 is potentially 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). The intent of a shared lock is to let collaborators know who else is potentially working on a resource.

Why not use exclusive write locks all the time? Experience from initial Web distributed authoring systems has indicated that exclusive write locks are often too rigid. An exclusive write lock is used to enforce a particular editing process: take out exclusive write lock, read the resource, perform edits, write the resource, release the lock. What happens if the lock isn't released? While the time-out mechanism provides one solution, if you need to force the release of a lock immediately, it doesn't help much. Granted, an administrator can release the lock for you, but this could become a significant burden for large sites. Further, what if the administrator can't be reached immediately?

Despite their potential problems, exclusive write locks are extremely useful, since often a guarantee of freedom from overwrite conflicts is exactly what is needed. The solution: provide exclusive write locks, but also provide a less strict mechanism in the form of shared locks which can be used by a set of people who trust each other and who have access to a communications channel external to HTTP which can be used to negotiate writing to the resource.

5.1.2 Required Support

The reason for this flexibility is that server implementers have said that they are willing to accept minimum requirements on all services but locking. Locking policy strikes to the very heart of their resource management and versioning systems and they require control over what sort of locking will be made available. For example, some systems only support shared write locks while others only provide support for exclusive write locks. As each system is sufficiently different to merit exclusion of certain locking features, the authors are proposing that locking be allowed as the sole axis of negotiation within DAV.

5.2 LOCK Method

5.2.1 Operation

A successful response to a lock invocation MUST include a Lock-Token header. If the server supports a time based lock removal mechanism on the resource, a successful lock invocation SHOULD return a Time-Out header.

5.2.2 Effect of Locks on Properties and Containers

The default behavior when locking a container is to act as if a "Depth: 0" header had been placed on the method.

5.2.3 Locking Replicated Resources

5.2.4 Interaction with other Methods

5.2.5 Lock Compatibility Table

Legend: True = lock MAY be granted. False = lock MUST NOT be granted. *=if the principal requesting the lock is the owner of the lock, the lock MAY be regranted.

The current lock state of a resource is given in the leftmost column, and lock requests are listed in the first row. The intersection of a row and column gives the result of a lock request. For example, if a shared lock is held on a resource, and an exclusive lock is requested, the table entry is "false", indicating the lock must not be granted.

If an exclusive lock is re-requested by the principal who owns the lock, the lock MAY be regranted. If the lock is regranted, the same lock token that was previously issued MUST be returned.

5.2.6 Status Codes

5.2.7 Example

LOCK /workspace/webdav/proposal.doc HTTP/1.1
Host: webdav.sb.aol.com
Lock-Info: LockType=Write LockScope=Exclusive
Owner: <http://www.ics.uci.edu/~ejw/contact.html>

HTTP/1.1 200 OK
State-Token: StateToken:Type=^DAV:/LOCK/DAVLOCK^:Res=^http://www.ics.uci.edu/workspace/webdav/proposal.doc^:LockType=Write:LockScope=Exclusive:ServerID=12382349AdfFFF
Time-Out: ClockType=Activity TimeType=second;604800

This example shows the successful creation of an exclusive write lock on resource http://webdav.sb.aol.com/workspace/webdav/proposal.doc. The resource http://www.ics.uci.edu/~ejw/contact.html contains contact information for the owner of the lock. The server has an activity-based timeout policy in place on this resource, which causes the lock to automatically be removed after 1 week (604800 seconds). The response has a Lock-Token header that gives the state token URL for the lock token generated by this lock request.

5.2.8 Lock-Info Request Header

LockInfo = "Lock-Info" ":" DAVLockType SP DAVLockScope CRLF
DAVLockType = "LockType" "=" DAVLockTypeValue
DAVLockTypeValue = ("Write" | *(uchar | reserved))
DAVLockScope = "LockScope" "=" DAVLockScopeValue
DAVLockScopeValue = ("Exclusive" |"Shared" | *(uchar | reserved))

5.2.9 Owner Request Header

5.2.9.1 Problem Description

5.2.9.2 Solution Requirements

The From header (defined in RFC 2068), which contains only an email mailbox, is not sufficient for the purposes of quick identification. When desperately looking for someone to remove a lock, e-mail is often not sufficient. A telephone number (cell number, pager number, etc.) would be better. Furthermore, the email address in the From field may or may not support including the owners name and that name is often set to an alias anyway. Therefore a header more flexible than From is required.

5.2.9.3 Syntax

Owner = "Owner" ":" (("<" URI ">")  | quoted-string)

5.2.10 Time-Out Header

5.2.10.1 Problem Description

5.2.10.2 Solution Requirements

The second solution, is the time based removal policy. Activity based systems set a timer as soon as the lock is taken out. Every time a method is executed on the resource, the timer is reset. If the timer runs out, the lock is removed.

Finally, some systems only allow locks to exist for the duration of a session, where a session is defined as the time when the HTTP connection that was used to take out the lock remains connected. This mechanism is used to allow programs which are likely to be improperly exited, such as JAVA programs running in a browser, to take out locks without leaving a lot of ownerless locks around when they are improperly exited.

5.2.10.3 Syntax

TimeOut = "Time-Out" ":" ((TimeOutType SP Session) | TimeOutVal |
          Session) CRLF
TimeOutType = ClockType SP TimeType
ClockType = "ClockType" "=" ClockTypeValue
ClockTypeValue = "Activity"
TimeType = "TimeType" "=" TimeTypeValue
TimeTypeValue = "Second" ";" DAVTimeOutVal
DAVTimeOutVal = 1*digit
Session = "Session" "=" ("Yes" | "No")

If no time based system is in use then a Time-Out header MUST NOT be returned. The Time-Out header MUST only be returned in a response to a LOCK request.When session is set to yes then whatever clocktype and timetype is being used, their effects are scoped within that particular session. So an absolute lock with a ten day expiration period will only remain active so long as the session remains active. A DAVTimeOutVal value must be greater than zero.

Clients MAY include TimeOut headers in their LOCK requests. However the server is not required to honor or even consider the request. The primary purpose in allowing clients to submit a TimeOut header is to inform the server if the client is requesting a session based lock. If a timeout is associated with the lock, the server MUST return a TimeOut header with a valid value.

5.2.11 State-Token Header

5.2.11.1 Problem Definition

5.2.11.2 Solution Requirement

The solution must not require that clients guess what sorts of locks might be used and use if-state-match headers with wildcards to prevent collisions. The problem with trying to "guess" which locks are being used is that new lock types might be introduced, and the program would not know to "guess them". So, for example, a client might put in an if-state-match header with a wildcard specifying that if any write lock is outstanding then the operation should fail. However a new read/write lock could be introduced which the client would not know to put in the header.

5.2.11.3 State-Token Header

The State-Token header containing a lock token owned by the request principal is used by the principal on arbitrary method to indicate that the principal is aware of the specified lock. If the State-Token header with the appropriate lock token is not included the request MUST be rejected, even though the requesting principal has authorization to make modifications specified by the lock type. This injunction does not apply to methods that are not affected by the principal’s lock.

For example, Program A, used by user A, takes out a write lock on a resource. Program A then makes a number of PUT requests on the locked resource, all the requests contain a State-Token header which includes the write lock state token. Program B, also run by User A, then proceeds to perform a PUT to the locked resource. However program B was not aware of the existence of the lock and so does not include the appropriate state-token header. The method is rejected even though principal A is authorized to perform the PUT. Program B can, if it so chooses, now perform lock discovery and obtain the lock token. Note that program A and B can perform GETs without using the state-token header because the ability to perform a GET is not affected by a write lock. Note that having a lock state token provides no special access rights. Anyone can find out anyone else’s lock state token by performing lock discovery. Locks are to be enforced based upon whatever authentication mechanism is used by the server, not based on the secrecy of the token values.

5.3 Write Lock

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 to respect locks are guaranteed to not change while locked.

It is possible to assert a write lock on a null resource in order to lock the name. Please note, however, that locking a null resource effectively makes the resource non-null as the resource now has lock related properties defined on it.

Write locking a container also prevents adding or removing members of the container. This means that attempts to PUT/POST a resource into the immediate name space of the write locked container MUST fail if the principal requesting the action does not have the write lock on the container. In order to keep the behavior of locking containers consistent all locks on containers MUST contain a Depth header equal to infinity, any other value is illegal.

5.4 Lock Tokens

5.4.1 Problem Description

5.4.2 Proposed Solution

5.4.3 Lock Token Definition

Lock-Token-URL = "StateToken:" Type ":" Resources ":" State-Info
Type = "Type" "=" "^DAV:/LOCK/DAVLOCK^"
Resources = "Res" "=" 1*("^" Caret-Encoded-URI "^")
Caret-Encoded-URI = <This is a URI which has all "^"s % encoded.>
State-Info = DAVLockScope ":" DAVLockType ":" ServerID  ;
DAVLockScope, DAVLockType defined in Lock-Info header
ServerID = "ServerID" "=" *(uchar | reserved)

The ServerID is a field for use by the server. Its most basic purpose is to put in a unique identifier to guarantee that a server will never confuse an old lock token with a newer one. However the server is free to use the field to record whatever information it deems fit. The field is opaque to clients.

5.5 UNLOCK Method

5.5.1 Problem Definition

5.5.2 Example

UNLOCK /workspace/webdav/proposal.doc HTTP/1.1
Host: webdav.sb.aol.com
State-Token: StateToken:Type=^DAV:/LOCK/DAVLOCK^:Res=^http://www.
ics.uci.edu/workspace/webdav/proposal.doc^:LockType=Write:LockSco
pe=Exclusive:ServerID=12382349AdfFFF

HTTP/1.1 200 OK

In this example, the lock from example of Section 2.9 is removed from the resource at http://webdav.sb.aol.com/workspace/webdav/proposal.doc

5.6 Discovery Mechanisms

5.6.1 Lock Type Discovery

5.6.1.1 Problem Definition

5.6.1.2 SupportedLock Property

5.6.1.3 LOCKENTRY XML Element

5.6.1.4 LOCKTYPE XML Element

5.6.1.5 LOCKSCOPE XML Element

5.6.2 Active Lock Discovery

5.6.2.1 Problem Definition

5.6.2.2 Solution Requirements

5.6.2.3 LOCKDISCOVERY Property

5.6.2.4 ACTIVELOCK XML Element

5.6.2.5 OWNER XML Element

5.6.2.6 TIMEOUT XML Element

5.6.2.7 CLOCKTYPE XML Element

5.6.2.8 TIMETYPE XML Element

5.6.2.9 TIMEOUTVAL XML Element

5.6.2.10 LOCKTOKEN XML Element

6 Version Control

7 Internationalization Support

8 Security Considerations

9 Acknowledgements

10 References

[Bray, Sperberg-McQueen, 1997] T. Bray, C. M. Sperberg-McQueen, "Extensible Markup Language (XML): Part I. Syntax", WD-xml-lang.html, http://www.w3.org/pub/WWW/TR/WD-xml-lang.html.

[Connolly et al, 1997] D. Connolly, R. Khare, H.F. Nielsen, "PEP - an Extension Mechanism for HTTP", Internet draft, work-in-progress. draft-ietf-http-pep-04.txt, ftp://ds.internic.net/internet-drafts/draft-ietf-http-pep-04.txt.

[Fielding et al., 1997] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol --HTTP/1.1." RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997.

[Lasher, Cohen, 1995] R. Lasher, D. Cohen, "A Format for Bibliographic Records," RFC 1807. Stanford, Myricom. June, 1995.

[Maloney, 1996] M. Maloney, "Hypertext Links in HTML." Internet draft (expired), work-in-progress, January, 1996.

[MARC, 1994] Network Development and MARC Standards, Office, ed. 1994. "USMARC Format for Bibliographic Data", 1994. Washington, DC: Cataloging Distribution Service, Library of Congress. [Miller et al., 1996] J. Miller, T. Krauskopf, P. Resnick, W. Treese, "PICS Label Distribution Label Syntax and Communication Protocols" Version 1.1, W3C Recommendation REC-PICS-labels-961031. http://www.w3.org/pub/WWW/TR/REC-PICS-labels-961031.html

[Slein et al., 1997] J. A. Slein, F. Vitali, E. J. Whitehead, Jr., D. Durand, "Requirements for Distributed Authoring and Versioning on the World Wide Web." Internet-draft, work-in-progress, draft-ietf-webdav-requirements-03.txt, ftp://ds.internic.net/internet-drafts/draft-ietf-webdav-requirements-03.txt.

[WebDAV, 1997] WEBDAV Design Team. "A Proposal for Web Metadata Operations." Unpublished manuscript. http://www.ics.uci.edu/~ejw/authoring/proposals/metadata.html

[Weibel et al., 1995] S. Weibel, J. Godby, E. Miller, R. Daniel, "OCLC/NCSA Metadata Workshop Report." http://purl.oclc.org/metadata/dublin_core_report.

[Yergeau, 1997] F. Yergeau, "UTF-8, a transformation format of Unicode and ISO 10646", Internet Draft, work-in-progress, draft-yergeau-utf8-rev-00.txt, http://www.internic.net/internet-drafts/draft-yergeau-utf8-rev-00.txt.

11 Authors' Addresses

Y. Y. Goland
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
Email yarong@microsoft.com

E. J. Whitehead, Jr.
Dept. Of Information and Computer Science
University of California, Irvine
Irvine, CA 92697-3425
Email: ejw@ics.uci.edu

A. Faizi
Netscape
685 East Middlefield Road
Mountain View, CA 94043
Email: asad@netscape.com

S. R Carter
Novell
1555 N. Technology Way
M/S ORM F111
Orem, UT 84097-2399
Email srcarter@novell.com

D. Jensen
Novell
1555 N. Technology Way
M/S ORM F111
Orem, UT 84097-2399
Email dcjensen@novell.com