WEBDAV Working Group                                                      Y. Goland, Microsoft
INTERNET-DRAFT                                               E. J. Whitehead, Jr., U.C. Irvine
                                                                          Asad Faizi, Netscape
                                                                     Stephen R. Carter, Novell
                                                                            Del Jensen, Novell

<webdav-draft-06.html>                                                January 23, 1997

Expires June, 1997

Author's draft: v0.6

Extensions for Distributed Authoring and Versioning on the World Wide Web

Status of this Memo

This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress".

To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast).

Distribution of this document is unlimited. Please send comments to the WWW Distributed Authoring and Versioning (WEBDAV) working group at <w3c-dist-auth@w3.org>, which may be joined by sending a message with subject "subscribe" to <w3c-dist-auth-request@w3.org>. Discussions of the WEBDAV working group are archived at <URL:http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth>. The HTTP working group at <http-wg@cuckoo.hpl.hp.com> also discusses the HTTP protocol. Discussions of the HTTP working group are archived at <URL:http://www.ics.uci.edu/pub/ietf/http/>. General discussions about HTTP and the applications which use HTTP should take place on the <www-talk@w3.org> mailing list.

Abstract

[Ed. Note: TBD]

1. Introduction

1.1 Purpose

The purpose of this document is to extend the HTTP 1.1 [HTTP11] protocol to support features which satisfy the Distributed Authoring and Versioning requirements set down in [INSERT REFERENCE TO UNIFIED DAV REQUIREMENTS DRAFT].

1.2 Terminology

The following entries define how a term is used within this document.

Unless otherwise noted, the use of terminology in this document is consistent with the definitions of terms given in [HTTP11].

Editor: Sections references need to be entered.

arbiter
A resource which performs actions on the behalf of other resources.
attribute
An attribute is a name/value pair which contains meta-information regarding a resource. See section x.x.
attribute set
An attribute set is a collection of attributes. See section x.x.
set edit announcement
A set edit announcement is a declaration by a principal that they intend to edit a resource. No action other than the declaration is implied by a set edit announcement. See section x.x.
remove edit announcement
A remove edit announcement is a declaration by a principal that they no longer intend to edit a resource. See section x.x.
check-out root
One or more versioned resources within a particular version tree which are operated on by a CHECKOUT method.
command comments
Command Comments associate either a string or a URI with an HTTP message. See section x.x.
copy
A copy performs a duplication of a resource, making it available at both the original and new location in the URI namespace. Due to contextual differences, it may not be possible to create an exact copy of a resource. A copy only requires best effort on the part of the copy agent. See section x.x.
collection
A group of URIs which are manipulated as a unit. See section x.x.
destroy
To destroy a resource is to request that the resource be permanently removed from storage. This differs from delete in that some versioning systems handle delete as a request to no longer make the specified resource available under the specified URI. See section x.x.
diff
A diff is a mechanism whereby two or more resources are compared and the differences enumerated. See section x.x.
history
A history lists the URIs of the versions of a resource along with related information. See section x.x.
merge
A merge is the process whereby information from multiple resources is folded into a single resource. Merges can occur at the client or the server. See section x.x.
move
A move is logically an atomic action consisting of a copy followed by a delete of the source resource. Please see the definition of copy in this section. See section x.x.
no-modify lock
A no-modify lock prevents a locked resource from being edited until all no-modify locks on the resource are released. See section x.x.
notify request
A notify request instructs the recipient to send information regarding the progress of a request. See section x.x.
principal
A principal is the source of a message. For example: persons, computers, and programs.
read lock
A read lock prevents principals who do not posses a read lock on a resource from reading that resource. See section x.x.
redirect
A redirect instructs a server to return one of the 3xx series codes. See section x.x.
relationship
A relationship is a unidirectional typed link. See section x.x.
shared mode
Shared mode modifies a lock request such that the lock may be shared between multiple principals. See section x.x.
version identifier
The identifier used to name a version of a resource.
working resource
The writeable resource created by some versioning engines as the result of a CHECKOUT method invocation.
write lock
A write lock prevents principals who do not possess a write lock on a resource from editing that resource. See section x.x.

1.3 Notational Conventions and Generic Grammar

This specification uses the Augmented BNF and Basic Rules as defined in Section 2 of [HTTP11].

1.4 Design Conventions

