WEBDAV Working Group Y. Goland, Microsoft INTERNET-DRAFT E. J. Whitehead, U.C. Irvine A. Faizi, Netscape D. Jensen, Novell Expires May 25, 1997 November 26, 1996 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 , which may be joined by sending a message with subject "subscribe" to . Discussions of the WEBDAV working group are archived at . The HTTP working group at also discusses the HTTP protocol. Discussions of the HTTP working group are archived at . General discussions about HTTP and the applications which use HTTP should take place on the mailing list. Abstract WEBDAV is a set of application-level protocol methods and types Goland, et al 1 INTERNET-DRAFT WEBDAV November 26, 1996 which provide core functionality for distributed authoring and version control. It is intended to mediate client/server transactions providing support for effecting Distributed Editing, managing and using Meta Data, manipulating Namespaces, and effecting Version Control. WEBDAV is not a stand-alone protocol. Rather, it is an extension of HTTP/1.1 [HTTP11], and as such strives to conform (where possible and reasonable) with those attributes which characterize the essential nature of HTTP/1.1; namely, to be generic, stateless, and object-oriented. The WEBDAV strategy is to 1. Implement methods where possible (object-oriented), 2. Leverage links (as defined in [HTTP11]). 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 [draft-durand- http-webdav-??]. 1.2 Terminology Unless otherwise noted, the use of terminology in this document is consistent with the definitions of terms given in [HTTP11]. 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 2, Attributes. attribute set An attribute set is a collection of attributes. See section 2.4, Standard Attributes. set edit announcement A set edit announcement is a declaration by a principal that they intend to edit a resource. No action other than Goland, et al 2 INTERNET-DRAFT WEBDAV November 26, 1996 the declaration is implied by a set edit announcement. See section 8.1, Set Edit Announcement/Remove Edit Announcement. remove edit announcement A remove edit announcement is a declaration by a principal that they no longer intend to edit a resource. See section 8.1, Set Edit Announcement/Remove Edit Announcement command comments Command Comments associate either a string or a URI with an HTTP message. See section 9.1, Command Comments. 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 4.1, Copy. collection A group of URIs which are manipulated as a unit. Please see section 7, URI Collections. 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 4.2, Destroy. diff A diff is a mechanism whereby two or more resources are compared and the differences enumerated. See section 8.2, Diff. history A history lists the URIs of the versions of a resource along with related information. See section 9.2, History. 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 8.3, Merge. move Goland, et al 3 INTERNET-DRAFT WEBDAV November 26, 1996 A move is logically an atomic action consisting of a copy followed by a delete of the source resource. See the definition of copy in this section. Also see section 4.4, Move. 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 3, Lock. notify request A notify request instructs the recipient to send information regarding the progress of a request. See section 6.1, Notify Request. 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 3, Lock. redirect A redirect instructs a server to return one of the 3xx series codes. See section 4.5, Redirect. relationship A relationship is a unidirectional typed link. See section 5, Relationships. shared mode Shared mode modifies a lock request such that the lock may be shared between multiple principals. See section 3, Lock. write lock A write lock prevents principals who do not possess a write lock on a resource from editing that resource. See section 3, Lock. 1.3 Notational Conventions and Generic Grammar This specification uses the Augmented BNF and Basic Rules as defined in Section 2 of [HTTP11]. Goland, et al 4 INTERNET-DRAFT WEBDAV November 26, 1996 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. 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. 2. Methods should only perform a single action. 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. 3. URLs are opaque tokens and should be treated as such. 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. 4. Only addressable entities will be subject to the commands in this document. Goland, et al 5 INTERNET-DRAFT WEBDAV November 26, 1996 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. 5. This document will only specify client to server communication. Some of the actions possible in this document require server to server communication in order to be effectively implemented. For example, atomically locking two resources that reside on two different servers. This document will not specify such interactions. Rather this document will specify how such requests are made by a client of a server. 2. Message/Multipart [TBD. Specify a mechanism for bundling a bunch of HTTP messages together. Should contain a switch to indicate if the messages must all be executed atomically or rejected. Also need to define a message/multipart response type so we can bundle together all the responses. Must stipulate that there will be a single response for the multipart message itself and then a bunch of sub responses for everything contained in the multipart. Explain the idea that if you combine a bunch of methods atomically it is possible to define semantics for that particular combination and order. Example: a notify followed by a lock followed by a GET all wrapped in an atomic package means CheckOut with all the connotations.] 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 to recreate the link facility already existing in HTML. This document proposes a more powerful link facility which specifies that links are typed and directional. 3.2 Link Types Goland, et al 6 INTERNET-DRAFT WEBDAV November 26, 1996 Links are typed. These types explain the purpose and behavior of a link. When a server allows a link of a particular type to be created it is accepting a contract, it is saying that it understands the type of link being created and is willing to enforce its semantics. Link types should be thought of as inheritable objects. It is completely reasonable to create a new type of link by specifying that it inherits the features of one or more links. 3.3 Definition of Link/Unlink Methods The link method creates or modifies a link. The unlink method removes links. The request-URI is the resource which should record the link. 3.4 Definition of Content Type Message/Link A message/link MIME type contains a request to create a single undirectional link. If a link type is defined so as to require a bidirectional link then message/multipart with an atomic indication can be used to create both directions of the link. Link = [(Source | Destination)] Type Type = Text Source = "Source" ":" URI Destination = "Destination" ":" URI Which ever URI is included in the content-type, the request-URI is the other end of the link. If a source or destination is not included then the request-URI is both. 3.5 Definition of Content Type Message/LinkResult It is often the case that a resource is created solely to act as the source or destination of a link. It is also often the case that because of the underlying implementation a server can only accept certain kinds of links if the source or destination exists within a certain namespace. Rather than requiring negotiation on this issue the message/link syntax allows for a link to be requested without specifying either the source or destination. The response body, as specified below, will then return a URI which the link has been connected to. The client may then set the URI to an appropriate value. Note, however, that the URI may not Goland, et al 7 INTERNET-DRAFT WEBDAV November 26, 1996 necessarily be empty. It is possible, for consistency reasons, that the arbiter may put a default or other value at the URI. LinkResult = Type Source Destination 3.6 Definition of Content Type Message/Unlink Unlink = Type Source Destination 3.7 Definition of Content Type Message/UnlinkResult UnlinkResult = Type Source Destination 3.8 Definition of LinkSearch Method The LinkSearch method is used to search on the link type name space. The request URI is a LinkSearch arbiter that will perform the search on behalf of the client. This syntax is adapted from [RFC1959] and [RFC1960]. However the substring syntax has been greatly simplified as many servers will not be willing to support the more complex syntax. [TBD - Does the group agree with this assessment? Note: have also removed the "~=" operator as link names are not necessarily in any particular language so approximate is meaningless.] A pure prefix format has been chosen to simplify the server side processing. Given the already expensive nature of a search the choice seems appropriate. LinkSearchMethod = ["ReturnValue"] CRLF URI CRLF SearchFilter CRLF ReturnValues CRLF Scope CRLF SearchFilter = FilterList CRLF FilterList = And | Or | Not | Item And = "&" FilterList 1*FilterList Or = "|" FilterList 1*FilterList Not = "!" FilterList Item = Simple | Present | Substring Simple = EqualityOperator Type MatchPattern EqualityOperator = "=" | ">" | ">=" | "<" | "<=" | "!=" MatchPattern = token Present = "=*" AttributeName SubString = ["*"] token ["*"] ReturnValues = 1#Attribute CRLF Scope = "base" | "one" | "sub" The ReturnValue switch specifies that when possible the result should include the value of the link destination rather than its Goland, et al 8 INTERNET-DRAFT WEBDAV November 26, 1996 URL. In such a case the search result should be combined with the results of a GET on the destination into a message/multipart. If the search resolves to more than one result then the results of the request are dependent upon the result format. Equality is based on an octet by octet matching. The scope operator has three values, base, one, and sub. Base means to only search the specified URI. One means to search the URI and one level down the tree rooted at the URI. Sub means to search the URI and the entire URI name space rooted at that URI. 3.9 Definition of LinkSearch Header 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 Goland, et al 9 INTERNET-DRAFT WEBDAV November 26, 1996 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. 3.10 Definition of LinkPrefix Header 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. 4. Attributes [TBD - Explain that attributes sometimes use Destination to record their value and sometimes use Type. Specifically we can have attributes whose value is their type by having the destination pointing to the source.] [TBD - Also give a template for how attributes are specified. Specifying their type description and the contents of the destination.] The following attributes have their name and semantics defined by this specification. [TBD - Currently only brief descriptions are included. Decide which ones should survive and provide MIME types and other information.] AttributeSet This attribute returns a list of the attribute sets currently being used to describe the resource. Support of an attribute set does not indicate that all of its Goland, et al 10 INTERNET-DRAFT WEBDAV November 26, 1996 attributes are being used. For a list of all attributes in use, the AttributeDirectory attribute should be retrieved. For example, if some attributes from the Dublin Core were being used to describe a resource, AttributeSet might contain the value "Dublin", or "DC". The tag used to denote attributes defined in this specification is "RFCxxxx". IntentToEdit This attribute header returns a SiteMap containing a list of principals who have performed a Set Intent to Edit. DirectoryName This attribute returns a name suitable for presentation in a directory. The attribute embeds content headers to indicate language, character set, etc. History See History, section 9.2. Link Contains information about resources that are related to this resource. A SiteMap representation SHOULD be available. [TBD: Review the SiteMap format and figure out tag formats to define source links.] Link.Version See Version, Section 9.3. LockInformation See Lock Discovery, Section 3.2. Modifiable (weak form of access control query) Indicates if the principal can modify the resource. NotifyRequest See Notify Request, Section 6. Source The URI of the resource as stored, without any processing by the server (e.g. without processing of server-side includes). Version See Version, Section 9.3. Goland, et al 11 INTERNET-DRAFT WEBDAV November 26, 1996 5. Relationships - [Note: preliminary and incomplete] [TBD - Relationship should be a set of links. Should probably use the idea of atomic mime types to create both directions of a link simultaneously or to create a n-ary link. N-ary links will probably need some sort of token. What if many different parent child relationships? They can't all use the same damn name. Containers may be the real solution to n-ary links. Of course, container section incomplete] A relationship specifies how two or more resources are related. Examples of relationships include "author-of," "table of contents," and "specifies." A relationship can exist within a resource, and between mutliple resources. These resources may be of any media type, and a relationship can exist between resources of differing media type. When considering relationships which exist between resources, due to the distribution of resources across the Web, it is often the case that the relationship spans multiple servers. As a result, instead of being stored once, between resources, the endpoints of a relationship must be stored on individual resources. For the purposes of this specification, a relationship is defined to be a set of relationship endpoints. To create a multiway (or n-ary) relationship, a client must individually create each endpoint of the relationship, specifying at each endpoint which other relationship endpoints (usually on other resources) are part of the relationship. A hypertext link is a relationship which a client has made available to the user interface so a user can jump to the other endpoints of the relationship using the hypertext point-click-and-traverse user interface style. A link is always a relationship, but a relationship is not always a hypertext link. To request the creation of a relationship endpoint, a POST message with entity body of content-type application/relationship should be issued to the administration resource for relationships. 5.1 Definition of Content Type Application/Relationship REL/BODY = Relationship-request | Relationship-response Relationship-request = 1*( Rel-action Rel-token Rel-spec ) Goland, et al 12 INTERNET-DRAFT WEBDAV November 26, 1996 Relationship-response = 1*( Rel-action Rel-token Rel-spec Rel-response ) Rel-spec = Rel-URI Link ; Link is defined in Section 19.6.2.4 of [HTTP11] Rel-URI = "URI" ":" URI Rel-action = "Add" | "Remove" | "Modify" Rel-token = *1("RToken" ":" rtoken) ; Specifying token for an Add request is optional Rel-status = Status-Code SP Reason-Phrase ; As defined in [HTTP11] rtoken = token The ability to specify relationship endpoints on resources of any content type is mostly provided by the Link entity header field defined in 19.6.2.4 of [HTTP11]. The Link entity header field is used in this specification, with minor additions which add the ability to specify that another endpoint belongs to this relationship. This capability is provided by an additional link-param field, called peer. The contents of a peer field are a sequence of (URI, relationship token) tuples, which list the opposite endpoints of the relationship. The relationship token MUST uniquely identify a relationship endpoint on a particular resource, but does not have to be globally unique across all resources. ( "peer" "=" 1# "(" <"> URI <"> "," rtoken ")" ) An example of content type application/relationship is: Add URI: http://www.ics.uci.edu/authoring/meeting/intro.html RToken: 1 Link: ; rel="Child"; peer=("http://www.ics.uci.edu/authoring/meeting/agenda.html, 2) Add URI: http://www.ics.uci.edu/authoring/meeting/agenda.html RToken: 2 Link: ; rel="Parent"; peer=("http://www.ics.uci.edu/authoring/meeting/intro.html", 1) This defines a binary parent-child relationship between intro.html and agenda.html. From this example, it may seem that having the URI in the peer field is redundant. For binary relationships, this is indeed the case. However, the URI is required for multiway relationships, where more than one peer link needs to be specified in a peer parameter. Goland, et al 13 INTERNET-DRAFT WEBDAV November 26, 1996 6. Lock/Unlock [Note: a) I'd like to see more discussion about the semantics of the transitions from exclusive to shared (and vice-versa) locking modes. b) There needs to be more discussion about sub-document locking, and the interactions between a sub-document lock and full document lock, and the compatibilities of these cases. For example, an exclusive sub-document write lock is compatible with a full document shared write lock, but a shared sub-document write lock is not compatible with an exclusive full document write lock (on the same document, of course). c) There needs to be some discussion on which headers have defined semantics when included in a lock request. For example, "Max-Forwards:" does not make sense in this context. May other header fields might make sense, but would have slightly different semantics than defined in HTTP/1.1.] In order to provide for maximum flexibility and ease of administration, lock tokens will be used to track locks. When a lock is taken out a lock token will be returned. A single lock token can represent any number of locks. In future lock requests the same token may have new locks added or old locks removed from it. Lock tokens are not required to be transferable between lock administration resources. A lock has three possible types: read, write and no-modify. The following table specifies the legal combinations of locks on the same resource or, in the case of content-range, the same range of a lock. Read Write No-Modify Read Legal if Legal Legal Shared Write Legal Legal if Illegal Shared No-Modify Legal Illegal Legal if Shared A lock may be assigned to a range of a resource. The range may go off the "end" of the representation. Locks that exceed the end of a representation control the ability to append to the representation. Goland, et al 14 INTERNET-DRAFT WEBDAV November 26, 1996 A lock may be taken out either in exclusive or shared mode. In shared mode anyone with proper access may take out a lock. In exclusive mode only the principal who originally took out the lock may edit the lock. However a new principal can be added to an exclusive lock if the holder of the lock token performs the addition. If an entire resource is write locked and a lock owner deletes the resource then the write lock remains. Thus new information can be added to the now deleted resource using a PUT. Locks have time outs associated with them. If no time out value is associated with a lock then the lock will never time out. Otherwise the lock will expire if a number of seconds equal to the time out value passes without the resource being accessed by a lock owner. The time out value may be edited, without affecting the rest of the lock, by submitting a lock request with no Lock Entries. [TBD - Need an error message indicating that the server will not accept certain lock combinations or accept overlapping locks. Also need an error stating that an unlock couldn't be executed because it did not exactly match with a lock.] Locks will be implemented using the LOCK method. The request-URI is the resource to be locked. The entity-body type message/lock is also defined in this document. The response type message/lockresponse is also defined. 6.1 Definition of Content Type Message/Lock LockBody = Token_Status Time_Out Lock_Owners Lock_Entry Token_Status = (Token_Field | "No Token") Token_Field = "Lock Token" ":" LockToken LockToken = Any OCTET but LWS Time_Out = "Time Out" ":" (*DIGIT | "Never") Lock_Owners = "Lock Owner" ":" Lock_Owner Lock_Owner = quoted-string Lock_Entry = "Lock Entry" ":" LockEffect LockType CRLF LockEffect = ("Write" | "Read" | "No-Modify") LockType = (("Exclusive" |"Shared") | "Unlock") Examples of type application/lock include: No Token Time Out: Never Goland, et al 15 INTERNET-DRAFT WEBDAV November 26, 1996 Lock Owner: "Yaron Goland yarong@microsoft.com" Lock Entries: http://www.microsoft.com/staff/yarong.html Write Exclusive This specifies a request for an exclusive write lock on http://www.microsoft.com/staff/yarong.html, held by Yaron Goland. This lock will never time out. 6.2 Definition of Content Type Message/LockResponse LockResponse = 1#Description [LockBody] Description = quoted-string 6.3 Processing a Lock Request A lock request without a LockToken is a new lock request. If the request is successful then the response will include a lock token. A lock request with a LockToken is a request to extend the lock represented by the lock token. A lock request with Unlock specified for Lock_Request means that all locks associated with this token should be removed. A lock entry with Unlock means this particular lock should be removed from the token. The BNF allows unlocks to be specified without specifying a lock token. This is not an error. This syntax allows authorized principals to override locks. Lock requests MUST be processed as an atomic action or the request must be refused. When multiple resources are locked under a single token an operation will only be allowed on any of the resources if the remaining locks in the token can be guaranteed to exist for the life of the operation. 6.4 Lock Discovery [TBD - Needs sanity check.] 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. This information SHOULD be available through the attribute "LockInformation" which has the mime type Goland, et al 16 INTERNET-DRAFT WEBDAV November 26, 1996 application/LockInformation. The format of the mime entity-body is: LOCKINFORMATION = #(Token_Field Time_Out Lock_Owners Lock_Entries) [Contact_Field] Contact_Field = "Contact" ":" token The Contact_Field is used to provide contact information in case there is a problem with a lock. An example of a LockInformation attribute is: LockInformation: Token: a5dzq Time Out: Never [Yaron Goland The exclusive write lock on http://www.microsoft.com/staff/yarong.html is held by Yaron Goland, has token value a5dqz, and will never time out. If there is a problem with a lock, the Lock Administrator should be contacted. 7. Name Space Manipulation 7.1 Definition of Copy Method A copy performs a byte-for-byte duplication of a resource, making it available at both the original and new location in the URI namespace. There is no guarantee that the result of a GET on the URL of the resource copy will be identical to a GET on the original resource. For example, copying a script to a new location will often remove it from its intended environment, and cause it to either not work, or produce erroneous output. A copy MUST be atomic. Before any copied resources are made available through the destination, all copied resources must either be available or return a 503 Service Unavailable response code when referenced. A copy is preformed by the COPY method. The request-URI is the destination of the copy. The content-type Message/Copy may be used as a message body. Goland, et al 17 INTERNET-DRAFT WEBDAV November 26, 1996 MessageCopy = Source_URI Type Type = "Overwrite" | "No Overwrite" If the No Overwrite value is specified then that the copy should not occur if the destination URI already exists. If a resource is not copied because a "No Overwrite" flag was used then a 416 Destination Exists. 7.2 Definition of Move Method A move is logically a copy followed by a delete of the source resource. A move MUST be atomic. The MOVE method's syntax is identical to the COPY method except the content-type is called Message/Move. In this case atomicity requires that before the resources are made available at the new location they must no longer be available at the old location. The rest of the atomicity requirements are the same as for copy. 7.3 Definition of Destroy Method 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.3 Definition of Undelete Method 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 Introduction A collection is a resource used to contain other resources. Resources are added to a collection using the POST method and are removed from a collection using the RemoveResource method. A collection is created by performing a PUT method with a content-type of message/collection. Goland, et al 18 INTERNET-DRAFT WEBDAV November 26, 1996 8.2 Definition of Content Type Message/Collection MessageCollection = "FSC" | text The contents of message/collection identifies what sort of collection is being created. This document defines the collection type "FSC" which standards for File System Collection. 8.3 Definition of Content Type Message/AddResource To add a resource to a collection a POST on the resource should have the content-type Message/AddResource. AddResource = ("Propagate" | "Symbolic") URI A resource may be added to a collection in one of two states, Propagate or Symbolic. If added with Propagate then any name space manipulation methods executed on the collection will also be executed on the member resource. If added with Symbolic then methods executed on the collection will not be executed on the resource. 8.4 Definition of Content Type Message/RemoveResource The RemoveResource method's request-URI is the URI of the collection. The content-type Message/RemoveResource may be used with the RemoveResource method. RemovedResource = URI 8.5 Results of Methods on Collections of Type "FSC" A GET will return a listing of the contents of the collection. The WebCollection [WebC] content-type SHOULD be used as the default return type. A PUT MUST result in 405 Method Not Allowed. A DELETE or UNDELETE will be directly executed on the collection and all propagate members. A COPY/MOVE will be propagated to all propagate members. A POST will be performed on the COPY/MOVE destination for all the symbolic members. If a propagate member is a child of the collection's name space then the destination of the COPY/MOVE will be extended for that member. So if the collection is at http://foo/bar, the destination is http://place and a propagate Goland, et al 19 INTERNET-DRAFT WEBDAV November 26, 1996 member is http://foo/bar/thunk then the destination for the member will be http://place/thunk. If the propagate member is not a child of the collection's name space then the member's name should be appended to the collection's destination. So using the previous example if the propagate member's URL is http://blah/blah then its destination will be http://place/blah/blah. 9. Notification 9.1 Notify Request The Notify Request request-header is used to request that the server send a stream of "102 Process" messages containing updates of the request's status. Notify_Request = "NotifyRequest" ":" CRLF 9.2 Resource Event Notification As features such as WebCheck and URLMinder demonstrate, there is a strong interest in receiving notification when a resource changes. What is lacking is a standard means to register interest in receiving notification regarding a resource. To solve this problem the Notification link type is introduced. Type = "Notification" [On_Event] On_Event = #token The request-URI MUST be the destination. The source in the Message/Link will be the resource to notify when the specified event occurs. If no event is specified then the source will be notified at the destination's discretion. [TBD - Define On_Event for all known methods as well as their responses.] 10. Version Features [NOTES: IF YOU GET A VARIANT AND THEN VERSION IT YOU ARE NOT GUARANTEED TO GET THE SAME RESULT IF YOU VERSION A RESOURCE AND THEN GET A VARIANT. IT IS UP TO THE SERVER TO KEEP TRACK OF THESE THINGS. WE NEED TO MAKE SURE THAT VERSIONING DEGRADES NICELY. SO IF A CLIENT OR SERVER DOESN'T SUPPORT SOMETHIN WE CAN STILL GET SOME THINGS DONE. Goland, et al 20 INTERNET-DRAFT WEBDAV November 26, 1996 WE NEED A SERVER VERSION DISCOVERY MECHANISM. SOME WAY TO FIGURE OUT WHAT THE SERVER SUPPORTS. ] 10.1 Definition of Edit Announcement Link Type A set edit announcement is a means to notify other principals of an intent to edit the specified resource. This method should only cause the link to come into existence. No other actions is intended or implied. Type = "Edit Announcement" ("Exclusive" | "Shared") The "Exclusive" and "Shared" keywords indicate if a Set Edit Announcement is exclusive or shared on the specified resource. If exclusive then only a single Set Edit Announcement will be accepted on the resource. The request-URI of the LINK method is the resource the Set Edit Announcement is placed on, the destination. The Source is the URL of the principal to identify as having placed the announcement. UNLINK is used to remove an edit announcement. 10.2 Definition of the Merge Method The Merge method provides the result of a merge. It specifies what resources have been merged and then provides either the merge result or a URI that provides the merge result. The request-URI is the resource that wants the merge result. Application/Merge = Sources entity-body Sources = 1#("URI" ":" URI | "Entity" ":" <"> encoded-entity-body <">) encoded-entity-body = which must be encoded.> 10.3 Definition of the DIFF Method The request-URI of the DIFF method is the resource against which specified resources will be compared. The actual meaning of a DIFF depends upon the return type. [TBD - Throw in VTML as a return type.] Application/Diff = Sources 10.4 Definition of the Rollback Method The RollBack method causes the last method executed on a resource Goland, et al 21 INTERNET-DRAFT WEBDAV November 26, 1996 to be undone. [TBD - Define the error messages.] 10.5 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. 10.6 History History is an attribute header that returns a WebMap containing the history of the document. Type = "History" [TBD - Define the object tags for a standard history.] 10.7 Definition of the Version Link Version links indicate versioning relationships. Type = "Version" [Version] Version = Token The version token refers to the version of the destination. If the destination equals the source then the type gives the version of the current resource. If the Version is left out of a request then the requestor asks that the server assign a version. If a Version link's destination is not included then the link is a request to create a new version of the source. A successful response should include the version of the new resource along with a destination value pointing to the new resource. The new resource will not be frozen until a PUT is performed on it. However, if the new version is locked then it will not be frozen until the locks are removed. Thus, a Version Link without a Goland, et al 22 INTERNET-DRAFT WEBDAV November 26, 1996 version token and a destination is a request to create a new version with a server defined version token. A newly created version, which has yet to have a PUT performed on it, can not be frozen. An unfrozen resource, which is write-locked, may not be frozen until all write-locks are removed. 10.8 Version Management Issues The following examples demonstrate how to create new versions under various circumstances and how to control when those new versions become frozen. 10.8.1 Creating the First Version of a Resource If a server only accepts versioned resources then a new resource will automatically be versioned when it is PUT. The version number will be recorded in a looped version link. In order to prevent freezing, the URL should be write locked before the first PUT is performed. If the system does not automatically version resources then once a resource has been PUT a self-looping Version Link must be placed upon it to create a new version. 10.8.2 Adding a New Version of a Resource Assume the existence of a versioned resource A. To create a child of A, called B, one can create a Version Link with an unspecified destination. If the method is successful, the server will return a destination and a version token in the result. Another mechanism to create B is to PUT B to some URL and then attach a version link between the B and A. However servers are not required to support this functionality. 10.8.3 Version Conflicts If a version has not been frozen then multiple principals may make alternations to it. The simplest model is a free for all when changes may overwrite each other. However most systems prefer a more complicated model which depends upon Merges. A principal may perform a GET followed by a MERGE. The MERGE body should include the content-location from the GET response, as a merge source. The server may respond with a 409 Conflict if the Goland, et al 23 INTERNET-DRAFT WEBDAV November 26, 1996 resource has altered since the MERGE was performed. If so, the process repeats again. Another means to update an unfrozen version is to just PUT the new data. If a conflict occurs then a 409 Conflict will be returned which should be followed up by a MERGE. 10.8.4 Multiple Children Anytime a Version LINK is executed on a resource without a destination a new version of the resource will be created. This may have unintended consequences. If principals X and Y both wish to create a new version of A and both place Version LINKs without destinations on A, two separate new versions will be created. The version tree will branch. To prevent this unintended branching it is important to check for preexisting Version links. However this branch prevention mechanism can still cause problems because it is not atomic. There are two possible answers to this problem. Some systems do not allow for non-linear trees. As soon as a new version "B" is created from a base version "A" any further attempts to create new versions from "A" will point to "B". Other systems do allow branches. The only way for these systems to ensure that all principals will find out about "B" is to write-lock "A" and then create "B". Once confirmation has been received that "B" is created the write-lock can be released on "A". [TBD - The last part now specifies that write-locks will lock the ability to add links. This makes sense as links belong to the resource. The destination of a link doesn't belong to the resource but the link information itself, the source/destination/type triple does.] 10.8.6 Versions vs. Variants It is up to the server to maintain consistency amongst version numbers. However this does not require the server to guarantee that if a client requests a variant of a resource followed by a specific version that the client will get the same result performing the operations in the reverse order. 10.9 Server Versioning Negotiation version LINK/lock - to create a new Goland, et al 24 INTERNET-DRAFT WEBDAV November 26, 1996 11. Access Control [Note: preliminary and incomplete] When I speak of access control I mean the ability to associate a set of allowable actions to be performed on a resource by a representation as defined under a specified security protocol. Actions are HTTP methods with specified associated tags. Resources are a URI or a URI which references a group of URIs. Entities are defined by the particular security protocol being referenced. The versioning standard should include how to specify actions and resources but should only define an extension mechanism for defining entities. It would be prudent to include in an appendix a syntax for the definition of entities under commonly used HTTP authentication methods such as the Authentication tag. Note that a server is not required to accept access control suggestions. Each server has its own rules for how actions, resources and entities should be divided and is free to enforce those views. However error message should be used to inform the principal of the server's policies. In addition means must be provided to discover what actions, resources, and entities are available. However this information should also be under access control. It would seem logical to provide support in HTML for specifying access control features so that a server could provide principals who wish to set access controls with an HTML page whose formatting will help the principal assign access controls in a matter consistent with the server's policies. As access controls are the primary means for deciding how to share information it is critical that we define a standard or each versioning and distributed authoring package will define its own. This would not be such a bad fate if only one or two people on a site needed to assign access privileges. However everyone who owns a resource needs to set the access privileges for that resource and if resources are to be shared across systems then principals who use different versioning and distributed authoring packages need to be able to control access to resources on other systems. This interoperable world is only feasible if methods to define access controls are standardized. We should probably do access control through a method and header specification associated with security tokens which can either be groups or principals. We may want to push the URI kludge even further and identify principals via URIs. Goland, et al 25 INTERNET-DRAFT WEBDAV November 26, 1996 [Required Features - RAW Introduce the concept of Distributed Authoring compliance, Versioning compliance, and totally optional features. Use the list from the presentation.] 12. Acknowledgements Roy Fielding, Richard Taylor, Larry Masinter, Henry Sanders, Judith Slein, Dan Connolly, David Durand, Henrik Nielsen, Paul Leach. Others, TBD. 13. References [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. [VTML] 14. Authors' Addresses Yaron Goland Microsoft Corporation One Microsoft Way Bldg. 27N/3445 Redmond, WA 98052-6399 Fax: 206 936 7329 Email: yarong@microsoft.com Jim Whitehead Dept. Of Information and Computer Science Goland, et al 26 INTERNET-DRAFT WEBDAV November 26, 1996 University of California, Irvine Irvine, CA 92697-3425 Email: ejw@ics.uci.edu Asad Faizi Netscape Email: asad@netscape.com Del Jensen Novell 1555 N. Technology Way M/S ORM-F111 Orem, UT 84097-2399 Fax: 801 228 5176 Email: dcjensen@novell.com Goland, et al 27