idnits 2.17.1 draft-whitehead-webdav-versioning-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Found some kind of copyright notice around line 36 but it does not match any copyright boilerplate known by this tool. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 4 longer pages, the longest (page 1) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 18 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 9, 1998) is 9452 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) -- Possible downref: Non-RFC (?) normative reference: ref. 'WebDAV' Summary: 8 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET DRAFT E. J. Whitehead, Jr., UC Irvine 2 4 Expires December, 1998 June 9, 1998 6 A Web Versioning Protocol 8 Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six 16 months and may be updated, replaced, or made obsolete by other 17 documents at any time. It is inappropriate to use Internet-Drafts as 18 reference material or to cite them other than as "work in progress". 20 To learn the current status of any Internet-Draft, please check the 21 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 22 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 23 munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or 24 ftp.isi.edu (US West Coast). 26 Distribution of this document is unlimited. Please send comments to 27 the Distributed Authoring and Versioning (WEBDAV) working group at 28 , which may be joined by sending a message 29 with subject "subscribe" to . 31 Discussions of the WEBDAV working group are archived at 32 . 34 Copyright Notice 36 Copyright (C) The Internet Society (1998). All Rights Reserved. 38 Abstract 40 This document describes a set of methods, headers, and properties 41 which extend the HTTP and WebDAV protocols to support versioning and 42 variant authoring of Web resources. Operations are provided to 43 support differencing two resources, applying a difference to a 44 resource, checkin and checkout, along with creation, manipulation, 45 and listing a version and variant history graph. 47 Contents 49 STATUS OF THIS MEMO...................................................1 50 COPYRIGHT NOTICE......................................................1 51 ABSTRACT..............................................................1 52 CONTENTS..............................................................2 53 1 INTRODUCTION .......................................................4 54 2 NOTATIONAL CONVENTIONS .............................................4 55 3 VGRAPH - VERSION AND VARIANT GRAPH .................................4 56 4 MAPPING A VGRAPH INTO A HTTP URL NAMESPACE .........................5 57 4.1 Vhandle and Vportal .............................................6 58 4.2 Example of Vhandle and Vportal ..................................6 59 4.3 An Example of Vhandle and Vportal for Only Variants .............8 60 4.4 Alternate Approaches Considered, But Not Followed ...............9 61 4.4.1 Client Controlled Versioning ................................9 62 4.4.2 Ordered Collections ........................................10 63 5 HTTP METHODS FOR VERSIONING AND VARIANT AUTHORING .................11 64 5.1 CREATE .........................................................11 65 5.1.1 Example - CREATE a Vhandle to Existing Vgraph ..............12 66 5.1.2 Example - CREATE a Vhandle and a new Vgraph ................12 67 5.1.3 Example - CREATE a Vhandle, Vportal, and Vgraph ............13 68 5.2 DIFF ...........................................................13 69 5.2.1 Example - DIFF of Two Unversioned text Resources ...........14 70 5.2.2 Example - DIFF of Two Versioned text Resources .............14 71 5.2.3 Example - DIFF of Two Unversioned image Resources ..........15 72 5.2.4 Example - DIFF between an image and text Resource ..........15 73 5.3 PATCH ..........................................................15 74 5.4 DEFSET .........................................................16 75 5.4.1 Example - DEFSET to an Exact Version Identifier ............16 76 5.4.2 Example - DEFSET to the Latest Version .....................17 77 5.5 GRAPHOP ........................................................17 78 5.5.1 Example - GRAPHOP to Create Arcs and Nodes .................18 79 5.6 GRAPHGET .......................................................20 80 5.7 CHECKOUT .......................................................20 81 5.7.1 Example - CHECKOUT .........................................21 82 5.8 CHECKIN ........................................................22 83 5.8.1 Example - CHECKIN ..........................................23 84 6 OPERATION OF EXISTING HTTP AND WEBDAV METHODS ON VHANDLE AND VPORTAL 85 RESOURCES............................................................24 86 6.1 GET, HEAD ......................................................24 87 6.2 PUT ............................................................24 88 6.3 POST, TRACE ....................................................24 89 6.4 OPTIONS ........................................................24 90 6.5 DELETE .........................................................24 91 6.6 COPY ...........................................................24 92 6.7 MOVE ...........................................................24 93 6.8 PROPFIND/PROPPATCH .............................................25 94 6.9 LOCK/UNLOCK ....................................................25 95 6.10 MKCOL ..........................................................25 96 7 HTTP HEADERS FOR VERSIONING AND VARIANT AUTHORING .................25 97 7.1 Diff ...........................................................25 98 7.2 Videntifier ....................................................25 99 8 PROPERTIES ........................................................26 100 9 INTERNATIONALIZATION CONSIDERATIONS ...............................26 101 10 IANA CONSIDERATIONS .............................................26 102 11 SECURITY CONSIDERATIONS .........................................26 103 12 XML ELEMENT DEFINITIONS .........................................26 104 13 REFERENCES ......................................................26 105 14 AUTHOR'S ADDRESS ................................................27 106 1 Introduction 108 Change is ubiquitous, nowhere more evident than in Web content. 109 Whether to support collaborative authoring, tracking content 110 deliveries, efficient retrieval of resources by requesting a delta, 111 or retrieval of previous versions of a resource, versioning 112 functionality is a key infrastructure for manipulating Web resources 113 which change over time. 115 In a global information system, one type of content does not suit 116 all. People who use the Web typically prefer their content in a 117 specific human language, character set, and media type. The Web 118 currently supports retrieval of such resource variants via content 119 negotiation, but provides limited support for authoring them. 121 Variation and change are not orthogonal, since an abstract Web 122 resource may have multiple versions, changing over time, and each 123 version of the resource may have several variants, to satisfy many 124 consumers. 126 This document describes extensions to the WebDAV distributed 127 authoring protocol [WebDAV], itself an extension of the HTTP 1.1 128 protocol [RFC2068], for manipulating versioned resources, variants 129 of resources, and their combinations. 131 2 Notational Conventions 133 Since this document describes a set of extensions to the HTTP/1.1 134 protocol, the augmented BNF used herein to describe protocol 135 elements is exactly the same as described in section 2.1 of 136 [RFC2068]. Since this augmented BNF uses the basic production rules 137 provided in section 2.2 of [RFC2068], these rules apply to this 138 document as well. 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 142 document are to be interpreted as described in [RFC2119]. 144 3 Vgraph - Version and Variant Graph 146 A Vgraph is a directed acyclic graph which models the versions and 147 variants of one conceptual resource. A Vgraph consists of resources 148 (nodes), and typed relationships (arcs). The "derived-from" 149 relationship models a later resource as a revision of another 150 resource. For example, a revision labeled "1.2" has a "derived-from" 151 relationship to revision "1.1". The "variant-of" relationship models 152 situations where one resource varies from another by human language, 153 charset, media type, or content coding. A resource which is a 154 German language variant has a "variant-of" relationship to the 155 original English language resource. 157 In this specification, every version and variant of a resource is 158 itself a separate resource, with a separate URI. So, if there is a 159 set of resources which are conceptually viewed as "hello.html", then 160 versions 1 and 2 of hello.html would each have their own URIs, and 161 the URI for version 1 would be different than the URI for version 2. 162 If there was a German language variant of version 1 of hello.html, 163 it would have a URI which is different than the URIs of English 164 language versions 1 and 2 of hello.html. 166 Nodes are referentially contained within a Vgraph, and are 167 identified by their URI. Both nodes and arcs can have descriptive 168 information associated with them, known as properties. Node 169 descriptive information has a 1:1 correspondence with WebDAV 170 properties, hence any property that can be retrieved from the Vgraph 171 can be retrieved from a property on the resource, assuming the 172 Vgraph and the resource are on the same server, and the resource 173 supports WebDAV properties (e.g., an FTP resource would not). 174 Relationships are binary only, corresponding directly to arcs in a 175 graph. 177 A Vgraph MUST have a globally unique identifier, which is a URI. No 178 operations are supported on this URI by default (like a property 179 name, it is just a unique identifier). Similarly, all elements of 180 the Vgraph have globally unique identifiers; nodes are uniquely 181 identified by their URI, and each arc MUST have a globally unique 182 identifier, which is a URI. 184 A Vgraph has sufficient expressiveness to represent version 185 histories which span multiple servers, and can contain resources in 186 multiple URI schemes. Since resources are not directly contained by 187 a Vgraph, the same resource may participate in multiple Vgraphs. A 188 Vgraph expresses derived-from and is-variant-of relationships 189 between resources of any media type, and the media type may vary 190 across resources in a Vgraph. 192 4 Mapping a Vgraph into a HTTP URL Namespace 194 One of the siren calls for Web versioning is mandating a single 195 mapping of a Vgraph into the HTTP URL namespace. A typical approach 196 is to specify a convention for adding a version identifier to a URL, 197 such as ",v{version id}". This approach has fatal drawbacks: 199 - It adds semantics to URLs, making them non-opaque, and subject to 200 namespace collisions with other such URL "munging" schemes. 202 - It hard-codes derived-from relationships into version identifiers, 203 limiting their expressiveness, for example, mandating "1.2" instead 204 of "Jim's interim version". 206 - Since a specific version's URL is constructed from a version 207 identifier appended to a base URL, it requires all revisions of a 208 resource to be located on the same server, and resources are limited 209 to membership in just a single Vgraph. 211 - The approach scales poorly for handling variants, since extra 212 information must be added to the URL for representing variants of a 213 specific version of a resource (e.g., ",v{version 214 id},var{en,application/pdf}"). 216 - It confuses the distinction between a single Web resource, and all 217 of the resources contained within a Vgraph. 219 A far more flexible approach is have no mapping of a Vgraph into the 220 HTTP URL namespace, providing instead two abstractions, a Vhandle, 221 and a Vportal. 223 4.1 Vhandle and Vportal 225 A Vhandle is a location in the HTTP URL namespace which supports 226 operations on one Vgraph. A Vhandle can be created anywhere in the 227 HTTP URL namespace, and supports operations which manipulate the 228 graph structure of its Vgraph. Operations such as checkout, 229 checkin, add an arc, add a node, and retrieve graph contents are 230 applied to a Vhandle. When a Vhandle is created, the Vgraph it 231 operates upon is specified by the Vgraph's unique identifier. 233 A Vportal is a location in the HTTP URL namespace which supports 234 retrieval operations on one Vgraph. A Vportal can be created 235 anywhere in the HTTP URL namespace. Operations such as retrieve a 236 specific version, retrieve a specific variant (e.g., GET with Accept 237 headers), set the default version/variant for unspecified retrieval 238 (e.g. GET without content negotiation or a named version), and 239 retrieving a difference between two versions are applied to a 240 Vportal. When a Vportal is created, the Vgraph it operates upon is 241 specified by the Vgraph's unique identifier. 243 Any Vgraph MUST have at least 1 Vhandle, and MAY have more. There 244 may be 0 or more Vportals for any Vgraph. While Vhandles and 245 Vportals are distinct abstractions, a given URL MAY act as both a 246 Vhandle and a Vportal simultaneously. 248 4.2 Example of Vhandle and Vportal 250 In this example, there is a conceptual resource called 251 "datasheet.html", which has three revisions where each revision has 252 a Japanese language variant. The server which manages these 253 resources, "www.specs.com", reserves an area of its HTTP namespace 254 under "/vcache/" specifically for versions and variants of 255 resources, and this area is separate from the area of its namespace, 256 "/products/", where requests for information are made. 258 This server has chosen a scheme where it assigns a unique numeric 259 identifier to each version and variant of a resource, and so for 260 this server version 1 of datasheet.html is located at 261 "http://www.specs.com/vcache/52619.html" (52619 is a unique number 262 generated by the server according to its server-specific naming 263 scheme), version 2 is located at 264 "http://www.specs.com/vcache/43687.html", and version 3 is located 265 at "http://www.specs.com/vcache/68432.html". The Japanese language 266 variant of version 1 of datasheet.html is located at 267 "http://www.specs.com/vcache/59766.html", and the variants of 268 versions 2 and 3 are located at 269 "http://www.specs.com/vcache/12344.html" and 270 "http://www.specs.com/vcache/87663.html". Like for versions 1 271 through 3, the server's specific naming policy for version and 272 variants has been used to generate these names, and the semantics of 273 the names are only meaningful to the server. 275 The Vgraph has the unique URI, "vgraph:4A7F-52DE-5DFA29FE-12A0", and 276 the following relationships: 278 http://www.specs.com/vcache/68432.html derived-from 279 http://www.specs.com/vcache/43687.html 280 (That is, version 3 is derived from version 2.) 282 http://www.specs.com/vcache/43687.html derived-from 283 http://www.specs.com/vcache/52619.html 284 (Version 2 is derived from version 1.) 286 http://www.specs.com/vcache/59766.html is-variant-of 287 http://www.specs.com/vcache/52619.html 288 (The Japanese language variant of version 1.) 290 http://www.specs.com/vcache/12344.html is-variant-of 291 http://www.specs.com/vcache/43687.html 292 (The Japanese language variant of version 2.) 294 http://www.specs.com/vcache/87663.html is-variant-of 295 http://www.specs.com/vcache/68432.html 296 (The Japanese language variant of version 3.) 298 There is one Vportal for this Vgraph, located at 299 "http://www.specs.com/products/chips/6502". This Vportal has its 300 default retrieval set to return version 3. 302 The following HTTP 1.1 request: 304 GET /products/chips/6502 HTTP/1.1 305 Host: www.specs.com 307 Returns exactly the same entity as a GET (with no content 308 negotiation) of http://www.specs.com/vcache/68432.html, i.e., it 309 returns version 3. 311 Adding language content negotiation to the request: 313 GET /products/chips/6502 HTTP/1.1 314 Host: www.specs.com 315 Accept-language: jp 317 Returns exactly the same entity as a GET (with no content 318 negotiation) of http://www.specs.com/vcache/87663.html, i.e., it 319 returns the Japanese language variant of version 3. 321 A specific version could be requested: 323 GET /products/chips/6502 HTTP/1.1 324 Host: www.specs.com 325 Videntifier: 2 327 This returns http://www.specs.com/vcache/43687.html, which is 328 version 2. 330 The Vgraph in this example has a single Vhandle, which has the same 331 URL as the Vportal. 333 4.3 An Example of Vhandle and Vportal for Only Variants 335 The example features a conceptual resource called "vino.html", 336 located on server "http://www.vinomundial.com/", which is 337 unversioned and has three language variants, German, French, and 338 English, in addition to its Spanish source. This server uses the 339 naming scheme of placing the language code of the variant in the 340 URL. 342 The Vgraph has the unique URI, "vgraph:6B9A-86BE-5EA47610-8876", and 343 has the following relationships: 345 http://www.vinomundial.com/vino.de.html is-variant-of 346 http://www.vinomundial.com/vino.es.html 347 (The German language variant is a variant of the Spanish language 348 source.) 350 http://www.vinomundial.com/vino.fr.html is-variant-of 351 http://www.vinomundial.com/vino.es.html 352 (The French language variant is a variant of the Spanish language 353 source.) 355 http://www.vinomundial.com/vino.en.html is-variant-of 356 http://www.vinomundial.com/vino.es.html 357 (The English language variant is a variant of the Spanish language 358 source.) 360 The Vportal for this Vgraph is located at 361 http://www.vinomundial.com/vino.html, and is set so the default 362 resource retrieved from this URL is the Spanish language variant, 363 http://www.vinomundial.com/vino.es.html. 365 An example retrieval with content negotiation from the portal URL 366 is: 368 GET /vino.html HTTP/1.1 369 Host: www.vinomundial.com 370 Accept-language: de 372 This returns the German language variant of the resource, i.e., the 373 same entity returned by a GET without accept headers on 374 http://www.vinomundial.com/vino.de.html. 376 This site also maintains a German-only hierarchy at 377 "http://www.vinomundial.com/de/" where all of the resources are in 378 German. There is a second Vportal on the Vgraph located in this 379 hierarchy, at "http://www.vinomundial.com/de/vino.html" This 380 Vportal is set so the default resource retrieved from this URL is 381 the German language variant, 382 http://www.vinomundial.com/vino.de.html. 384 This site also maintains a separate authoring section, at 385 "http://www.vinomundial.com/authoring/", and the Vhandle for the 386 Vgraph is located there, at 387 "http://www.vinomundial.com/authoring/vino.html". Whereas the rest 388 of the site is open to all requests, access to the authoring section 389 of the site is protected using Digest authentication, and all access 390 must be authenticated. 392 4.4 Alternate Approaches Considered, But Not Followed 394 Two alternate approaches for mapping versioned resources into the 395 HTTP URL space have been considered, but not used in this draft. 396 However, a discussion of these alternate approaches, their strengths 397 and deficiencies is useful to distinguish the approach presented 398 here. 400 4.4.1 Client Controlled Versioning 402 In this approach, the client controls the mapping of versioned 403 resources into the HTTP URL space, and manages all versioning 404 operations, as well as the consistency maintenance of the 405 version/variant graph. The paper, "Version management with meta- 406 level links via HTTP/1.1", by K. Ota, K. Takahashi, K. Sekiya 407 (draft-http-ntt-version-00, expired, but available off 408 http://www.ics.uci.edu/pub/ietf/webdav/), is an example of this 409 approach. 411 As an example of client controlled versioning, a checkout translates 412 into operations to create a new resource, lock the resource, lock 413 the predecessor, update the link information (stored in properties) 414 on the predecessor to point to the checked-out resource, unlock the 415 predecessor, add comment information to the new resource. Since the 416 client is only using base WebDAV operations to perform the 417 versioning, the server is completely unaware of any versioning -- 418 all versioning semantics are provided by the client. 420 The benefits of this approach are: 422 1) Versioning capability can be achieved with smarter clients 423 working against WebDAV servers, so no new server technology is 424 needed (except for programmatic access control). 425 2) Due to the flexibility of the approach, different versioning 426 styles can easily be accommodated -- a new style requires a new 427 client. However, interactions between versioning operation 428 conventions for different versioning styles would need to be 429 addressed. 430 3) Members of the version graph can be located anywhere in the HTTP 431 URL space, and the version graph can span multiple HTTP servers, 432 and could potentially span several protocols. 434 There are several drawbacks to this approach: 436 1) The server is unable to provide consistency maintenance for the 437 version graph. For example, if a client that is unaware of the 438 versioning conventions deletes an intermediate member of a 439 version graph, the graph will be inconsistent. 440 2) The server is unable to optimize the storage of versions by using 441 delta-based compression mechanisms. 442 3) Since there is only one mapping of the members of the version 443 graph into the HTTP URL hierarchy, it is difficult to provide a 444 "retrieve default member" operation, e.g., a GET on URL XYZ 445 always returns the most recent member of the version graph. 446 4) Either retrieval of the complete version graph is an expensive 447 operation, requiring traversal of the graph, or the client is 448 responsible for replicating is-derived-from links from the 449 resource which contains the complete version graph, and to 450 individual members of the version graph. Neither is desirable. 451 5) The technique does not handle versioning collections well. 453 4.4.2 Ordered Collections 455 This technique linearizes the version graph, placing an order on the 456 members of the graph, and then places all members of the version 457 graph into a collection with this ordering. Limiting the graph to 458 linear versioning simplifies this technique, since there then exists 459 a simple temporal mapping of members of the version graph into the 460 ordering maintained by the collection. Furthermore, in the linear 461 versioning case, the version graph can be implicitly encoded into 462 the ordering, and hence the server will automatically maintain the 463 consistency of the version graph. 465 So, using this technique, the versions of a resource called 466 "hello.java" would be placed into an ordered collection called 467 "hello.java", and the individual versions would be named following 468 some naming convention, such as "hello.java,v1", "hello.java,v2", 469 etc. So, to retrieve version 2 of hello.java, a GET would be 470 performed on "hello.java/hello.java,v2". Retrieval of a default 471 member of the collection is supported by creating a convention for 472 the response of GET on the collection, e.g., a GET on "hello.java/" 473 might always return the most recent member of the version 474 graph/collection. 476 A variation on this approach which uses non-ordered collections and 477 permits non-linear version graphs is shown in the slide presentation 478 at: . 480 The benefits of this approach are: 482 1) A simple client can use the ordering characteristics of the 483 collection to implicitly encode the version graph (linear 484 versioning only). 485 2) The server will perform automatic consistency maintenance of the 486 collection, hence version graph. 487 3) Supports retrieval of a default member of a collection. 488 4) Versioning can be supported by a simple client, and a relatively 489 simple server. 491 The drawbacks to this approach are: 493 1) If the version graph is implicitly stored in the ordering, it 494 extends poorly to non-linear version graphs, or graphs which have 495 variant relationships. 496 2) It extends poorly to versioning collections, that is, the 497 technique only works for the leaves of a HTTP URL hierarchy. 498 3) A single resource cannot participate in multiple version graphs, 499 (or conventions involving referential collection members must be 500 created, with implications for consistency maintenance.) 501 4) Requires modifications to the existing HTTP URL hierarchy. 503 Of these criticisms, the most telling is the inability to handle 504 versioned collections, thus locking out a future mechanism for 505 configuration management. 507 5 HTTP Methods for Versioning and Variant Authoring 509 5.1 CREATE 511 The CREATE method is used to create a Vhandle, a Vportal, or a 512 combination Vhandle and Vportal resource at the Request-URI. When 513 CREATE is used to create a Vhandle, either the URI of an existing 514 Vgraph MUST be given, or a new Vgraph will be created along with the 515 Vhandle, and the Vhandle will point to the new Vgraph. 517 5.1.1 Example - CREATE a Vhandle to Existing Vgraph 519 CREATE /authoring/dav-handle HTTP/1.1 520 Host: www.ics.uci.edu 521 Content-Length: xxx 522 Content-Type: text/xml; charset="utf-8" 524 525 526 527 528 529 vgraph:4A7F-52DE-5DFA29FE-12A0 530 531 532 534 HTTP/1.1 201 Created 536 This example shows the creation of the Vhandle at URL 537 http://www.ics.uci.edu/authoring/dav-handle/. This Vhandle permits 538 operations on the Vgraph with the unique identifier, vgraph:4A7F- 539 52DE-5DFA29FE-12A0. 541 5.1.2 Example - CREATE a Vhandle and a new Vgraph 543 CREATE /authoring/spec-handle HTTP/1.1 544 Host: www.ics.uci.edu 545 Content-Length: xxx 546 Content-Type: text/xml; charset="utf-8" 548 549 550 551 552 554 HTTP/1.1 201 Created 556 Content-Length: xxx 557 Content-Type: text/xml; charset="utf-8" 559 560 561 562 563 vgraph:5FDE-A43D-7865FDEA-7654 564 565 566 This example shows the creation of a new Vgraph, which has been 567 assigned the unique name, vgraph:5FDE-A43D-7865FDEA-7654, and the 568 creation of a new Vhandle for that Vgraph, at 569 http://www.ics.uci.edu/authoring/spec-handle. 571 5.1.3 Example - CREATE a Vhandle, Vportal, and Vgraph 573 CREATE /spec-sheets/widget.html HTTP/1.1 574 Host: www.prod.com 575 Content-Length: xxx 576 Content-Type: text/xml; charset="utf-8" 578 579 580 581 582 584 HTTP/1.1 201 Created 585 Content-Length: xxx 586 Content-Type: text/xml; charset="utf-8" 588 589 590 591 592 vgraph:A7D9-EAEA-54AFFDEA-7654 593 594 596 This example shows the creation of a new Vgraph, with the unique 597 identifier, vgraph:A7D9-EAEA-54AFFDEA-7654, and a resource at 598 http://www.prod.com/spec-sheets/wideget.html which simultaneously 599 acts as both a Vhandle and a Vportal for the Vgraph. 601 5.2 DIFF 603 The response from this method is the difference between two 604 resources. Each of the two resources may be given as the URI of a 605 non-versioned resource, or the URI of a Vportal resource combined 606 with a version identifier. This supports differences between two 607 arbitrary resources, two resources in the same Vgraph, resources 608 from different Vgraphs, or between a versioned resource and a non- 609 versioned resource. 611 The first resource is specified by the Request-URI. If the Request- 612 URI is the URL of a Vportal, then the version identifier of a 613 specific member of the Vgraph may be specified with the Videntifier 614 header. The second resource is specified by the Diff header. 616 The entity response from DIFF represents the difference(s) between 617 the two request resources. A server MAY return the difference in 618 any format, however a server MUST minimally support the TBD 619 difference format for all media types, and MUST perform Accept 620 header processing of client diff format preferences. 622 The server MUST minimally supply differences between two instances 623 of the same media type, for all text media types encoded using the 624 same charset. Ideally, servers will support differences between all 625 media types, minimally providing an octet-level difference. The 626 server SHOULD supply differences between different instances of the 627 text media type, (e.g. text/html and text/xml), and MAY support 628 differences between media types from different top-level trees. For 629 example, supporting a difference between text/xml and 630 application/xml is possible and meaningful, while a difference 631 between text/xml and image/gif is not. 633 *** Design Issue: which diff format should be required? 635 5.2.1 Example - DIFF of Two Unversioned text Resources 637 DIFF /drafts/draft-01.txt HTTP/1.1 638 Host: www.npo.org 639 Diff: 641 HTTP/1.1 200 OK 642 Content-type: zzz/dav-required-diff-format 643 Content-length: xyx 645 {.... diff entity here ...} 647 In this example, two non-versioned resources, 648 http://www.npo.org/drafts/draft-00.txt and 649 http://www.npo.org/drafts/draft-01.txt, which are text/plain, 650 charset="us-ascii", are differenced. Since the difference format is 651 currently TBD, the exact difference between the two resources is not 652 shown in this example. 654 5.2.2 Example - DIFF of Two Versioned text Resources 656 DIFF /drafts/draft.txt HTTP/1.1 657 Videntifier: "1" 658 Host: www.npo.org 659 Diff: ; "0" 660 HTTP/1.1 200 OK 661 Content-type: zzz/dav-required-diff-format 662 Content-length: xyx 664 {... diff entity here ...} 666 In this example, the URL http://www.npo.org/drafts/draft.txt 667 identifies a Vportal, hence the two resources being differenced are 668 the two members of the associated Vgraph with version identifiers 669 "0" and "1". In this example, both resources are text/plain, 670 charset="us-ascii". Since the difference format is currently TBD, 671 the exact difference between the two resources is not shown in this 672 example. 674 5.2.3 Example - DIFF of Two Unversioned image Resources 676 DIFF /images/new-logo.gif HTTP/1.1 677 Host: www.corp.com 678 Diff: 680 HTTP/1.1 200 OK 681 Content-type: zzz/dav-required-diff-format 682 Content-length: xyx 684 {... diff entity here ...} 686 This example shows two non-versioned GIF images (image/gif) being 687 compared, http://www.corp.com/images/new-logo.gif, and 688 http://www.corp.com/iamges/old-logo.gif. 690 5.2.4 Example - DIFF between an image and text Resource 692 DIFF /images/new-logo.gif HTTP/1.1 693 Host: www.corp.com 694 Diff: ; "1.1" 696 HTTP/1.1 409 Conflict 698 This example shows two resources, one an unversioned GIF image at 699 http://www.corp.com/images/new-logo.gif, the other a versioned HTML 700 resource which has version "1.1" in the Vgraph associated with the 701 Vportal http://www.corp.com/drafts/index.html. Since the server 702 cann perform a diff between a text/html and an image/gif resource, 703 it responds with a 409 Conflict status code. 705 5.3 PATCH 706 The PATCH method is used to modify parts of the entity returned in 707 the response to a GET method. 709 The request entity of the PATCH method contains a list of 710 differences between the resource identified by the Request-URI and 711 the desired content of the resource after the PATCH action has been 712 applied. The list of differences is in a format defined by the 713 media type of the entity (e.g., "application/diff") and must include 714 sufficient information to allow the server to convert the original 715 version of the resource to the desired version. Processing 716 performed by PATCH is atomic. Hence all changes MUST be 717 successfully executed or the method fails. PATCH MUST fail 718 executed on a non-existent resource; i.e., PATCH does not create a 719 resource as a side effect. 721 If the request appears (at least initially) to be acceptable, the 722 server MUST transmit an interim 100 response message after receiving 723 the empty line terminating the request headers and continue 724 processing the request. Since the semantics of PATCH are non- 725 idempotent, responses to this method are not cacheable. 727 *** Design Issue: In what format should the patch be applied? There 728 needs to be one patch format which all compliant applications must 729 support. 731 5.4 DEFSET 733 This method sets the default resource for the Vportal specified by 734 the Request-URI. The default resource is specified by the 735 Videntifier header, and identifies the resource which responds to 736 HTTP GET and POST method invocations (without Accept headers) on the 737 Vportal URI. 739 5.4.1 Example - DEFSET to an Exact Version Identifier 741 DEFSET /drafts/pos-paper.html HTTP/1.1 743 Host: www.ics.uci.edu 744 Videntifier: "1.3" 746 HTTP/1.1 200 OK 748 GET /drafts/pos-paper.html HTTP/1.1 749 Host: www.ics.uci.edu 751 HTTP/1.1 200 OK 752 Content-type: text/html 753 Content-length: xyx 755 { ... this is the entity body for version 1.3 of pos-paper.html ...} 756 This example of DEFSET sets the default resource for the Vportal 757 http://www.ics.uci.edu/drafts/pos-paper.html. The new default is 758 version 1.3 of the Vgraph associated with the Vportal. The GET 759 method invocation after the DEFSET shows that the Vportal 760 http://www.ics.uci.edu/drafts/pos-paper.html will respond to a GET 761 with no Accept headers by returning the entity body of the resource 762 which is version 1.3 of the Vgraph associated with this Vportal. 764 5.4.2 Example - DEFSET to the Latest Version 766 DEFSET /drafts/pos-paper.html HTTP/1.1 767 Host: www.ics.uci.edu 768 Videntifier: latest 770 HTTP/1.1 200 OK 772 GET /drafts/pos-paper.html HTTP/1.1 773 Host: www.ics.uci.edu 775 HTTP/1.1 200 OK 776 Content-type: text/html 777 Content-length: xyx 779 { ... this is the entity body for the most recent member of the 780 Vgraph associated with the Vportal 781 http://www.ics.uci.edu/drafts/pos-paper.html ...} 783 This example of DEFSET sets the default resource for the Vportal 784 http://www.ics.uci.edu/drafts/pos-paper.html. The new default is 785 the most recent member of the Vgraph associated with the Vportal. 786 The GET method invocation after the DEFSET shows that the Vportal 787 http://www.ics.uci.edu/drafts/pos-paper.html will respond to a GET 788 with no Accept headers by returning the entity body of the resource 789 which is the most recent member (of any branch) of the Vgraph 790 associated with this Vportal. 792 5.5 GRAPHOP 794 The GRAPHOP method processes instructions specified in the request 795 body to add a node or remove a node or add an arc or remove an arc 796 from the Vgraph associated with the Vhandle specified by the 797 Request-URI. Instruction processing MUST occur in the order 798 instructions are received (i.e., from top to bottom). Instructions 799 MUST either all be executed, or none executed. Thus if any error 800 occurs during processing all executed instructions MUST be undone 801 and a proper error result returned. 803 After all instruction processing has completed, the server MUST 804 ensure the graph is consistent by removing all arcs which do not 805 have a node at each endpoint, and all nodes which are not connected 806 to at least one arc. 808 *** Design issue: if an arc in the middle of a graph is removed, 809 there could be multiple, disconnected graphs. Should these extra 810 arcs be pruned? 812 Since the Vgraph only contains nodes by-reference, and not by-value, 813 if a node is removed from a Vgraph it does not imply the resource 814 associated with that node is deleted. 816 All servers MUST support the addarc and addnode processing 817 instructions, and SHOULD support the delarc and delnode processing 818 instructions. 820 5.5.1 Example - GRAPHOP to Create Arcs and Nodes 822 GRAPHOP /project/src/Makefile HTTP/1.1 823 Host: www.code.com 824 Content-type: text/xml; charset="utf-8" 825 Content-length: xyx 827 828 829 830 831 http://www.code.com/vcache/Makefile?v=1.0 832 http://www.code.com/vcache/Makefile?v=1.1 833 http://www.code.com/vcache/Makefile?v=1.2 834 835 836 837 http://www.code.com/vcache/Makefile?v=1.1 838 http://www.code.com/vcache/Makefile?v=1.0 839 840 841 842 http://www.code.com/vcache/Makefile?v=1.2 843 http://www.code.com/vcache/Makefile?v=1.1 844 845 846 847 849 HTTP/1.1 207 Multi-Status 850 Content-Type: text/xml; charset="utf-8" 851 Content-Length: zyz 852 853 854 855 856 857 858 HTTP/1.1 200 OK 859 860 861 862 863 http://www.code.com/vcache/Makefile?v=1.1 864 865 866 http://www.code.com/vcache/Makefile?v=1.0 867 868 869 arcid:4567-ae4f-78de54ad-6754 870 871 872 873 http://www.code.com/vcache/Makefile?v=1.2 874 875 876 http://www.code.com/vcache/Makefile?v=1.1 877 878 879 arcid:4567-de21-432156d8-ad31 880 881 HTTP/1.1 200 OK 882 883 884 885 887 This example shows a Vgraph being populated with three nodes and two 888 arcs. The following resources (which existed prior to the beginning 889 of GRAPHOP processing) were successfully added to the Vgraph: 891 http://www.code.com/vcache/Makefile?v=1.0 892 http://www.code.com/vcache/Makefile?v=1.1 893 http://www.code.com/vcache/Makefile?v=1.2 895 Two arcs were successfully added to the graph, and were assigned the 896 following unique identifiers: 898 http://www.code.com/vcache/Makefile?v=1.2 is-derived-from 899 http://www.code.com/vcache/Makefile?v=1.1 900 unique identifier: arcid:4567-ae4f-78de54ad-6754 901 http://www.code.com/vcache/Makefile?v=1.1 is-derived-from 902 http://www.code.com/vcache/Makefile?v=1.0 903 unique identifier: arcid:4567-de21-432156d8-ad31 905 Since the graph was consistent after adding these three nodes and 906 two arcs, the server was not required to perform any additional 907 processing to maintain the consistency of the Vgraph. 909 5.6 GRAPHGET 911 The GRAPHGET method returns an entity body listing the contents of 912 the Vgraph associated with the Vhandle specified by the Request-URI. 914 *** Design issue: How should the Vgraph entity be returned? RDF is 915 one solution, as is XML without RDF semantics. 917 *** Design issue: should comment (arbitrary property) information be 918 returned by GRAPHGET? 920 5.7 CHECKOUT 922 The CHECKOUT method performs the following operations on the Vgraph 923 associated with the Vportal at the Request-URI: 925 1) A new resource, known as the "working resource", is created at a 926 location determined by the server. This resource is acted upon 927 by authoring tools, accepting PUTs of intermediate and final 928 results, and allowing properties to be read and set on it. 929 2) The initial contents of the working resource are identical to the 930 resource whose version is given by the Videntifier header, if 931 specified, or the default resource if not. 932 3) An "is-derived-from" relationship is added to the Vgraph between 933 the working resource and the resource given by the Videntifier 934 header, if specified, or the default resource if not. 935 4) The working resource is write locked, with the type of the write 936 lock (exclusive or shared) determined by the server. By default, 937 the lock SHOULD be an exclusive write lock. 938 5) Any check-out comments submitted in the request body are stored 939 in the comments property on the working resource. 940 6) Access permissions MUST be set so the principal requesting the 941 check-out has read and write permission to the working resource. 943 All of these operations MUST be performed, or none are performed. 944 Thus, if any error occurs during processing, all operations 945 performed to that time MUST be undone and a proper error result 946 returned. 948 Since a lock is being created during normal CHECKOUT processing, the 949 Timeout header (specified in [WebDAV]) MAY be submitted with a 950 CHECKOUT method request, and is subject to normal Timeout header 951 processing as described in [WebDAV]. 953 *** Design Issue: What should be the behavior if the lock times out? 955 *** Design Issue: Extending Checkout to work with Depth header to 956 check out a collection hierarchy with one operation. 958 A successful response to CHECKOUT will return a checkoutstat XML 959 element which contains the URL of the working resource, and a 960 lockdiscovery XML element that describes the lock created on the 961 working resource. 963 5.7.1 Example - CHECKOUT 965 >> Request 967 CHECKOUT /reports/1998/q1.doc HTTP/1.1 968 Host: www.funcorp.com 969 Content-type: text/xml; charset="utf-8" 970 Content-length: xxyx 971 Videntifier: "1.5" 972 Timeout: Infinite 973 Authorization: Digest username="craig.snider", 974 realm="reports@www.funcorp.com", nonce="...", 975 uri="/reports/1998/q1.doc", response="...", opaque="..." 977 978 979 980 Checked-out to add new project expense numbers. 981 982 Craig Snider 983 985 >> Response 987 HTTP/1.1 200 OK 988 Content-Type: text/xml; charset="utf-8" 989 Content-Length: zzyzx 991 992 993 994 995 996 997 998 0 999 1000 Craig Snider 1001 1002 Infinite 1003 1004 1005 opaquelocktoken:e5d7a3214-6da3-4432-5c39-fe98a34deaea 1006 1007 1008 1009 1010 1011 1012 http://www.mycorp.com/vcache/q1.doc?v1.6 1013 1014 1015 1017 This example shows a CHECKOUT being performed on the Vgraph 1018 associated with the Vportal at 1019 http://www.funcorp.com/reports/1998/q1.doc. The checkout was 1020 submitted with a Videntifier header of "1.5", meaning the checkout 1021 is occurring off of version 1.5 of q1.doc. A comment was submited 1022 with the checkout, giving rationale for the checkout operation, and 1023 owner information was also submitted for the lock created during 1024 checkout. A lock timeout value of "Infinite" was also requested, 1025 expressing a desire for a lock which never times out. 1027 The response from the CHECKOUT method lists the characteristics of 1028 the lock, and the location of the working resource. In this case, 1029 the lock is an exclusive write lock, that will never time out, and 1030 affects affects the working resource. The lock token for the lock 1031 is "opaquelocktoken:e5d7a3214-6da3-4432-5c39-fe98a34deaea", and the 1032 owner information from the request has been associated with the 1033 lock. 1035 The location of the working resource is 1036 "http://www.mycorp.com/vcache/q1.doc?v1.6". 1038 In this example, the nonce, response, and opaque fields have not 1039 been calculated in the Authorization request header. 1041 5.8 CHECKIN 1043 The CHECKIN method performs the following operations on the Vgraph 1044 associated with the Vportal given by the Request-URI, and on the 1045 working resource specified in the request body. 1047 1) The working resource is unlocked. 1048 2) The access control for the working resource is set such that no 1049 principal has write access (i.e., it is frozen). 1050 3) The server MAY set the version identifier for the working 1051 resource to the version identifier specified in the request body. 1053 All of these operations MUST be performed, or none are performed. 1054 Thus, if any error occurs during processing, all operations 1055 performed to that time MUST be undone and a proper error result 1056 returned. 1058 A valid CHECKIN request MUST include a Lock-Token header listing the 1059 lock token of the working resource's lock. 1061 5.8.1 Example - CHECKIN 1063 >> Request 1065 CHECKIN /reports/1998/q1.doc HTTP/1.1 1066 Host: www.funcorp.com 1067 Content-type: text/xml; charset="utf-8" 1068 Content-length: zxyzx 1069 Lock-Token: 1070 Authorization: Digest username="craig.snider", 1071 realm="reports@www.funcorp.com", nonce="...", 1072 uri="/reports/1998/q1.doc", response="...", opaque="..." 1074 1075 1076 1077 Added project expense numbers, fixed Figure 5, 1078 made minor fixes from reviewer's feedback. 1079 1080 1081 1082 http://www.mycorp.com/vcache/q1.doc?v1.6 1083 1084 1085 1086 Stable release 1 1087 1088 1090 >> Response 1092 HTTP/1.1 200 OK 1093 Content-Type: text/xml; charset="utf-8" 1094 Content-Length: zxyzx 1096 1097 1098 1099 1100 Stable release 1 1101 1102 1103 This example shows a CHECKIN method which checks-in the working 1104 resource "http://www.mycorp.com/vcache/q1.doc?v1.6" which is a 1105 member of the Vgraph associated with the Vportal 1106 http://www.funcorp.com/reports/1998/q1.doc. Comments have been 1107 submitted with the checkin, as has a suggested version identifier 1108 ("Stable release 1"). 1110 The response from CHECKIN gives the actual version identifier 1111 assigned by the server. In this case, the server accepted the 1112 version identifier submitted by the user agent. 1114 In this example, the nonce, response, and opaque fields have not 1115 been calculated in the Authorization request header. 1117 6 Operation of Existing HTTP and WebDAV Methods on Vhandle and Vportal 1118 Resources 1120 [Ed note: This section needs to be fleshed-out. These are my 1121 initial views on how they should be defined.] 1123 6.1 GET, HEAD 1125 GET and HEAD on a Vportal are redirected to the default member of 1126 the associated Vgraph. GET and HEAD on a Vhandle are not defined by 1127 this specification. 1129 6.2 PUT 1131 PUT is not permitted to either a Vhandle or Vportal. 1133 6.3 POST, TRACE 1135 Same as in RFC 2068. 1137 6.4 OPTIONS 1139 Same as in RFC 2068 plus WebDAV extensions. 1141 6.5 DELETE 1143 Operates on the Vhandle and Vportal. Deleting the last Vhandle to a 1144 Vgraph removes the Vgraph (and could leave dangling Vportals). 1146 6.6 COPY 1148 Operates on the Vhandle and Vportal (i.e., duplicates the Vhandle or 1149 the Vportal in a new location in the namespace). 1151 6.7 MOVE 1153 Operates on the Vhandle and Vportal (i.e., moves the Vhandle or the 1154 Vportal to a new location in the namespace). 1156 6.8 PROPFIND/PROPPATCH 1158 Operates on the properties of the Vhandle or the Vportal (i.e., both 1159 a Vhandle and a Vportal have properties for each instance). 1161 *** Design Issue: Since PROPFIND is used to list the members of a 1162 collection, if this approach is extended to handle versioned 1163 collections, there will need to be a way to pass the PROPFIND to the 1164 default member of the Vgraph for the versioned collection to afford 1165 a "list the members of the default member of the Vgraph for the 1166 versioned collection." 1168 6.9 LOCK/UNLOCK 1170 A lock on a Vhandle affects the Vhandle and the Vgraph, but is not 1171 propagated to the individual members of the Vgraph (the reference is 1172 locked, not the actual resource). A lock on a Vportal affects only 1173 the Vportal, but not the Vgraph. 1175 6.10 MKCOL 1177 Not allowed on a Vgraph or a Vportal. 1179 7 HTTP Headers for Versioning and Variant Authoring 1181 7.1 Diff 1183 Diff = "Diff" ":" Coded-url [";" version-id] ; Coded-url from 1184 Section 8.4 of [WebDAV] 1185 versiod-id = quoted-string 1187 The Diff header is used to specify one of the two URIs being 1188 differenced by the DIFF method. If the Coded-url is the URL of a 1189 Vportal, then the optional version-id specifies the version 1190 identifier of a specific member of the Vgraph. 1192 7.2 Videntifier 1194 Videntifier = "Videntifier" ":" vspec 1195 vspec = version-id | "latest" [branch-id] 1196 branch-id = Coded-url 1198 If the Request URI is a Vportal, this header specifies a member of 1199 the Vgraph associated with that Vportal. The specification is 1200 either an exact version identifier, or the most recent member of the 1201 Vgraph ("latest"), or the most recent member of a branch of the 1202 Vgraph ("latest" along with a branch identifier URI). 1204 *** Design issue: Since version identifiers are human-readable 1205 fields, need to have i18n support. This implies that version 1206 identifiers should be marshalled in the request body. 1208 8 Properties 1210 Need properties for comments, version graph info, and arcs leading 1211 to/from this node for all vgraphs the resource participates in (need 1212 to get root, default, pred., succ.) 1214 A Vportal and a Vhandle have properties associated with each 1215 instance of the Vportal or Vhandle. 1217 9 Internationalization Considerations 1219 TBD. 1221 Fields in the protocol that are human-readable: 1222 - version identifier 1223 - comments submitted on checkout and checkin 1225 10 IANA Considerations 1227 This protocol defines several new URI schemes: 1228 - vgraph:, for globally unique version graph identifiers 1229 - arcid:, for globally unique arc identifiers 1231 11 Security Considerations 1233 TBD. 1235 12 XML Element Definitions 1237 TBD. Some element definitions are reused from the WebDAV 1238 Distributed Authoring Protocol specification [WebDAV]. 1240 13 References 1242 [RFC2068] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners- 1243 Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. U.C. 1244 Irvine, DEC, MIT/LCS. January, 1997. 1246 [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate 1247 Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1248 1997. 1250 [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, 1251 D. Jensen, "Extensions for Distributed Authoring on the World Wide 1252 Web -- WEBDAV". Microsoft, U.C. Irvine, Netscape, Novell. 1253 Internet-draft, work-in-progress. 1255 14 Author's Address 1257 E. James Whitehead, Jr. 1258 Dept. of Information and Computer Science 1259 University of California, Irvine 1260 Irvine, CA 92697-3425 1261 Email: ejw@ics.uci.edu