The following design conventions have been adopted by the HTTP Distributed Authoring and Versioning (DAV) group.

  1. Whenever reasonable new functionality will be expressed as new methods. When sensible the commands for such a method will be included in the message body of the request.
  2. This resolution was adopted in order to solve a debate about how to express new functions such as copy and diff. One group wished to use POST and MIME types to express new commands. Another group wished to use new methods and MIME types to express new commands. A third group wished to use new methods and new method headers to express new commands. The group settled on using new methods and MIME types to express new commands. The new methods would allow for quick parsing by proxies and servers but the MIME types would allow for flexibility in specifying the command. It was also felt that introducing method specific headers would violate the letter and spirit of the HTTP protocol.
  3. Methods should only perform a single action.
  4. The original design of many of the methods in this document allowed for multiple requests of the same type to be packaged together. So, for example, one could send a Copy method which specified that 1000 different URIs should be copied. It was decided that in the face of pipelining, compressed headers, and other innovations there was no need to add this level of complexity to the protocol. This decision was based upon the assumption that a new method or MIME type would be introduced which would allow for any number of HTTP requests to be bundled together. It was further assumed that such a method or MIME type would carry with it the option to specify that the contents be processed atomically.
  5. URLs are opaque tokens and should be treated as such.
  6. It is often possible to decrease the number of trips to retrieve a particular piece of data by putting suffixes on URLs. However URLs are intended to be opaque tokens. The above design principal not prevent the use of suffixes but rather requires that the server indicates that a particular URL understands a particular type of suffix.
  7. Only addressable entities will be subject to the commands in this document.
  8. Response must be machine processable. Currently HTTP responses rely upon humans being available to view the response and take appropriate action. This level of error encoding is not sufficient for WEBDAV purposes where all actions and results of all actions must be fully machine processable. However, a corollary of this design principal is that response messages are not required to provide information about incorrect syntax, only to point out that incorrect syntax has been submitted. It is legitimate to assume that the client and server are both capable of generating proper syntax. However, this corollary in no way effects the general principal of being generous in the sorts of messages accepted.
  • It is sometimes desirable to have a non-addressable entity. For example, an accept header may specify a content-language. The response may contain a representation in that language but may not contain a content-location header. In that case the representation of that resource in that language will not alterable with the commands given in this document.
  •  

    2. Schema Methods

    [Ed. Note: Misplaced this section - should follow links. Will correct later.]

    2.1 Introduction

    DAV methods provide diverse abilities, and no current system supports all of them. As such the client requires a mechanism to determine what features of a method a server supports. DAV provides such a mechanism controlling how methods are defined and then providing for a feature discovery mechanism. DAV also provides for a version number to allow servers to alter method semantics without breaking older clients.

    2.2 Method Formatting

    Part of the feature discovery mechanism is a regulated format for method request bodies. This format allows for individual method functions to be identified and for the server to be able to describe its support for those functions. Methods that support this format are referred to as Schema Methods. All Schema Methods MUST use this format. [Author's Note: We will have to change the name.]

    A Schema Method takes the following form:

    Request-Body = Schema-Version CRLF *(Schema-Entry CRLF)
    Schema-Version = 1*Digit.1*Digit
    Schema-Entry = AttributeName ":" (Enumerated_List | Comma_List | Open_Value)
    AttributeName = Token
    Enumerated_List = #Token
    Comma_List = #Token
    Open_Value = Text-No-CRLF
    Text-No-CRLF = ; Text which doesn't contain a CRLF

    The method's request body always begins with a Schema-Version that is followed by a series of Schema-Entries. These entries always consist of a name followed by a colon followed by either a predefined list of values, a comma separated list of tokens, or an open value which can contain any legal text but a CRLF.

    The Schema-Version major number describes a set of schema entries and their defined values for a particular method. The major number MUST increase if the semantics of a previously defined schema entry is altered or if the Schema Method format is changed.

    The Schema-Version minor number is used for feature negotiation purposes. As defined below feature negotiation allows the server to list each schema-entry and indicate if the entry is required, optional, or unsupported. A server MAY add new schema-entries to a method without changing the minor schema-version number so long as those entries are optional. If a new required schema-entry is introduced then the minor number MUST be increased.

    2.3 Schema Entry Negotiation & Response Format

    With the Schema Method format it becomes possible for a server to provide information to a client regarding the schema-entries it supports and the manner in which it supports them. This mechanism is completely mechanistic so any Schema Method can be negotiated upon. This section describes the response format used by a server to declare the nature of its support for a Schema Method.

    The format is to list each schema entry, mark it as required, optional, or unsupported, and then indicate what values it may take on. Schema entries with predefined lists of values the server lists which of those values is supported. For schema entries with a comma delaminated list of tokens, the server indicates how many tokens it will accept. No additional information is provided for schema entries that use the Text-No-CRLF production.

    A client MAY include schema entries whose values are enumerated lists for which there is only a single legal value. A client MUST NOT include schema entries that have been marked as unsupported. A client MAY include a schema entry that is marked as optional. A client MUST include schema entries that are marked as required. A client MUST only use values that the server has indicated it will accept. If definition of a Schema Method does not state that a schema entry is required then the server MAY make that entry required, optional, or unsupported. The Schema-Version production MUST be included in all request bodies of all Schema Methods. The definition of a Schema Method MAY put restrictions on the interaction of schema entries, such as declaring that if one schema-entry is required then so must another.

    The format for providing Schema Method negotiation information is a web collection that is contained in a response of type Text/HTML.

    WC Attributes:

    Type = "DAV/VersionSupport"
    Name = MethodName
    Schema-Version = SupportedVersions
    SupportedVersions = #(VersionRange | MajorNumber | Individual)
    VersionRange = Schema-Version "to" Schema-Version
    MajorNumber = 1*Digit "." "*"
    Individual = Schema-Version

    WCDATA Entry:

    Entry = AttributeName (Required_Optional | "Unsupported") CRLF
    AttributeName = Token
    Required_Optional = ("Required" | "Optional") [(EnumList | NumLegalEntries)]
    EnumList = "Enumerated_List" ":" "["#Token"]" | "AsDefined"
    NumLegalEntries = "Number_Entries" ":" 1*Digit | "Infinite" | "AsDefined"

    The "AsDefined" value is used when the definition of possible values is too complex to be expressed in this simple negotiation format.

    The VersionRange production allows the server to declare support for all versions within a specified range. The MajorNumber production allows the server to declare support for all versions within a major version. The Individual version production allows the server to declare support for an individual version.

    Multiple web collections may be specified as necessary if support differs based on schema-version.

    2.4 Schema Method Support Discovery

    Two mechanisms are provided for discovering server support for a Schema Method. One is by checking for a link and the other is by using a discovery method. A server MUST support at least one of these two mechanisms.

    2.4.1 SchemaMethod Link

    The type of the schema method link is defined as follows:

    SchemaMethodLink = "DAV.SchemaMethod." MethodName
    MethodName = Token

    This destination of this link is the support provided by the source for the method specified. The result will be a text/html response body containing a series of web collections describing the systems support for that Schema Method.

    [NOT YET DEFINED - A Web Collection to indicate that there is variation of function based on namespace.]

    2.4.2 SCHEMASUPPORT

    2.4.2.1 Method Definition

    2.4.2.2 Request Body

    2.4.2.3 Response Body

    2.4.2.4 Error Conditions

    [2.4.2 NOT YET DEFINED - It will provide for the submission of a schema method name and information about schema versions supported by the client. The server will then return a web collection specifying the sort of support provided for the schema method and schema versions indicated.]

    3. Links

    3.1 Introduction

    In [HTTP11] link and unlink methods were introduced. The idea was to allow for two or more arbitrary resources to be associated with each other. In essence, its purpose was to extend the linking facilities available on the Web to all content types, not just HTML.

    This document proposes a link facility consisting of links which are typed and unidirectional, containing an explicit source and destination.

    3.2 Link Types

    Links are typed. These types explain the purpose and behavior of a link. It is possible that multiple links defined on the same resource may have the same type, e.g., a resource with multiple authors.

    A link type usually belongs to a link schema, such as the "LockInfo" type which belongs to the "DAV" schema. By convention, links which belong to a schema are specified as: schema "." typename. Thus, the LockInfo type would be specified as "DAV.LockInfo". This creates a type namespace which is less susceptable to namespace collision than a single, flat namespace. However, use of the "." to denote hierarchy is only a convention, since types are properly considered to be opaque tokens.

    3.3 LINK

    3.3.1 Method Definition

    The LINK method requests that a single typed unidirectional hypertext link be created on the Request-URI. This link consists of three fields, a source URI, a destination URI, and a type, which is an opaque token. The source URI is the beginning of the link, the destination URI is the endpoint of the link, and the type describes the relationship between the source and destination resources. A link may be interpreted as a binary relationship between the source and destination resources, which has the meaning, "the destination resource contains information of relation <type> to the source resource." A link may also be interpreted as an attribute-value pair, where the attribute name is the link type, and the value is pointed to by the destination of the link.

    The specification of the requested link is made in the message body of the LINK request, which SHOULD be of content type "application/link". The source URI of the link will typically correspond to the Request-URI of the LINK request, but MUST not be required to do so. Either the source URI or the destination URI of the link MUST correspond to the Request-URI of the LINK request. This ensures that the Request-URI is part of the link being defined.

    If the source URI is ommitted in the link specification, the source URI defaults to the Request-URI. If the destination URI is ommitted in the link specification, the destination URI defaults to the Request-URI.

    Some servers may automatically allocate part of their namespace for link information of a specific type. For example, the creation date of a resource at URL <http://www.ics.uci.edu/resource.html> might be accessed from <http://www.ics.uci.edu/resource.html?create_date>. In this case, a user-agent would not want to specify the destination of a link of type "create_date," and instead would want the server to automatically fill-in the correct destination URI. If the server should specify the source or destination URI of a link, then the key word "SET" is entered for the source or destination URI in the link specification.

    3.3.2 Request Body

    The request body of a LINK method request is of content type application/link, defined as:

    Link = Version CRLF [ Source CRLF ] [ Destination CRLF ] Type CRLF 
    Schema-Version = "Schema-Version" ":" 1*Digit "." 1*Digit 
    Source = "Source" ":" ( URI | "SET" ) 
    Destination = "Destination" ":" ( URI | "SET" ) 
    Type = "Type" ":" token

    The Schema-Version field specifies the version of the specification of the application/link media type. By definition, the version of the application/link media type specified in this document is "1.0".

    Example

    Source: http://www.ics.uci.edu/~ejw/reports/Q1.html 
    Destination: http://www.ics.uci.edu/~ejw/reports/Q1_author.html 
    Type: Author

    This link states that the destination URI contains information about the author of the source URI. It may also be interpreted as the value of the author attribute of the source URI can be found in the resource pointed to by the destination URI.

    3.3.3 Response Body

    The request body of a LINK method request is of content type application/linkresult, defined as:

    LinkResult = Version CRLF LinkSource CRLF LinkDestination CRLF Type CRLF 
    LinkSource = "Source" ":" URI 
    LinkDestination = "Destination" ":" URI 
    Type = "Type" ":" token
    

    3.3.4 Error Conditions

    a) there is a syntax error in the application/link message body (e.g., missing field values, missing type value)

    b) the source URI and the destination URI fields are both missing

    c) Both the source URI and the destination URI are specified, and neither match the Request-URI.

    d) Unsupported Type - The server does not allow links of the specified type to be created.

    e) The server does not have room to store the requested link.

    f) The server is unable to fulfill a request to automatically set an endpoint of the link.

    3.5 UNLINK

    3.5.1 Method Definition

    The UNLINK method requests the removal of any link defined on the Request-URI which exactly matches the link specification in the request message body, which must be of content type application/unlink.

    If there are any links which exactly match the link specification, a description of the removed links is returned in a response body of type application/unlinkresult.

    3.5.2 Request Body

    The request body of an UNLINK method request is of content type application/unlink, defined as:

    UnLink = Version CRLF Source CRLF Destination CRLF Type CRLF
    Schema-Version = "Schema-Version" ":" 1*Digit "." 1*Digit 
    LinkSource = "Source" ":" URI 
    LinkDestination = "Destination" ":" URI 
    Type = "Type" ":" token

    The Schema-Version field specifies the version of the specification of the application/unlink media type. By definition, the Schema-Version of the application/unlink media type specified in this document is "1.0".

    3.5.3 Response Body

    The response body of an UNLINK method is of content type application/unlinkresult, defined as:

    UnLinkResult = Version CRLF 1*(LinkSource CRLF LinkDestination CRLF Type CRLF)
    Schema-Version = "Schema-Version" ":" 1*Digit "." 1*Digit 
    LinkSource = "Source" ":" URI 
    LinkDestination = "Destination" ":" URI 
    Type = "Type" ":" token
    

    3.5.4 Error Conditions

    a) there is a syntax error in the application/unlink message body (e.g., missing fields, missing field values, missing type value)

    b) Both the source URI and the destination URI are specified, and neither match the Request-URI.

    c) No links match the specification in the request message body.

    3.6 LINKSEARCH

    3.6.1 Method Definition

    The LINKSEARCH method is used to search on the link tuple space. The search occurs in the URI namespace. Search points and scope define the area of name space to be searched. The search points are URIs from which the search should start. The scope defines the number of levels into the URI namespace the search should go down. The search syntax is in prefix notation in order to ease processing by the server.

    3.6.2 Request Body

    The Request-URI is the search arbiter, and it is the job of that resource to process the request and return the results.

    The media type is application/linksearch.

    This syntax is adapted from [RFC1959] and [RFC1960].

    LinkSearchMethod = Schema-Version CRLF [SearchPoints] CRLF SearchPattern CRLF Scope CRLF
    SearchPoints = "SearchPoints" ":" 1#URI 
    SearchPattern = "SearchPattern" ":" 1*SearchOperations
    SearchOperations = And | Or | Not | Item
    And = "&" 2*SearchOperations
    Or = "|" 2*SearchOperations
    Not = "!" SearchOperations 
    Item = Operator CompareTo MatchPattern
    Operator = "=" | "!="
    CompareTo = "Source" | "Destination" | "Type"
    MatchPattern = 1*(token | " *") CRLF 
    Scope = "Scope" ":" 1*Digit | "Sub" 

    The SearchPoints are URIs on which the search is to be performed. If at least one URI is not listed in SearchPoints then the search point becomes the request-URI.

    The operator is equals "=" or not equals "!=". Source and Destination equality are dependent upon the type of URIs. Please refer to the definition of the referenced URI type to determine equality rules. The server MUST NOT compare URIs with which it is not familiar. Two types are equal if their tokens are octet for octet equal.

    The MatchPattern allows for wildcard matching. Inserting spaces prevents the wildcard character to not be confused with characters in the token. A wildcard character matches zero or more characters.

    The scope operator specifies how deep into the URI namespace the search should go. A scope of 0 means the search is only on the search point(s). A scope higher than zero means the search should proceed scope levels down the URI namespace. A scope of "sub" means the search should go all the way down to the leaves of the namespace.

    Redirects may only be followed if the new location is within the defined search space.

    3.6.3 Response Body

    The response body will be of type text/html and contain a web collection with type "DAV/LinkSearchResponse". That web collection will itself contain a series of web collections that have the following definition:

    WC Attributes

    Type = "DAV/LinkResponse"

    WCDATA Entry

    Entry = [OnSource] [OnDestination] Type
    OnSource = ["ON"] "Source" ":" URI CRLF
    OnDestination = ["ON"] "Destination" ":" URI CRLF
    Type = "Type" ":" token CRLF

    Each DAV/LinkResponse indicates the source, destination, and type of a link result. The "ON" tag indicates if the source and/or destination is aware of the link's existence.

    3.6.4 Error Conditions

    Editor: these error conditions will be merged with the response codes in the following section in a future rev. of the document.

    URI Doesn't Exist (From Here on Down) (Incomplete) -

    URI Access is Forbidden (From Here on Down) (Incomplete) - 403 Forbidden

    URI Access is Not Allowed (From Here on Down) (Incomplete) - 401 Unauthorized

    URI Not Found (From Here on Down) (Incomplete) - 404 Not Found

    Arbiter does not Support Search on this URI (From Here on Down) (Incomplete) - 406 Not Acceptable

    URI does not Support Search (From Here on Down) (Incomplete) - 405 Method Not Allowed

    URI has been redirected out of search space (Temporarily | Permanently)(From Here on Down)(Incomplete) - 301 Moved Permanently, 302 Moved Temporarily

    Unknown URI Type in Comparison (Include URI)

    3.6.5 Response Codes

    202 Accepted - The request has been accepted and an appropriate response generated.

    203 Non-Authoritative Information - The request has been accepted but the response may be based on outdated or non-authoritative link information.

    413 Request Entity Too Large - The results of the request are larger than the server is willing to return. The request should be made again using an appropriate range header. No body is returned.

     

    3.7 GETLINKS

    3.7.1 Method Definition

    GETLINKS is a convenience method that takes a type and returns a webmap containing link tuples whose source or destination equals the Request-URI and whose type matches the submitted typed.

    3.7.2 Request Body

    The media type of the request body is application/GETLINKS.

    GetLinksMethod = Schema-Version CRLF TaggedType CRLF
    TaggedType = "Type" ":" #type | "All"
    

    3.7.3 Response Body

    A text/html media type containing a web collection of type DAV/GetLinksResponse that contains DAV/LinkResponse entries.

    3.7.4 Response Codes

    See the return codes for the LinkSearch method.

     

    3.8 GETLINKVAL

    3.8.1 Method Definition

    GetLinkVal is a convenience method that takes a type and returns a message/multipart. The first entry in the message/multipart is a Web Collection with link tuples whose source or destination equal the Request-URI and whose type matches the submitted type. The rest of the entries in the message/multipart are the result of a GET submitted on the source or destination of the link that does not equal the Request-URI.

    3.8.2 Request Body

    The request body for method GETLINKVAL is of content type application/getlinkval, defined below:

    GetLinkValMethod = Schema-Version CRLF TaggedType CRLF 
    

    3.8.3 Response Body

    The response body is multipart/related. The first entry is of type text/html containing a DAV/GetLinkValResponse Web Collection containing DAV/LinkResponse web collections. Following the text/html is a series of responses containing GET results.

    3.8.4 Response Codes

    See return codes for the LinkSearch method.

    3.9 SETLINKVAL

    3.9.1 Method Definition

    SETLINKVAL is a convenience method that combines LINK and PUT. It is used to create a link and to specify the contents of one end of the link.

    3.9.2 Request Body

    The request body consists of a MIME multipart. The first entry is the request body contained below which is of type Application/SETLINKVAL. The second entry is the headers and body of the information to be PUT.

    SETLINKVAL = Schema-Version CRLF LINK CRLF PutDestination CRLF ; LINK in Section 3.3.2
    PutWhere = "Put-Where" ":" "Source" | "Destination"

    3.9.3 Response Body

    A web collection that contains the results from LINK and PUT.

    3.9.4 Response Codes

    TBD.

     

    4. Distributed Authoring and Versioning Link Schema

    This section specifies only those link types which are absolutely necessary to implement the functionality described in this specification. Link types other than the ones described within are possible, but must be defined in other documents. Since there are many different possible relationships which can exist between resources, there are many different link types which can exist to describe these relationships. It is difficult, if not impossible to enumerate and describe all of these relationships, especially since the meaning of the same type may vary depending on usage context. This specification has therefore chosen not to try and enumerate all possible link types, instead providing a mechanism for discovering which link types (DAV.SupportedLinkTypes), and which sets of link types (DAV.SupportedLinkSchemas) are supported on a resource.

    A server is not required to support all of the DAV Link Types. However, if a server supports a DAV Link Type, it SHOULD maintain the consistency of that relationship by ensuring the contents of the Destination URI are always up-to-date.

    The DAV Link Types specified in this document form the "DAV" link schema.

    All DAV schema links have a source URI which is the resource being described by the link. The destination URI alway points to a resource whose content type, and contents are described below for each DAV link type.

    4.1 DAV.Versioning.History

    4.1.1 Link Definition

    The history link returns information about the history of a versioned document. This information is contained within a DAG that describes the ancestors and children of various versions in the tree. The history link MUST be defined on the tree handle and SHOULD be defined on individual versions. Versions that do not have a history link MUST have a tree link defined on them.

    4.1.2 Link Type

    The history link has type DAV.Versioning.History.

    4.2.3 Destination Body

    The destination body of the history link is a text/html file containing a series of web collections of type "DAV/History".

    WC Tag Attributes:

    Type = "DAV/History"
    Name = VersionToken

    WCAT Tag Attributes and/or WCDATA Entry:

    Rel = ("ParentEntry" | "ChildEntry" | "SiblingEntry")
    Version = Token
    HREF = Pointer to a web collection w/more information
    Rel = ("Parent" | "Child" | "Sibling")
    Version = Token
    HREF = Pointer to a parent, child, or sibling.

    The Rel/Version/HREF triples above can be used with WCAT or WCDATA. The *Entry links provide pointers to web collections with more information about the family member. The version tag provides the version of the relative being pointed to. The second Rel/Version/HREF triple provides a pointer directly to the versioned resource. All attributes defined on HCs MAY also be used here to provide information such as creation date, author, owner, etc.

    4.2 DAV.Versioning.CheckedOut

    A server MAY create a link of type DAV.Versioning.CheckedOut on the check out root(s), the working resource, or both. The destination resource of a DAV.Versioning.CheckedOut link is of content type application/checkoutresult, which contains the same information as the response body to the CHECKOUT method. invocation which caused the creation of this link. An optional Web Collection attribute, "Principal" may also be included, which holds information about the principal(s) who initiated the check out.

    Principal

    WC Attributes:

  • Type = "DAV/Identifier"
  • WCDATA Attributes:

  • ContactURI = "URI"
  • 4.3 DAV.Versioning.DefaultPublished.

    A server MAY create a link of type DAV.Versioning.DefaultPublished on the version tree handle and all members of the version tree pointed to by the handle. The destination resource of a DAV.Versioning.DefaultPublished link is a member of the version tree, and points to the version which has been designated as being appropriate for display to non-editors. The DAV.Versioning.DefaultPublished destination resource SHOULD be returned to non-DAV aware clients who perform a GET on a version tree handle.

    4.4 DAV.Versioning.NextVersion

    A server MAY create a link of type DAV.Versioning.NextVersion on a versioned resource. The destination resource of a DAV.Versioning.NextVersion link is the version that immediately succeeds the source. A resource MAY have multiple DAV.Versioning.NextVersion links.

    4.5 DAV.SupportedLinkTypes

    Destination resource content type: Web Collection
    Synytax: TBD

    The contents of the destination resource is a list of the link types which the server will definitely allow to be created on the source URI. The server may allow the creation of links with types other than those contained in the destination resource, but this is not guaranteed.

    If a server supports a particular schema, then all link types in the supported schema SHOULD be returned in the destination resource of a SupportedLinkTypes link.

    If a server implements the LINK method, it MUST also implement the SupportedLinkTypes link.

    4.6 DAV.SupportedLinkSchemas

    Destination resource content type: Web Collection
    Syntax: TBD

    The contents of the destination resource is a list of link schemas. If a link schema is listed, it means that the server SHOULD allow the creation of links with types belonging to that schema. The server may allow the creation of links with types which do not belong to a schema listed in the destination resource, but this is not guaranteed.

    If a server implements the LINK method, it SHOULD also implement the SupportedLinkSchemas link.

    5. Relationships

    [Ed. Note: This section will be removed from the spec and appended]

     

    6. Locking

    6.1 Introduction

    The mechanism for locking and unlocking a resource involves the use of a "lock token" (LockToken) which is used to reference the instantiation of the lock. Each lock token instantiates the occurrence of a lock on one resource or a specified portion of a resource (i.e., a lock on a range of a resource). The locking of multiple resources will cause the instantiation of an equal number of lock tokens.

    Lock tokens represent a lock that is specific to the context of a server and therefore can not be transferred to another server. Nor is it allowable to transfer the LockToken to another "client space" even if both are instantiated on the same server. A "client space" is defined as the data space in the context of the client obtaining the lock. More than one thread can be active in a given "client space."

    A mechanism is provided to ensure that a method is executed only if a lock is in place. This mechanism allows a lock header to be included in the method request. The method will be executed only if the LockToken is still valid. Multiple LockTokens may be include in the lock header. Lock headers may reference any LockToken allowing the submission of a method on a resource with a LockToken that refers to another resource.

    A lock may designate "write exclusive" on a given resource. "Write exclusive" is currently the only type of lock supported. A single range for the "write exclusive" lock may be defined and overlapping ranges are never allowed. Thus a lock on the entire resource would be exclusive of any and all range locks on the same resource. Multiple range locks may be instantiated for a given resource (even among multiple "user spaces"), but overlapping ranges are not permitted. The following table describes the allowable states:

    Request

    State

    Result

    full full denied
    full partial denied
    full none granted
    partial full denied
    partial partial granted*
    partial none granted

    * if no overlap

    Once defined the definition of the lock range may not be modified. The only mechanism supported is to release the lock and instantiate a new lock with a defined range.

    The size of a resource may not be changed within the defined region of a lock range unless the range includes +n (n>0) octets beyond the end of the resource (eof). By definition, locking a range beyond the eof provides the owner with the ability to add to the eof and therefore extend the resource.

    If an entire resource is locked and the lock owner deletes the resource then the write lock remains. Further actions on the resource (e.g. PUT) are allowed because the LockToken is still instantiated.

    Each lock may have a time out associated with it. If no time out value is associated with the lock then the lock will never time out (implementors should have some mechanism for destroying a lock at an administrative level). Otherwise the lock will expire if the designated amount of time has elapsed without a method being invoked on the resource by the lock owner. The time out value may be modified without affecting the rest of the the lock by submitting a lock request for the LockToken with no other values associated with it other than a new time out value.

    6.2 LOCK

    6.2.1 Method Definition

    [Ed. Note: Need description of LOCK method.]

    The Request-URI of the LOCK method is the URI of the resource to be locked.

    6.2.2 Request Body

    The lock request specifies the target of the lock, parameters of the lock, and requests that a lock be set on the resource.

    The request body of a LOCK method is of content type application/lock, defined as:

    LockBody = Schema-Version LockEntry CRLF TimeOut CRLF 
               [LockRange CRLF] [LockOwner CRLF]
    LockEntry = "LockEntry" ":" LockWriteExclusive 
    LockWriteExclusive = "write exclusive" 
    TimeOut = "TimeOutSeconds" ":" TimeOutVal 
    TimeOutVal = 1*digit | "Infinite" 
    LockRange = "LockRange" ":" 1*digit "-" (1*digit | "eof++") 
    LockOwner = "LockOwner" ":" URI

    Example:

    LOCK /users/johndoe/davspec.html HTTP/1.1
    Content-Type: application/lock
    Schema-Version: 1.0
    LockEntry: write exclusive 
    TimeOut: 2400 
    LockRange: 100-eof++ 
    LockOwner: mailto:johndoe@foo.com 
    

    6.2.3 Response Body

    The response body of a LOCK method is of content type application/LockResponse, defined below. The syntax of this content type is that of a Web Collection.

    ResourceLockResponse = WC_Open LockResponse WC_Close 
    WC_Open = "<"WC VERSION=<">1.0<"> TYPE=" ("DAV/Lock"|"DAV/Unlock") 
              "<">NAME=<">" LockToken "<">>" 
    LockToken = token
    
    LockResponse = *WCAT LockData *WCAT 
    LockData = "<WCDATA>" LockURI LockBody LockGranted "</WCDATA>"
                ; LockBody production from Section 6.2.2
    
    LockURI = "ResourceLocked" ":" URI
    LockGranted = "LockGranted" ":" RFC1123-date [*digit]  ;*digit for milliseconds
    WC_Close = "</WC>" 

    Example:

    This is a possible response body from the lock request example in Section 6.2.2.

    <WC VERSION="1.0" TYPE="DAV/Lock" NAME="LK_Xj5N75">
    <WCDATA>
    ResourceLocked: http://www.foo.com/users/johndoe/davspec.html
    Schema-Version: 1.0
    LockEntry: write exclusive 
    TimeOut: 2400 
    LockRange: 100-eof++ 
    LockOwner: mailto:johndoe@foo.com 
    LockGranted: Thu, 23 Jan 1997 15:11:27 GMT
    </WCDATA>
    </WC>

    6.2.4 Error Conditions

    Lock already owned:
    Lock range overlaps:
    Invalid range:
    Resource not found:
    Denied:
    General Failure:

     

    6.3 UNLOCK

    6.3.1 Method Definition

    [Ed. Note: Need description of Unlock method]

    The Request-URI of the UNLOCK method specifies the URI of the resource to be unlocked.

    6.3.2 Request Body

    The request body of an UNLOCK method is of content type application/unlock, defined below:

    UnlockRequest = Schema-Version UnLockToken
    UnLockToken = "UnLock-Token" ":" LockToken 
    

    6.3.3 Response Body

    The response body of an UNLOCK method is of content type application/UnlockResult, which is defined by the production ResourceLockResponse, defined in Section 6.2.3.

    6.3.4 Error Conditions

    Lock not found:
    Lock not owned:
    Lock timed out:
    Denied:
    General Failure:

     

    6.4 Lock Discovery

    [Ed. Note: "LockInfo" link and associated "LockDiscovery" WC should be included in the section on DAV Link Schema links]

    6.4.1 Lock Discovery via GetLinkVal

    When a lock is taken out the system SHOULD record who owns the lock. Ownership information can be taken from the From header, from identification provided by authentication, or from the LockOwners field.

    Lock Discovery is enabled via a DAV Schema link of type DAV.LockInfo. Lock Discovery is performed by using the GetLinkVal method on links of this type.

    The LockInfo Link is structured as:

    src = URI of the resource
    dest = URI of the lock discovery WC
    type = "LockInfo"

    6.4.2 Lock Discovery Destination Resource

    The DAV.LockInfo destination resource is of content type text/html, which uses the Web Collection syntax:

    LockDiscoveryResponse = WC_Open LockResponse OtherFields WC_Close 
    WC_Open = "<"WC VERSION=<">1.0<"> TYPE=<">DAV/LockDiscovery<">
              NAME=<">" LockToken "<">>"
    LockResponse = *WCAT LockData *WCAT 
    LockData = "<WCDATA>" LockBody LockGranted "</WCDATA>" 
    LockGranted = RF1123-date [*digit] 
    OtherFields = (implementation specific) * 
    "Owner" ":" 1*octet ** 
    WC_Close = "</WC>" 

    * not negotiable, safely dropped by client
    ** if available

     

    7. Name Space Manipulation

    7.1 COPY

    7.1.1 Method Definition

    This method requests the server to manipulate the mapping for the resource in the namespace such that a new location (mapping) is created for the Request-URI in the namespace, while maintaining the existing location (mapping) in the namespace. The actual implementation is left to the discretion of the server. The presence of hyperlinks within a resource creates special problem in Web resources. The fact that these hyperlinks could be either absolute or relative create yet another level of complexity.

    The Request-URL will be the URL for the source resource which will be copied to the destination. In case of a versioned resource, depending on the implementation, it may be either the root of the version tree, in which case it may mean to copy the whole tree or a specific version (depending on the value of request-version), or it may be the version tree history. In case of non-versioned resource, it will refer to the resourse itself.

    The message body will contain the URL of the destination of the COPY. The OVERWRITE header, as defined by this spec., defines the behavior of the server if a resource already exists as referred to by destination URL. If the value of the overwrite header is true (default), then any existing resource referenced by the destination URL will be overwritten. If the value of overwrite header is false then the copy will fail when the URL of an existing resource matches that of the destination URL. In case of non-versioned collections, COPY can be used as one of the ways to add to the collection.

    7.1.2 Request Body

    The information about the destination and the switch to determine if the links need to copied as well, will be passed in the message body which should be of the content type "application/copy". Also defined in the body is a switch called "copylink". If the value of this switch is set to true, then the server should copy all the links that it deems pertinent. This spec. leaves it to the discretion of the server to determine which links are or are not appropriate in the context of copy. When links are copied the following condition MUST be met:

    The defination of the content type Application/Copy is as follows:

    copy = Schema-Version CRLF destination CRLF copylink CRLF [request-version CRLF]
    Schema-Version = 1*DIGIT "." 1*DIGIT
    destination = "destination" ":" URI
    copylink = "copylink" ":" value
    value = "true" | "false"
    request-version = "Request-Version" ":" token
    

    Note: COPY and Version Trees

    The request-version token may be used to refer to a versioned resource by its version ID, in which case the Request-URI must point to the version tree handle. If the Request-URI points to the version tree handle and the request-version field is not provided, then the whole tree will be copied to the new location.

    The following rules apply when a versioned resource is invloved in a copy operation:

    7.1.3 Response Body

    The response body returns the status code back.

    7.1.4 Error Conditions

    The following status codes may be returned:

    OK - The server has successfully copied the resource, and all the links, if applicable, to the new location in the namespace.

    Copy failed due to some internal error:

    The source is missing
    The desitination exists (and the overwrite switch is false)
    One or more links (in case copylink switch is true) failed to copy due to some internal error.

     

    7.2 COPYHEAD

    7.2.1 Definition

    This is a discovery method to be used with COPY method. Since it is the server's discretion to choose the links that it deems appropriate to copy with the new resource location, these links have to be discoverable. COPYHEAD provides this discovery mechanism to the client. The Request-URI will be the URI for the source resource which will be copied to the destination. In case of a versioned resource, it will be the version tree handle. In case of non-versioned resource, it will refer to the resourse itself. The information about the destination (and the switch to determine if the links need to copied as well) will be passed in the message body which should be of the content type "Application/Copyhead".

    7.2.2 Request Body

    The definition of application/copyhead is exactly the same as application/copy.

    7.2.3 Response Body

    The response will be a Web Collection. It will contain a list of all the links that the server deems appropriate to copy with the destination URI.

    Response = WC_OPEN HEAD_INFO WC_CLOSE
    WC_OPEN = "<WC version="&lt;&quot;"> 1.0 <"> Type = <"> "("DAV/COPYHEAD" | "DAV/MOVEHEAD")" <">>"
    HEAD_INFO = REQUEST RESPONSE_CODE LINK_RESPONSE TIME_STAMP
    WC_CLOSE = "</WC>"
    REQUEST = "<WCDATA>" REQ_BODY "</WCDATA>"
    REQ_BODY = actual request line and headers (without any message body) 
               of the COPY request for which the discovery is being made.
    RESPONSE_CODE = "<WCDATA>" CODE "</WCDATA>"
    CODE = exact copy of HTTP status line.
    LINK_RESPONSE = Web Collection response format for each link (see section on LINK) 
    TIME_STAMP = "<WCDATA>" TIME "</WCDATA>"
    TIME = "Time" ":" RFC 1123 date [*digit]

    To copy a resource pointed to by http://foo.bar.com/foobar.html, with a link of the type "Author" and destination URI http://foo.bar.com/junk, the copyhead response will be as follows:

    <WC version="1.0" Type="DAV/COPYHEAD"> 
    <WCDATA> 
    COPYHEAD http://foo.bar.com/foobar.html HTTP/1.1 
    Content-type : application/copyhead 
    {instance of content type application/copy goes here}
    </WCDATA> 
    <WCDATA> Status : 200 OK </WCDATA> 
    <WC version="1.0" Type="DAV/LINK"> 
    <WCDATA> 
    ON Source : http://foo.bar.com/foobar.html 
    Dest : http://foo.bar.com/junk 
    Type : Author 
    </WCDATA> 
    </WC> 
    <WCDATA> Time : some time value </WCDATA> 
    </WC>
    

    7.3 MOVE

    7.3.1 Method Definition

    This method requests the server to manipulate the resource/namespace mapping; a new location (mapping) is created for the Request-URI in the namespace, and the existing location (mapping) in the namespace is removed. The actual implementation is left to the discretion of the server.

    Move can be considered as an atomic, logical operation combining a COPY followed by a DELETE on the source URI. This means MOVE inherits all the complexities of COPY operation, and add a few more of its own due to the fact that it changes the resource location in the namespace.

    For instance: from the perspective of the client, a MOVE on a resource may result in a REDIRECT to the new location namespace. WEBDAV does not require a server to issue a redirect on "moved" URIs in order to be compliant, but one might argue that some sort of discovery for "server capability" be provided.

    Also there is an issue of "level of intelligence" of move. One argument is that due to the special nature of HTML media types, move should automatically perform some link management on links after a MOVE. While it is impossible to manage all links pointing to a resource due to lack of control over all of the links pointing to the resource, it is conceivable that links from a resource, and links within a resource might be manageable. The opposing argument to this is that allowing a move operation to have side-effects which could modify the resource being moved - or worse yet modify resources which were not being moved - can have unexpected consequences. It is important to know the consequences of an operation before executing the operation.

    WEBDAV is silent on MOVE/link interaction issues, specifying a simple MOVE with a discoverable list of links to be moved with the resource. Beyond that WEBDAV does not make any recommendation or suggestions about the actual implementation of the MOVE operation.

    In case of non-versioned collections, move can be used as one of the ways to add to the collection.

    7.3.2 Request Body

    This section defines the content type application/move.

    Move = Schema-Version CRLF destination CRLF movelink CRLF [request-versionCRLF]
    Schema-Version = 1*DIGIT "." 1*DIGIT
    destination = "destination" ":" URL
    movelink = "movelink" ":" value
    value = "true" | "false"
    request-version = "Request-Version" ":" token
    

    Note: COPY and Version Trees

    The request-version token may be used to refer to a versioned resource by its version ID, in which case the Request-URI must point to the version tree handle. If the Request-URI points to the version tree handle and the request-version field is not provided, then the whole tree will be moved to the new location.

    The following are the rules that apply when a versioned resource is invloved in a move operation:

    7.3.3 Response Body

    The response body returns the status code.

    7.3.4 Error Conditions

    The following status codes may be returned:

    OK - The server has successfully moved the resource, and all the links, if applicable, to the new location in the namespace.

    Move failed due to some internal error:

     

    7.4 MOVEHEAD

    7.4.1 Header Definition

    This is a discovery method to be used with MOVE method. Since it is the server's discretion to choose the links that it deems appropriate to move with the new resource location, these links have to be discoverable. MOVEHEAD provides this discovery mechanism to the client. The Request-URI is the URI for the resource to be moved. In case of a versioned resource, it will be the version tree handle. In case of non-versioned resource, it will refer to the resourse itself. The information about the destination (and the switch to determine if the links need to moved as well) are passed in the message body (content type "Application/Movehead").

    7.4.2 Request Body

    The definition of application/movehead is exactly the same as move

    7.4.3 Response Body

    The response is a Web Collection of type DAV/MOVEHEAD with BNF identical to that for DAV/COPYHEAD. It will contain a list of all the links that the server deems appropriate to move with the destination URI.

    To move a resource pointed to by http://foo.bar.com/foobar.html, with a link of the type "Author" and destination URI http://foo.bar.com/junk, the movehead response will be as follows:

    <WC version="1.0" Type="DAV/MOVEHEAD"> 
    <WCDATA> 
    MOVEHEAD http://foo.bar.com/foobar.html HTTP/1.1 
    Content-type: application/movehead 
    {instance of application/move goes here.}
    </WCDATA> 
    <WCDATA> Status : 200 OK </WCDATA> 
    <WC version="1.0" Type="DAV/LINK"> 
    <WCDATA> 
    ON Source : http://foo.bar.com/foobar.html 
    Dest : http://foo.bar.com/junk 
    Type : Author </WCDATA> 
    </WC> 
    <WCDATA> Time : some time value </WCDATA> 
    </WC>

     

    7.5 DESTROY

    To destroy a resource is permanently remove a resource from storage. To delete a resource is to request that the resource no longer be made available for editing. Destory differs from delete in that a versioning system may allow a deleted resource to be visible, but not editable, while a destroy causes the resource, and all knowledge about the resource to be removed from the server.  A destroy is performed by the DESTROY method. The request-URI of the DESTROY method is the resource to be destroyed.

     

    7.6 UNDELETE

    An undelete undoes the action of a delete, making a deleted resource available for editing.  An undelete is performed by executing the UNDELETE method. The request-URI is the resource to be undeleted.

     

    8. URI Collections

    8.1 URI Collection Behavior

    According to The Random House College Dictionary - Revised Edition, Collection is defined as "2. Something that is collected, as a group of objects..." In the most generic sense a URI Collection brings together a group of URIs and provides information about them. This specification will not be defining such a collection, mostly because it is a pretty idea with no where to go. At least for now. In the future systems will be available that will be able to make profitable use of a generic collection. For now this specification defines the Hierarchical Collection (HC). The HC is meant to walk, talk, and look just like a directory in a file system. URIs are added to an HC as either relative or absolute. All relative URIs in an HC are relative to the Request-URI. This restriction is in place in order to replicate normal file system behavior. Thus if the collection is copy, moved, or otherwise manipulated within the name space it will be possible to copy, move, etc. its component parts. This behavior is referred to as propagation. The idea is that a command executed on the collection can be propagated to all the relative URIs. The PropagateLevel header controls propagation behavior. This header specifies the number of levels a command should be propagated. Absolute URIs are added as links and thus commands are not propagated through them. Thus, if a collection is copied, the COPY method will be executed on all the relative URIs but not on the absolute URIs. Of course all the absolute URI entries will still be members of the collection, they simply won't have the COPY method executed on them.

    Executing the MAKECOLLECTION method creates HCs. This is the same as executing a MKDIR on a file system. If a MAKECOLLECTION is executed on a Request-URI which is not itself a member of a collection then either the system will automatically create all the necessary collections or it will reject the method. Once the collection is created any URI PUT under the collection's namespace will "magically" appear inside the collection. Again, this behavior mimics that of a normal file system. Adding a relative URI directly to a collection will either be rejected or cause a NULL file to appear. Removing a URI directly from a collection will cause a link to disappear in the case of an absolute URI or will cause the file to be deleted in the case of a relative URI.

    8.2 CREATECOLLECTION Method

    8.2.1 Method Definition

    The CREATECOLLECTION method indicates to the server that the clients wishes a specified URI to act as a collection.

    8.2.2 Request Body

    The contents of message/collection identify what sort of collection is being created. This document defines the Hierarchical Collection (HC). A HC only supports a hierarchical name space and is meant to replicate the behavior of a file system directory.

    A HC contains URIs. URIs may be entered as relative or absolute. Relative URIs must be relative to the request-URI. A relative URI is a propagate entry. If a PropagateLevel header is included with a method executed on a HC then the method will be propagated through all relative URIs. Absolute URI entries do not propagate.

    MessageCollection = Version CRLF CollectionType CRLF
    CollectionType = "Collection Type" ":" ("HC" | Text)

    8.2.3 Response Body

    CREATECOLLECTIONERROR = WC_OPEN Type WC_CLOSE
    ContentError = "DAV/Error/CreateCollection"
    Type = "Do Not Support Type" ":" ("HC" | Text)

    8.2.4 Response Codes

     

    8.3 ADDRESOURCE

    Editor: this section needs to incorporate the correct text from Yaron.

    8.3.1 Content Type Definition

    This content type is used to add a link to a collection. In the case of an HC most systems will not accept a relative URI. Rather, to add a new entry to an HC, the resource should be created using a PUT or similar method. If the server does accept a relative URI for an HC then the result SHOULD be the creation of an empty resource.

    8.3.2 Request Body

    AddResource = Version CRLF URIType CRLF URIEntry CRLF
    URIType = "Type" ":" ("Relative" | "Absolute")
    URIEntry = "URI" ":" (relativeURI | absoluteURI)

    URIType indicates the type of URI while URIEntry indicates the actual URI. URIType is included for negotiation purposes. If the URI is relative then it is relative to the request-URI. The productions relativeURI and absoluteURI are defined in section 3.2.1 of rfc2068.

    8.3.3 Response Body

    The content type of the response body is text/HTML and contains a Web collection.

     

    8.4 REMOVERESOURCE

    8.4 1 Method Definition

    This content type is used to remove a URI from a collection. In the case of an HC most systems will not accept a relative URI. Rather, to delete an HC entry, the resource should be DELETEd or DESTROYed. If the server does accept a relative URI for an HC then the result SHOULD be the deletion of the resource.

    8.4.2 Request Body

    RemoveResource = AddResource

    8.4.3 Response Body

    The content type of the response body is text/HTML and contains a Web collection.

     

    8.5 PropagateLevel Header

    8.5.1 Header Definition

    The PropagateLevel header controls how many levels a method will be propagated down a collection. Zero means the method should only be executed on the collection. Infinity means the method should be propagated as far down as possible. A loop is impossible with HCs because its name space is a tree and absolute URIs do not propagate. Other collection types will have to define their own mechanisms to detect and prevent loops.

    8.5.2 Request Body

    PropagateLevel = "PropagateLevel" ":" (1*Digit | "Infinity")

    8.5.3 Response Body

    The following web collection can be included in any web collection based body.

    WC Attributes

    Type = "DAV/Error/Prop/FailedAt"

    WCDATA Entry

    Entry = "Propagation Mechanism Failed at" ":" *(Relative | Absolute_URI CRLF)
    Relative = "Base" ":" Absolute_URI "Relative" ":" *Relative_URI CRLF

     

    9. Version Control

    9.1 Introduction

    This specification provides interface definitions which clients may use to perform the common versioning operations check in, check out, version history retrieval, and merge. A fundamental assumption of this specification is that the semantics of versioning operations are defined by the server, and may vary from server to server, depending on the versioning engine employed. As a consequence, this specification provides a common interface for accessing the functionality of many different versioning engines.

    Since versioning functionality may vary from server to server, or even in different namespaces on the same server, a discovery mechanism is provided for clients to determine precisely what effect a CHECKOUT or a CHECKIN method invocation will have on the state of the server. A client may query the server for its CHECKIN and CHECKOUT semantics by retrieving the destination resource of the DAV.Discovery.CHECKOUT and DAV.Discovery.CHECKIN links. It is expected that a client will query the value of the DAV.Discovery.CHECKOUT link before performing a check out, and the DAV.Discovery.CHECKIN link before performing a check in, so it knows exactly what will occur when it issues the CHECKOUT or CHECKIN request.

    Similarly, the who and when of setting a version identifier varies significantly:

    1. A version identifier MAY be specified by the client upon check out.
    2. Upon check out, the server MAY accept the client version identifier, or the server MAY assign a version identifier, or the server MAY not assign any version identifier.
    3. If the version identifier has not already been set, the client MAY specify a version identifier upon check in.
    4. Upon check in, the server MAY accept the client version identifier, otherwise the server MUST assign a version identifier unless one has already been assigned (e.g., during check out).

    9.2 Versioning Data Model

    A version tree is a directed acyclic graph of versioned resources. Arcs in the version graph indicate "is-version-of" (or "is-successor-of") relationships. Each versioned resource is a first-class resource, addressable by a URI. A version tree MUST have a handle resource, known as the version tree handle, which is used to refer to the version tree as a whole. The contents of the handle resource MUST be a single URI (a pointer), which is used by the versioning engine to identify the version tree as a whole. The version handle resource MAY point to either the root object of the version tree, or the history resource for the version tree.

    The version tree handle MUST have server generated links of type DAV.Versioning.DefaultPublished, DAV.Discovery.CHECKIN, and DAV.Discovery.CHECKOUT, and MAY have a server generated link of type History. Each versioned resource MAY have server generated links of the following types: DAV.Versioning.History, DAV.Versioning.DefaultPublished, DAV.Versioning.NextVersion, DAV.Discovery.CHECKOUT, DAV.Discovery.CHECKIN.

    Versioning is an orthogonal issue to content negotiation. Each particular variant of a resource MAY be independently versioned, and MAY have its own version tree.

    TBD: A Figure showing a sample version tree (using text characters)

     

    9.3 CHECKOUT

    9.3.1 Method Definition

    A CHECKOUT is a declaration by a client that it might edit a versioned resource. The CHECKOUT method is intended to map to the notion of check out supported by the server's versioning engine. The Request-URI of the check out method is a version tree handle, which identifies the version tree on which the CHECKOUT will be performed.

    A server MAY create a working resource as the result of a check out. If the server creates a working resource, it MUST return the URI of this resource in the response body.

    All of the activity which occurs during CHECKOUT method invocation MUST be performed atomically.

    9.3.2 Checkout Capability Discovery

    Editor: this section will be subsumed by a more general method discovery mechanism.

    9.3.3 Request Body

    The request body of the CHECKOUT method is of content type application/checkout, defined as:

    Checkout        = Schema-Version CRLF [Derived-From CRLF] [Request-Version CRLF]
                      [Request-Lock CRLF] [Request-Intent CRLF] 
                      [Request-Working-Loc CRLF] [Request-Visibility CRLF]  
    Schema-Version  = "Schema-Version" ":" 1*DIGIT "." 1*DIGIT
    
    Derived-From    = "Derived-From" ":" #token
    
    Request-Version = "Request-Version" ":" token
    
    Request-Lock    = "Request-Lock" ":" "Exclusive" "Write"
    
    Request-Intent  = "Request-Intent" ":" ("true" | "false")
    
    Request-Working-Loc = "Request-Working-Loc" ":" ("Client" | "Server")
    
    Request-Visibility = "Request-Visibility" ":" Visible-When [Visible-Where]
    Visible-When    = ("Always" | "If_Locked" | "Never") 
    Visible-Where   = ("On_CheckOut_Root" | "On_Working" | "On_Both")

    The Schema-Version is the version number of the syntax specification of the application/checkout content type.

    Derived-From specifies the version identifier of the check-out root(s) from which the working resource (if it exists) is derived. If more than one version identifier is specified in the Derived-From value, the working resource MAY be the result of a merge of the specified versions, and the exact semantics of this merge operation will vary across versioning engines.

    Request-Version specifies a client's request to set the version identifier of the working resource. The server MAY set the version identifier of the working resource to this value. If this field is omitted from the request message body, the server MAY perform a check out from a default check out root (often the latest version).

    Request-Lock is used by the client to request a lock when a server supports optional locking on check out.

    Request-Intent is used by the client to request the server to establish an intent to edit on check out. An intent to edit MAY result in the association of authentication or user information with either the check out root, or the working resource.

    Request-Working-Loc is used by the client to request where the working resource is located. If the client specifies "Client," then the server SHOULD not create a working resource on the server. If the server does not create a working resource on the server, the client SHOULD retrieve its working resource from the check out root after successful completion of the CHECKOUT. If the client specified "Server," then the server SHOULD create a working resource on the server.

    Request-Visibility is used by the client to request whether to create a DAV.Versioning.CheckedOut link, and the resource which will store the link. Visible-When describes whether the DAV.Versioning.CheckedOut link SHOULD always be created ("Always"), SHOULD only be created if the check out performs a lock ("If_Locked"), or SHOULD never be created ("Never"). Visible-Where describes where the link SHOULD be stored: on the check out root ("On_CheckOut_Root"), on the working resource ("On_Working"), or on both the check out root and the working resource.

    9.3.4 Response Body

    The response body of a CHECKOUT method invocation is of content type application/checkoutresult, defined as:

    CheckoutResult     = WC-Open CheckoutResultData WC-Close
    
    WC-Open            = "<WC VERSION =<">1.0<"> TYPE =<">DAV/CheckoutResult<">>"
    
    CheckoutResultData = *WCAT WCCheckoutData WCAT
    
    WCAT               = {arbitrary, server-defined Web Collection attributes}
    
    WCCheckoutData     = "<WCDATA>" DerivedTree DerivedRoot [WorkURI]
    
                         [WorkVersion] [Visibility] "</WCDATA>"
    
    
    
    DerivedTree        = "Derived-Tree" ":" URI CRLF
    
    DerivedRoot        = "Derived-Root" ":" #URI CRLF
    
    WorkURI            = "Working-URI"  ":" URI CRLF
    
    WorkVersion        = "Working-Version" ":" token CRLF
    
    Visibility         = "Visibility" ":" ( Visibility-Where | "Never" ) CRLF
    
    WC-Close           = "</WC>"

    Derived-Tree is the location of the version tree handle on which the check out was performed.

    Derived-Root is the location of the (possibly many) versioned resources on which the check out operation was performed.

    WorkURI is the location of the working resource generated by the server on check out, if it exists.

    WorkVersion is the version identifier of the working resource, if it was set on check out.

    Visibility is the location where the client can retrieve the DAV.Versioning.CheckedOut link.

    9.3.5 Error conditions

    An error condition occurs if the following conditions hold:

    If a client requests a version identifier on check out, but the server:
    a) cannot set a version identifier
    b) refuses to set a version identifier

    If a client requests a lock, but the server doesn't support locking.

    If the client requests an intent to edit, but the server doesn't support intent to edit.

    If the client doesn't specify a Derived-From version, and the server has no default value.

    Syntax error in the request body. If a client requests a feature the server doesn't support then it has committed a syntax error because the discovery told the client what the server supports.

     

    9.4 CHECKIN

    9.4.1 Method Definition

    A CHECKIN is a declaration by a client that it wishes to place a resource under version control. The CHECKIN method is intended to map to the notion of check in supported by the versioning engine. The Request-URI for a CHECKIN method invocation is the version tree handle of the version tree which is being operated on.

    A check in SHOULD clear any server state which is set as a result of a check out. For example, if a server locks a resource on check out, it should remove the lock upon check in.

    To place a resource under version control for the first time, a check in is performed on the resource. In this case, the Request-URI is the desired location of the version tree handle, and the Working-URI or the check in body gives the contents of the resource to be placed under version control.

    All of the activity which occurs during CHECKIN method invocation MUST be performed atomically.

    9.4.2 Checkin Capability Discovery

    Editor: this section will be subsumed by a more general purpose discovery mechanism

    9.4.3 Request-Body

    The request body of a CHECKIN method invocation MUST be in one of two forms:

    1. An entity of content type application/checkin
    2. An entity of content type multipart/related, with two parts, an entity of content type application/checkin, and a second entity, of any content type, containing a check in body.

    If the request-body is of content type multipart/related, the checkin operation is defined to be a PUT of the checkin entity body (into a server-dependent temporary resource), followed by a CHECKIN.

    The definition of content type application/checkin is:

    CheckIn          = Schema-Version CRLF [Derived-From CRLF]
    
                       [Working-Resource CRLF] [Request-Version CRLF] 
    
                       [Check-In-Location CRLF]
    
    
    
    Schema-Version   = "Schema-Version" ":" 1*DIGIT "." 1*DIGIT
    
    Derived-From     = "Derived-From" ":" #token
    
    Request-Version  = "Request-Version" ":" token
    
    Working-Resource = "Working-Resource" ":" ( "[" URI "]" ) | 
    
                       ("VersionID" ":" token) | "BODY"

    The Schema-Version is the version number of the syntax specification of the application/checkout content type.

    Derived-From specifies the version identifier of the check-out root(s) from which the working resource (if it exists) is derived. If more than one version identifier is specified in the Derived-From value, the checked-in resource MAY be entered as the successor of the Derived-From resources.

    Request-Version specifies a client's request to set the version identifier of the check in resource. The server MAY set the version identifier of the check in resource to this value. If this field is omitted from the request message body, the server MUST set the version identifier if it has not previously been set.

    Working-Resource specifies a URI or a version identifier of the working resource which is to be checked-in. If the value is "BODY," the working resource is contained in the check in body.

    Open issues: 1 - If a version has multiple parents the client wants to know where the version links will go. If the system supports multiple inheritance then that needs to be stated. If the system only supports single inheritance then the client needs to know, before hand, which version the new version will be linked to. 2 - The syntax allows a client to specify different derived-from resources on Check In then were listed on Check Out. Somewhere there is a versioning system that doesn't allow this. The client needs to know this fact before performing the check out.

    9.4.4 Response Body

    There is no response body defined for the CHECKIN method.

    9.4.5 Error Conditions

    If the Derived-From token(s) do not exist,

    If the working URI is not located on this server, or the server is not authorized to retrieve the working URI.

    If the PUT of the checkin entity body fails.

    Syntax error in the request body.

     

    9.5 DIFF/MERGE

    9.5.1 Introduction

    The request-URI of the DIFF method is an arbiter. The arbiter will compare the entries and return the differences between them.

    The request-URI of the MERGE method is also an arbiter. The arbiter will combine the entries and return the result.

    The Application/Diff content-type works with the DIFF method. The Application/Merge content-type works with the Merge method.

    Application/Diff = Body
    Application/Merge = Body
    Body = 1#("URI" ":" URI | "Entity" ":" entity-body)

     

    9.5.2 SERVERMERGE

    9.5.2.1 Method Definition

    The SERVERMERGE method requests that the server merge a number of entities on behalf of the client. The request-URI is a server side arbiter who performs the merge on behalf of the client.

    9.5.2.2 Request Body

    The request body may take on one of two possible formats. One format is application/servermerge, which is defined below. The second format is message/multipart related which will contain an entry of type application/servermerge as well as entities for the server to merge.

    Type = application/servermerge

    Merge = Schema-Version CRLF MergeType CRLF [MergeEntities CRLF] 
            ReturnType CRLF [ReturnURI CRLF]
    MergeType = "Merge Types" ":" ("URIs" | "Bodies" | "URIs" "Bodies")
    MergeEntities = "Merge Entries" ":" #URI
    ReturnType = "Return Result" ":" ("URI" | "Body")
    ReturnURI = "Return Location" ":" URI

    MergeType specifies what mechanisms are being used to refer to bodies to be merged. URIs means that a MergeEntities has been included while Bodies indicates that one or more message/multipart related have been included. ReturnType specifies how the results are to be returned, either as part of the response or recorded in a URI. ReturnURI specifies the URI for the result to be recorded in if the user selects that return mechanism. A server MAY support any combination of values for MergeType and ReturnType. It MUST provide for discovery of supported values.

    9.5.2.3 Response Body

    Only support # bodies to be merged

    Can not resolve URI

    Can not store in URI

    Can not merge included types

    Merge Failed

    Merge Succeeded

    9.5.2.4 Response Codes

    [Will fold in from above.]

     

    9.6 Command Comments

    Command comments are entity headers.

    Command_Comment = "Comment" ":" CommentVal
    CommentVal = URI | comment

    This is the standard comment facility used by versioning systems. Servers that do not understand the header or do not wish to make use of the information are free to ignore the information. No specification is made regarding how this information is to be retrieved. It is likely, however, that most systems will make the command comments available through their history attribute.

    9.7 FREEZE (a.k.a. UNVERSION)

    Editor: this method should be viewed as proposed functionality.

    9.7.1 Method Definition

    This method request the server to freeze the version tree in the current state, and copy the default published version outside of versioning space so that it is accessible as an unversioned resource to the client. After the version tree is frozen, the clients will not be able to perform any operation except CHECKIN at which time the tree will be taken out of the frozen state and put back into the version space. The Request-URI is the URI of the version tree handle.

    9.7.2 Request Body

    None.

    9.7.3 Response

    The response will only consist of the status code as returned by the server.

    9.7.4 Error Conditions

    The error codes could any of the following:

    OK - the server successfully froze the version tree and copied the Default Published Version into non-version space.
    FREEZE failed because the server could not freeze the tree.
    FREEZE failed because the server could not copy the default published version to unversioned space
    FREEZE failed because the server could not determine the Default Published Version
    The source (tree) is missing

    10. Ancillary Methods and Headers

    10.1 MaxLength Header

    10.1.1 Header Definition

    The max length header requests that the server not return any results greater than specified in the header. The header also specifies if partial results are preferred to no results in the case when the result entity is greater than allowed by the header.

    10.1.2 Header Body

    MaxLengthHeader = "MaxLength" ":" Size Partial CRLF
    Size = "Size" ":" Bytes-Unit 1*Digit
    Partial = "Partial" ":" ("Acceptable" | "Not Acceptable") 

     

    10.2 If-Lock Header

    10.2.1 Header Definition

    The If-Lock header makes any request to which it has been appended conditional on the lock(s) referred to by the included token(s) still being active. This header can not be dropped.

    10.2.2 Header Body

    IfLockHeader = "If-Lock" ":" #LockToken CRLF 

     

    10.3 Command-Comments Header (CCMD)

    10.3.1 Header Definition

    Command-Comments (short form CCMD) is a request-header which is used to transmit comment information on any HTTP request method to the server. The server MAY provide persistent storage for the comments. The server MAY log the comments. The server MAY ignore the comments.

    10.3.2 Header Body

    The definition of the syntax of the Command-Comments header is as follows:

    CommandComments  = ("CCMD" | "Command-Comments") ":" LangTaggedString
    
    LangTaggedString = Lang UTF-8   ; See RFC 2044 for UTF-8 definition
    Lang             = "(" LangTag ")"
    LangTag          = 1*8ALPHA *("-"1*8ALPHA)

     

    10.4 Overwrite Header

    10.4.1 Header Definition

    Overwrite is a request-header which specifies whether the destination of the method should or should not be overwritten.

    10.4.2 Header Body

    Overwrite = "Overwrite" ":" ("Yes" | "No")

    If the value of Overwrite is "Yes," a destination resource will be replaced if it exists. If the value of Overwrite is "No," the server will not replace the destination resource if it exists.

    This header may be applied to the PUT method, and thus modifies the definition of PUT given in Section 9.6 of [HTTP/1.1].

    APPENDIX

    A. Definition of LinkSearch Header

    Editor: This is a proposed feature.

    The LinkSearch method can be expensive, especially when a number of attributes must be retrieved over time.

    A more economical mechanism is to append a search string to URL using "?". However, the URL could be confused with any of a number of search syntax's. The solution proposed by this document is to create a new header called LinkSearch.

    LinkSearch = "LinkSearch" ":" HTTP_url ; See section 3.2.2 of [HTTP11]

    If the HTTP URL does not end in a "/" then a "?" may be appended to it and the attribute search syntax defined below may be used to search for attributes on that particular resource. If the URL does end with a "/" then any resource whose name is a child of the specified HTTP URL may be searched on directly.

    To perform a search a string matching the following syntax should be used.

    LinkSearchSuffix = "?" Attribute
    Attribute = token

    So, if the LinkSearch value is http://foo/bar then a search on a link type of author would be performed using http://foo/bar?author. If the returned value is http://foo/bar/ then the author search may be performed on http://foo/bar/?author and any of its children, such as http://foo/bar/doublebar?author.

    By returning the LinkSearch header the server is agreeing to manipulate the search URL as it would the URL of the resource it resolves to. Thus it becomes the responsibility of the server to resolve the search URL whenever it is included in a command.

    If it is impossible to resolve the search request to a single result then a 416 Not Unique error should be returned. This error specifies that the URI was not resolvable to a unique resource.

    If the search URI does not resolve to any attribute then any request containing that URI should return a 404 Not Found error.

    B. Definition of LinkPrefix Header

    Editor: this is a proposed feature.

    In some cases a server may have an arbiter which handles all searches on resources. To allow for the use of the arbiter but still gain the advantages of URL based searching the LinkPrefix is introduced.

    LinkPrefix = "LinkPrefix" ":" HTTP_url

    To retrieve a particular attribute the following syntax should be used:

    LinkPrefixSuffix = "?" URL LinkSearchSuffix

    Thus the returned URL has the URL to be searched on appended to it followed by the actual search syntax as previously specified. This allows for quick retrieval of attribute values but with the benefit of processing requests at a single resource.

    The URI returned by LinkPrefix has the same use semantics as the URI returned by LinkSearch.

     

    Required Features

    [Ed. Note: preliminary and incomplete]

    Introduce the concept of Distributed Authoring compliance, Versioning compliance, and totally optional features. Use the list from presentation.

    Acknowledgements

    [Ed. Note: preliminary and incomplete]

    Roy Fielding, Richard Taylor, Larry Masinter, Henry Sanders, Judith Slein, Dan Connolly, David Durand, Henrik Nielsen, Paul Leach. Kenji Ota, Kenji Takahashi. Jim Cunningham. Others, TBD.

    References

    [Ed. Note: preliminary and incomplete]

    [HTTP11] R. T. Fielding, J. Gettys, J. C. Mogul, H. F. Nielsen, and T. Berners-Lee. "Hypertext Transfer Protocol -- HTTP/1.1" Internet-Draft draft-ietf-http-v11-spec-07.txt, expires February 12, 1997.

    [ORANGE] DoD 5200.28-STD, "Department of Defense Trusted Computer System Evaluation Criteria", December, 1985.

    [RFC1521] N. Borenstein, N. Freed. "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies." RFC 1521, Bellcore, Innsoft, September, 1993.

    [URL] T. Berners-Lee, L. Masinter, M. McCahill. "Uniform Resource Locators (URL)." RFC 1738, CERN, Xerox PARC, University of Minnesota, December, 1994.

    [RFC1959]

    [RFC1960]

    [WEBC] - References to web collections.