idnits 2.17.1 draft-ietf-webdav-versioning-00.txt: -(501): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(834): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(835): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(867): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1489): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1953): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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. Expected boilerplate is as follows today (2024-04-26) 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. ** 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. == There are 12 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 40 longer pages, the longest (page 17) being 72 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 177 instances of too long lines in the document, the longest one being 3 characters in excess of 72. == There are 31 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 167 has weird spacing: '...ticated paral...' == Line 332 has weird spacing: '... can be imple...' -- 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 (April 26, 1999) is 9132 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) -- No information found for draft-ietf-webdav-versionreqs - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'DAVVERREQ' -- No information found for draft-kaler-webdav-versioning - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'Kaler' ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) == Outdated reference: A later version (-10) exists of draft-ietf-webdav-protocol-09 -- Possible downref: Normative reference to a draft: ref. 'White' Summary: 9 errors (**), 0 flaws (~~), 7 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Christopher Kaler, 3 draft-ietf-webdav-versioning-00.txt Microsoft 4 Editor 6 Expires April 26, 1999 7 October 26, 1998 9 Versioning Extensions to WebDAV 11 Status of this Memo 13 This document is an Internet draft. Internet drafts are working 14 documents of the Internet Engineering Task Force (IETF), its areas 15 and its working groups. Note that other groups may also distribute 16 working information as Internet drafts. 18 Internet Drafts are draft documents valid for a maximum of six 19 months and can be updated, replaced or obsoleted by other documents 20 at any time. It is inappropriate to use Internet drafts as 21 reference material or to cite them as other than as "work in 22 progress". 24 To learn the current status of any Internet draft please check the 25 "lid-abstracts.txt" listing contained in the Internet drafts shadow 26 directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 27 munnari.oz.au (Pacific Rim), ftp.isi.edu (US East coast) or 28 ftp.isi.edu (US West coast). Further information about the IETF 29 can be found at URL: http://www.ietf.org/ 31 Distribution of this document is unlimited. Please send comments 32 to the mailing list at , which may be 33 joined by sending a message with subject "subscribe" to . 36 Discussions of the list are archived at 37 . 39 Abstract 41 This document specifies a set of methods, headers, and content- 42 types composing DAV Versioning extensions, an application of the 43 HTTP/1.1 protocol to version DAV resources. 45 Table of Contents 47 VERSIONING EXTENSIONS TO WEBDAV...........................1 49 TABLE OF CONTENTS.........................................2 51 1.INTRODUCTION...........................................4 52 1.1. DAV Versioning......................................4 53 1.2. Relationship to DAV.................................4 54 1.3. Terms...............................................4 55 1.4. Definitions.........................................4 56 1.5. Notational Conventions..............................5 58 2.BASIC VERSIONING.......................................5 59 2.1. Discovery...........................................5 60 2.2. Immutable and Mutable Properties....................6 61 2.3. Automatic Versioning................................7 62 2.4. Resource Properties.................................7 63 2.5. Basic Versioning Headers............................8 64 2.5.1.Versioning-Support................................8 65 2.5.2.Revision-Id.......................................8 66 2.5.3.Merged-From.......................................9 67 2.6. Checking Out/In Resources...........................9 68 2.6.1.Checkout..........................................9 69 2.6.2.Branching Resources..............................11 70 2.6.3.Checkin..........................................12 71 2.6.4.Undo Checkout....................................13 72 2.6.5.Enumeration......................................13 73 2.7. Default Revision...................................13 74 2.8. Sharing............................................14 75 2.9. Collection Versioning..............................15 76 2.9.1.Default Revisions................................16 77 2.9.2.Headers..........................................16 78 2.9.3.Properties.......................................16 79 2.10.Resource Reports...................................17 80 2.10.1.Example.........................................17 81 2.10.2.Default History.................................18 82 2.10.3.Direct Lineage..................................19 83 2.10.4.Full Lineage....................................20 85 3.CONFIGURATIONS........................................21 86 3.1. Discovery..........................................22 87 3.2. Creating Configurations............................22 88 3.3. Configuration Properties...........................24 89 3.4. Headers............................................25 90 3.5. Deleting Configurations............................25 91 3.6. Managing Configuration Content.....................25 92 3.6.1.Access Using Configurations......................26 93 3.6.2.Adding Resources to a Configuration..............26 94 3.6.3.Removing Resources from a Configuration..........26 95 3.7. Workspace Configurations...........................27 96 3.7.1.Default Workspace Configurations.................27 97 3.7.2.Synchronizing Worksapce Configurations...........27 98 3.7.3.Condensing Workspace Configurations..............29 99 3.8. Configuration Reports..............................29 100 3.8.1.Configuration Derivation.........................30 101 3.8.2.Configuration Merge Graph........................31 102 3.9. Resolution Queues..................................31 103 3.9.1.Discovery........................................32 104 3.9.2.Obtaining Resolutions............................32 105 3.9.3.Processing Resolution Items......................32 106 3.10.Checkin Sets.......................................33 107 3.10.1.Discovery.......................................33 108 3.10.2.Usage...........................................34 110 4.VERSION MAPPING.......................................34 111 4.1. Discovery..........................................35 112 4.2. Mapping Configurations.............................35 113 4.3. Mapping Resource Versions..........................36 115 5.MISCELLANEOUS FUNCTIONS...............................37 116 5.1. Destroy............................................37 117 5.1.1.Discovery........................................37 118 5.1.2.Usage............................................37 119 5.1.3.Headers..........................................38 120 5.1.4.Properties.......................................38 122 6.THE DAV VERSIONING GRAMMAR............................38 124 7.INTERNATIONALIZATION CONSIDERATIONS...................38 126 8.SECURITY CONSIDERATIONS...............................38 128 9.SCALABILITY...........................................38 130 10. AUTHENTICATION......................................38 132 11. IANA CONSIDERATIONS.................................38 134 12. COPYRIGHT...........................................39 136 13. INTELLECTUAL PROPERTY...............................39 138 14. REFERENCES..........................................39 140 15. AUTHOR'S ADDRESSES..................................39 142 16. OPEN ISSUES.........................................39 144 17. CHANGE HISTORY......................................40 145 1. INTRODUCTION 147 1.1. DAV Versioning 149 This document defines DAV Versioning extensions, an application of 150 HTTP/1.1 for handling resource versioning in a DAV environment. 151 [DAVVERREQ] describes the motivation and requirements for DAV 152 Versioning. 154 DAV Versioning will minimize the complexity of clients so as to 155 facilitate widespread deployment of applications capable of 156 utilizing the DAV services. As well, DAV Versioning supports a 157 rich level of versioning options for versioning-aware clients. 159 DAV Versioning consists of: 161 - Automatic versioning support for HTTP/1.1-based clients, 163 - Basic versioning for DAV Versioning-aware clients, 165 - File branching for basic parallel development, and 167 - Configuration support for sophisticated parallel development. 169 1.2. Relationship to DAV 171 DAV Versioning relies on the resource and property model defined by 172 [WebDAV]. DAV Versioning does not alter this model. Instead, DAV 173 Versioning allows clients to version and access DAV-modeled 174 resources and histories. 176 1.3. Terms 178 This draft uses the terms defined in [RFC2068], [WebDAV], and 179 [DAVVERREQ]. 181 1.4. Definitions 183 The section defines several terms that are used throughout the 184 document specific to DAV versioning. 186 Versioned Resource - This refers to a resource that is subject to 187 versioning 189 Revision - This refers to a specific version of a versioned 190 resource 192 Revision History - This refers to the set of changes to a versioned 193 resource 195 Working Resource - This refers to a resource that is an 196 intermediate revision of a versioned resource. That is, the 197 versioned resource has been "checked out" and this is where changes 198 are made until it is ready to be "checked in". Note that working 199 resources are not versioned. 201 1.5. Notational Conventions 203 The augmented BNF used by this document to describe protocol 204 elements is exactly the same as the one described in Section 2.1 of 205 [RFC2068]. Because this augmented BNF uses the basic production 206 rules provided in Section 2.2 of [RFC2068], those rules apply to 207 this document as well. 209 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 210 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 211 this document are to be interpreted as described in [RFC2119]. 213 2. BASIC VERSIONING 215 The base level of versioning support defined by this specification 216 includes both automatic versioning and the basic versioning 217 properties defined for all resources. To support basic versioning, 218 resources MUST allow for versioning to occur automatically on 219 selected resources whenever immutable aspects are changed, and 220 support the properties defined in this section. 222 Resources that support DAV:versioning MUST also provide additional 223 versioning semantics for versioning-aware clients. This section 224 describes these new semantics which include enhancements to 225 existing DAV methods, new headers, and a new versioning-specific 226 method. 228 Although the semantics can vary, most versioning systems support 229 the notion of indicating intent to modify a document (check-out) 230 and then submission of the modified version (check-in). Typically 231 this involves some form of locking (either shared or exclusive). 232 As well, many systems support the ability to cancel a check-out or 233 undo a recent check-in. These options are available to the owner 234 or to the Administrator. 236 Users can generally enumerate the current check-outs although they 237 may not be able to determine the user in all cases. Likewise, 238 users can review check-ins to see the change history. Most systems 239 allow users to select different versions from the change history 240 and present a comparison of the versions. 242 Note that locks are not covered in this specification as they are 243 addressed by [WebDAV]. 245 2.1. Discovery 247 The OPTIONS method allows the client to discover if a resource 248 supports versioning. 250 The client issues the OPTIONS method against a resource named by 251 the Request-URI. This is a normal invocation of OPTIONS defined in 253 [RFC2068] with an extension. If the client includes the Verify- 254 Extension header, then the reply includes additional information 255 beyond that which is defined in [RFC2068]. 257 Using this header with the extension DAV:versioning, clients can 258 determine what versioning support is available. 260 The following defines the BNF for the Verify-Extension header: 262 Verify-Extension := "Verify-Extension" ":" URI-list 263 URI-list := URI | (URI-list "," URI) 265 This example shows that the /somefolder resource supports 266 versioning. 268 >> Request 270 OPTIONS /somefolder/ HTTP/1.1 271 Verify-Extension: DAV:versioning 272 Host: foobar.com 273 Content-Length: 0 275 >> Response 277 HTTP/1.1 200 OK 278 Date: Tue, 20 Jan 1998 20:52:29 GMT 279 Connection: close 280 Accept-Ranges: none 281 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 282 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF 283 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 284 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF 285 Verify-Extension: DAV:versioning 286 Versioning-Support: DAV:basicversioning 287 Content-Length: 0 289 The Verify-Extension header in the reply indicates that the server 290 understood the request with Verify-Extension and that 291 DAV:versioning is supported. As well, the Versioning-Support 292 header indicates the level of versioning support provided. The BNF 293 for this header is provided later in this document. 295 2.2. Immutable and Mutable Properties 297 An immutable property is defined as a property that, when changed, 298 causes a new revision of a versioned resource to be created. 299 Likewise, a mutable property is a property that can be changed 300 without having a new revision created. 302 Resources can support both mutable and immutable properties 303 although there MAY be restrictions that the mutability is 304 consistent across all resources. 306 This specification doesn�t cover the discovery or management of 307 property mutability. 309 2.3. Automatic Versioning 311 The DAV:autoversion property indicates if a resource is 312 automatically versioned when any immutable aspect of it is changed. 313 Resources with automatic versioning allow HTTP/1.1 clients to have 314 changes versioned without explicit versioning commands. 316 Automatic versioning includes the following methods: 318 - Updates via PUT, MKCOL, COPY, MOVE, or DELETE 320 - Immutable properties updates via PROPPATCH 322 2.4. Resource Properties 324 For resources that support versioning, they MUST support the 325 following properties using the "DAV:" namespace. Note that 0/1 is 326 used as a FALSE (0) / TRUE (1) indicator. 328 DAV:isversioned - 0/1 to indicate if the resource is versionable. 329 Note that this can be implemented as a read-only property. 331 DAV:autoversion - 0/1 to indicate if the resource is automatically 332 versioned when modified. Note that this can be implemented this 333 as a read-only property. 335 DAV:revisionid - This is a read-only property that returns a server 336 determined id for this specific revision of the resource. Every 337 revision of a resource will have a unique DAV:revisionid. A 338 revision id may be a URI or it may be an arbitrary server-defined 339 string. However, it cannot contain the "," character. Because it 340 is not required to be a URI, the DAV:revisionuri property is 341 required to obtain a URI for the specific revision of the resource. 343 DAV:vresourceid - This is a read-only property that returns a 344 server determined id for the versioned resource. That is, all 345 revisions of the resource have the same DAV:vresourceid. This MUST 346 be preserved over MOVE requests. 348 DAV:previousversionids - This is a read-only property that returns 349 the server defined id for the previous revision of the resource. 350 An empty value indicates that there are no previous revisions. 351 Note that there could be multiple previous versions. If there are 352 multiple revisions, they are returned as a comma-separated list. 353 Note that this property returns previous revisions that the server 354 determines. That is, this does not include user identified merged 355 revisions. 357 DAV:nextversionids - This is a read-only property that returns the 358 server defined id for the next revision of the resource. An empty 359 value indicates that there is no subsequent revision. Note that 360 there could be multiple next revisions. If there are multiple 361 revisions, they are returned as a comma-separated list. Note that 362 this property returns successor revisions that the server 363 determines. That is, this does not include user identified merged 364 revisions. 366 DAV:revisionuri - This is a read-only property that returns a URI 367 for this specific revision. 369 DAV:revisiondisplayname - This is a read-only property that returns 370 a string that clients may use to display this revision. This is 371 often a more user friendly string than DAV:revisionid. 373 DAV:revisionlabel - This property allows the specification of 374 textual names that refer to this version of the resource. If there 375 are multiple labels, they are returned as a comma separated list. 376 Labels MUST be unique for the versioned resource. That is, no two 377 revisions of the same versioned resource can have the same 378 DAV:revisionlabel. As well, DAV:revisionlabel, DAV:revisionid, and 379 DAV:vresourceid all share the same namespace and there can be no 380 duplicates. Servers MAY reserve specific portions of this 381 namespace and return an error if a client uses a reserved name as a 382 revision label. This property MUST be mutable. 384 DAV:mergedfrom - This property specifies a comma separated list of 385 revision ids from which this revision is purported to be derived. 386 This information is provided and managed by the client. 388 DAV:revisioncomment - This property contains a client-defined 389 property associated with the revision. This as a mutable property. 391 2.5. Basic Versioning Headers 393 The following sub-sections describe the new version headers that 394 MUST be supported for resources that support DAV:versioning. 396 2.5.1. Versioning-Support 398 The Versioning-Support header specifies the type of versioning that 399 is available. The following BNF defines this header. 401 Versioning-Support := "Versioning-Support" ":" URI-list 403 To support versioning, the URI list MUST include 404 DAV:basicversioning. Later sections of this document specify other 405 optional support. 407 2.5.2. Revision-Id 409 The Revision-Id header is used to identify a specific revision of a 410 versioned resource. This header can be specified on all methods 411 and qualifies the resource named in the method. As well, this 412 header is included in all replies to indicate the revision of the 413 versioned resource used or created. 415 The BNF for this header is as follows. 417 Revision-Id := "Revision-Id" ":" RID 418 RID := "*" | ANY 420 Clients can specify a DAV:revisionid or any of the 421 DAV:revisionlabel values to refer to a specific revision of the 422 resource. 424 The use of Revision-Id: * is only permitted with PROPFIND to obtain 425 properties across all revisions of a versioned resource. 427 2.5.3. Merged-From 429 When clients use resource branching, they will likely need to 430 perform merge operations. A merge is the process by which changes 431 from different versions are combined to produce a new version. It 432 is likely that clients will want to track this semantic 433 information. When the Merged-From header is specified on a PUT, 434 UNLOCK, or PROPPATCH method, it indicates the revision (or 435 revisions) from which the change is derived. The server tracks 436 this information and makes it available in the DAV:mergedfrom 437 property. 439 Merged-Item := ANY 440 Merged-List := Merged-Item | (Merged-List "," Merged-Item) 441 Merged-From := "Merged-From" ":" Merged-List 443 >>Request 445 PUT /foo/bar HTTP/1.1 446 Host: www.foobar.com 447 Merged-From: VER:FDHJ43058 448 Content-Type: text/html 449 Content-Length: xxxx 451 ... 453 >>Response 455 HTTP/1.1 200 OK 456 Content-Length: 0 458 2.6. Checking Out/In Resources 460 For versioning-aware clients, more advanced requests allow them to 461 perform specific versioning operations. These methods are directed 462 at a specific URI and the body contains XML indicating the action 463 to take. 465 If a resource supports DAV:versioning then it MUST support the 466 LOCK/UNLOCK extensions defined in this section. 468 2.6.1. Checkout 470 Using the LOCK method, clients can request resources to be "checked 471 out". This involves creating a working resource that is not 472 automatically versioned. Checked out resources must be checked in 473 or aborted, using the UNLOCK method. The diagram below illustrates 474 this process: 476 Revisions of foo.htm: V1 478 Checkout is performed: V1 479 | 480 +-> Working Resource 482 Checkin is performed: V1 -> V2 484 The body XML indicates an optional checkout comment, an optional 485 user token, and locking actions. Clients specify the checkout lock 486 in all update operations (e.g., PUT or PROPPATCH) to alter the 487 working resource. 489 The working resource will always be DAV:checkout locked. Clients 490 can choose to make the appropriate scope (DAV:shared, 491 DAV:exclusive, ...). Optionally, using the DAV:vresoucelockscope 492 tag, clients can have the versioned resource DAV:checkout locked 493 for a specified scope (DAV:shared, DAV:exclusive, ...). If a client 494 requests the versioned resource to be locked, and it cannot be, 495 then the lock operation MUST fail. 497 The DAV:checkout lock state is equivalent to the DAV:write lock 498 state in terms of interoperability with other locks. 500 Resources SHOULD allow clients to propose a DAV:locktoken in the 501 LOCK request. If a resource does not accept a client�s proposed 502 lock token, it MUST fail the LOCK request. 504 >>Request 506 LOCK /foo/bar HTTP/1.1 507 Host: www.foobar.com 508 Content-Type: text/xml 509 Content-Length: xxxx 511 512 513 514 checkout comment 515 client-defined token 516 517 518 520 >>Response 522 HTTP/1.1 201 CREATED 523 Content-Type: text/xml 524 Content-Length: xxxx 526 527 528 529 530 531 532 client-define token 533 534 opaquelocktoken:rejrei-43343-rereffre 535 536 537 538 540 2.6.2. Branching Resources 542 For more sophisticated clients, basic resource branching is 543 required. Resource branching means that for a given resource, the 544 history is not linear. That is, there are different lines of 545 descent. The diagram below illustrates this. 547 Revision history V1 -> V2 -> V3 548 Of foo.htm: | 549 +-> V1.1 -> V1.2 550 | 551 +-> V1.1.1 553 Individual resource branching is common in many versioning systems 554 today. Project branching (configurations) are described in a later 555 section. Note that when a collection is branched, the depth of the 556 branch is infinity. There is no way to change this. 558 If a resource supports branching, it MUST return 559 DAV:resourcebranching in the Versioning-Support header reply from 560 OPTIONS. 562 A resource is branched using the LOCK method and the DAV:checkout 563 lock type. The resource to be branched is specified as the target 564 URI for the method. 566 Clients have a choice of three approaches to branching which are 567 specified with specific tags in the request: 569 - perform a branch 571 - do not branch, error if necessary 573 - branch if necessary 575 As well, clients can specify a branch label to identify a created 576 branch using the DAV:branchlabel tag. The reply MUST include a 577 Branch-Id header specifying a resource defined branch id or the 578 specified branch label if a branch is created. The label or id can 579 be specified in a Branch-Id or Revision-Id header to determine the 580 revision to access. 582 >>Request 584 LOCK /foo/bar.htm HTTP/1.1 585 Host: www.foobar.com 586 Content-Type: text/html 587 Content-Length: xxxx 589 590 591 592 MyBranch 593 594 checkout comment 595 client-defined token 596 597 598 600 >>Response 602 HTTP/1.1 201 CREATED 603 Branch-Id: MyBranch 604 Content-Type: text/xml 605 Content-Length: xxxx 607 608 609 610 611 612 613 client-define token 614 615 opaquelocktoken:rejrei-43343-rereffre 616 617 618 619 621 When a branch is created, the reply MUST include a Branch-Id 622 header. The BNF for the header is as follows: 624 Branch-Id := "Branch-Id" ":" ANY 626 The Branch-Id can be used anywhere a revision-id is used. When 627 specified, it indicates that the latest version of the indicated 628 branch is to be selected as the revision to use for the operation. 630 2.6.3. Checkin 632 When the client has completed changes to a resource and wishes it 633 to become part of the revision history, the client must check in 634 the resource. This is performed using the UNLOCK method against 635 the versioned resource with special body tags and identification of 636 the checkout lock in the header. 638 >>Request 640 UNLOCK /foo/bar.htm HTTP/1.1 641 Host: www.foobar.com 642 Lock-Token: 643 Content-Type: text/xml 644 Content-Length: xxx 645 646 647 checkin comment 648 650 >>Response 652 HTTP/1.1 204 CREATED 653 Revision-Id: VER:FREFRI49349 654 Content-Length: 0 656 The reply MUST include the Revision-Id of the newly created 657 revision. 659 2.6.4. Undo Checkout 661 If a client chooses to cancel a checkout request, the UNLOCK method 662 is used with optional body tags and identification of the checkout 663 lock. 665 >>Request 667 UNLOCK /foo/bar.htm HTTP/1.1 668 Host: www.foobar.com 669 Lock-Token: 670 Content-Type: text/xml 671 Content-Length: xxxxx 673 674 675 676 cancel checkout comment 677 679 >>Response 681 HTTP/1.1 200 OK 682 Content-Length: 0 684 2.6.5. Enumeration 686 Clients can enumerate the current checkouts to a resource using the 687 PROPFIND method and standard lock discovery. All attributes 688 specified in the lock request (e.g. DAV:comment) MUST be returned 689 in lock discovery. 691 2.7. Default Revision 693 If a Revision-Id (or Branch-Id) header is not specified when 694 referring to a resource, then the tip (latest) revision (from the 695 primary branch) is used, unless a default revision has been 696 identified. To mark a specified revision as the default revision, 697 clients use the PIN method. Note that PUT or checkin will create 698 new revisions which will be returned unless a PIN is defined. When 699 a revision is PINned, new revisions can be created with PUT or 700 checkin, but they will not be returned unless they are referenced 701 explicitly. 703 Note that branching a resource has no effect on the default 704 revision of the resource, even if the default revision is branched. 705 If unpinned, the default revision is the tip revision of the 706 initial (primary) branch of the versioned resource. 708 >>Request 710 PIN /foo/bar.htm HTTP/1.1 711 Host: www.foobar.com 712 Content-Type: text/xml 713 Content-Length: xxx 715 716 VER:HT58GHDW49 718 >>Response 720 HTTP/1.1 200 OK 721 Content-Length: 0 723 >>Request 725 PIN /foo/bar.htm HTTP/1.1 726 Host: www.foobar.com 727 Content-Type: text/xml 728 Content-Length: xxx 730 731 733 >>Response 735 HTTP/1.1 200 OK 736 Content-Length: 0 738 It should be noted that setting a default revision may impact 739 automatic versioning. If a client performs a PUT operation that is 740 automatically versioned, it MUST fail if a GET will not return the 741 new version (possibly because of a PIN). 743 2.8. Sharing 745 Many versioning systems today provide the ability to have a given 746 resource visible in multiple parts of the namespace. In these 747 situations, a resource is shared. That is, changes to the resource 748 are visible to all versions. 750 The WebDAV advanced collections adds support for referential 751 members, however, this is not sufficient for sharing in a 752 versioning environment because of the requirement to establish 753 default revisions. Indirect references cannot map to specific 754 versions for down-level (e.g. HTTP/1.1) clients and direct 755 references map directly to the shared resource. 757 This specification introduces a new type of referential member, 758 semi-direct. A semi-direct reference is like a direct reference 759 except that it can have attributes of its own or it can map 760 directly to the shared resource. By default, when a semi-direct 761 reference is used in a request, it behaves like a direct reference. 762 However, if the Pass-Through header is specified on the request 763 with a value of "*", then the operation is performed against the 764 semi-direct reference not the object it points to. This is an 765 extension of the WebDAV advanced collection specification in value 766 and because the header can be specified with any request against a 767 semi-direct reference. 769 In the example below, a semi-direct reference is created. 771 >>Request 773 MKREF /bing/bar.htm HTTP/1.1 774 Host: www.foobar.com 775 Ref-Target: /foo/bar.htm 776 Ref-Integrity: DAV:semidirect 777 Content-Length: 0 779 >>Response 781 HTTP/1.1 201 CREATED 782 ... 784 In the example below, a request is made to a semi-direct reference. 785 The object that the reference refers to is returned. 787 >>Request 789 GET /bing/bar.htm HTTP/1.1 790 Host: www.foobar.com 791 Content-Length: 0 793 In the example below, the semi-direct reference is PINned to a 794 specific revision. 796 >>Request 798 PIN /foo/bar.htm HTTP/1.1 799 Host: www.foobar.com 800 Pass-Through: * 801 Content-Type: text/xml 802 Content-Length: xxx 804 805 VER:HT58GHDW49 807 2.9. Collection Versioning 809 Collections can be versioned just like non-collection resources, 810 however, there are special situations that must be taken into 811 account. Collections are versioned in the following ways: 813 - Don�t version the collection regardless of the changes. 815 - Version the collection only if there is a direct change to the 816 resource. 818 - Version the collection if there is a change anywhere under the 819 collection (i.e., bubble of the changes). 821 Each collection resource MAY choose the behavior it supports. The 822 behavior is specified through properties, which resources MAY 823 choose to make read-only. 825 The DAV:autoversion property indicates if a collection resource 826 supports versioning when changes are made to it. The 827 DAV:autocollectionversion property indicates if the collection 828 resource supports versioning when changes are made anywhere in the 829 namespace below it. 831 2.9.1. Default Revisions 833 It is up to each collection resource to determine if it supports 834 default versions. If it doesn�t, then PIN requests MUST fail. If 835 a collection resource doesn�t support versioning, then is MUST also 836 fail PIN requests. 838 2.9.2. Headers 840 If collections are versioned, then clients may choose to access 841 resources that are part of specific revisions. The Revision-Path 842 header is used to identify specific revisions that are part of the 843 "path" to the resource. This header servers as an alternative to 844 "URL munging". This header can be specified on all methods and 845 qualifies the resource named in the method. 847 The BNF for this header is as follows. 849 Revision-Path := "Revision-Path" ":" Path 850 Path := PItem | (Path PItem) 851 PItem := "/" ANY Rev 852 Rev := | (";" RID) 853 RID := "*" | ANY | "(" ANY ")" 855 >>Request 857 GET /foo/bar.htm HTTP/1.1 858 Host: www.foobar.com 859 Revision-Path: /foo;VER:HT58GHDW49/bar.htm;VER:HT58GHDW49 860 Content-Length: 0 862 The use of * for a revision is only permitted with PROPFIND to 863 obtain properties across all revisions of a versioned resource. 865 2.9.3. Properties 867 DAV:autocollectionversion - This property�s value (0/1) specifies 868 if a collection is automatically versioned when its contents 869 (anywhere under it) change. That is, if /foo/bar.htm is versioned, 870 is /foo/ versioned as well. Resources MAY implement this as a 871 read-only property. 873 DAV:canautocollectionversion - This property�s value (0/1) 874 specifies if the resource supports the ability to automatically 875 version collections when a contained resource changes. This is a 876 read-only property. 878 2.10. Resource Reports 880 Revision history graphs and other reports of a resource are 881 accessed via PROPFIND. Note that resources MAY support multiple 882 styles of history and reports. To enumerate the supported history 883 graphs and reports, clients use PROPFIND and the 884 property. The results indicate the different reports which can, 885 themselves, be requested via PROPFIND. 887 Note that clients can request properties to be included in reports 888 by specifying the desired properties inside the DAV:enumreport tag. 890 For the examples in this section, assume that the resource /foo.htm 891 has the following revision graph: 893 Revision history V1 -> V2 -> V3 894 Of foo.htm: | 895 +-> V1.1 -> V1.2 896 | 897 +-> V1.1.1 899 Clients have specified the following merge annotations: 901 - V1.2 is a merge of V1.1 and V1.1.1 903 - V3 is a merge of V2 and V1.2 905 As well, the default revision history (those revisions marked as 906 the default) is as follows: 908 - V1 (the initial revision was created) 910 - V2 (a new revision was created) 912 - V1 (a client changed the default revision) 914 - V3 (an updated revision was created) 916 Also, the following labels have been specified: 918 - V2: Test1 920 - V1.1: Test2, Good 922 - V1.2: Tested 924 Additionally, when the V1.1 branch was created, it was labeled 925 "MyBranch". 927 2.10.1. Example 929 >>Request 930 PROPFIND /foo/bar.htm HTTP/1.1 931 Host: www.foobar.com 932 Content-Type: text/xml 933 Content-Length: xxxx 935 936 937 938 940 >>Response 942 ... 943 944 945 946 DAV:defaulthistory 947 DAV:directlineage 948 DAV:fulllineage 949 950 951 952 ... 954 Note that the report styles MUST be specified as DAV:href values. 956 2.10.2. Default History 958 Resources MUST support the DAV:defaulthistory report. This 959 enumerates the historical record of revisions that have been 960 visible as the default revision of the versioned resource. 962 Clients can specify the limit parameter to limit the number 963 revisions returned. By definition, revisions are returned in 964 reverse chronological order starting with the most recent. 966 >>Request 968 PROPFIND /foo/bar.htm HTTP/1.1 969 Host: www.foobar.com 970 Content-Type: text/xml 971 Content-Length: xxxx 973 974 975 976 978 >>Response 980 ... 981 982 983 984 985 Update it 987 988 989 Update it 990 Test1 991 992 993 Update it 994 995 996 Update it 997 998 999 1000 1002 2.10.3. Direct Lineage 1004 Resources MUST support the DAV:directlineage report. This 1005 enumerates the direct parent revisions of the versioned resource. 1006 This report is from the default revision or the specified revision. 1008 Clients can request that a report be based on the namespace entry 1009 specified, or the associated DAV:vresourceid. Clients use the 1010 scope parameter to specify (name or id). 1012 >>Request 1014 PROPFIND /foo/bar.htm HTTP/1.1 1015 Host: www.foobar.com 1016 Revision-Id: V3 1017 Content-Type: text/xml 1018 Content-Length: xxxx 1020 1021 1022 1023 1025 >>Response 1027 ... 1028 1029 1030 1031 1032 Update it 1033 1034 Update it 1035 Test1 1036 1037 Update it 1038 1039 1040 1041 1042 1044 1045 1046 1048 2.10.4. Full Lineage 1050 Resources MUST support the DAV:fulllineage report. This enumerates 1051 the full graph of revisions for this resource. 1053 Clients can request that a report be based on the namespace entry 1054 specified, or the associated DAV:vresourceid. Clients use the 1055 scope parameter to specify (name or id). 1057 >>Request 1059 PROPFIND /foo/bar.htm HTTP/1.1 1060 Host: www.foobar.com 1061 Revision-Id: VER:FHJRH3994 1062 Content-Type: text/xml 1063 Content-Length: xxxx 1065 1066 1067 1068 1070 >>Response 1072 ... 1073 1074 1075 1076 1077 Update it 1078 1079 Update it 1080 Test1 1081 1082 Update it 1083 1084 1085 1086 1088 Test2, Good 1089 Update it 1090 1092 Tested 1093 Update it 1094 1095 1096 1097 1098 Update it 1099 1101 1102 1103 1104 1105 1106 1108 3. CONFIGURATIONS 1110 Many clients require more sophisticated management and organization 1111 of their versioned data. For this reason, configuration support is 1112 defined as part of this specification. 1114 Configuration management is a large space. This specification 1115 addresses several types of configurations: 1117 - Label: A label configuration is a collection of specific 1118 revisions of selected versioned resources. Changes to the 1119 versioned resources do not effect the contents of the label 1120 configuration. 1122 - Floating Label: A floating label configuration is a collection of 1123 the default revisions of selected versioned resources. When the 1124 default revision of a selected resource changes, the contents of 1125 the floating label configuration is updated automatically. Note 1126 that when a versioned resource is added to a floating level 1127 configuration, the Branch-Id header can be specified. In this 1128 case, the floating label will contain the tip revision the 1129 specified branch. 1131 - Workspace: A workspace configuration is a collection of multiple 1132 revisions of selected versioned resources. As the selected 1133 versioned resources are changed, in the context of the workspace 1134 configuration, the workspace tracks the version history. 1136 Configurations provide a mechanism for organizing resources and 1137 quick access to specific revisions of resources. Clients can 1138 access resources in the context of a configuration. By referencing 1139 a configuration, requests are automatically mapped to the correct 1140 revision of the versioned resource. 1142 Note that servers provide a default workspace configuration. This 1143 is were all resources exist. Clients can request other workspace 1144 configurations to be created and have operations performed within 1145 their context if workspace configurations are supported. 1147 A configuration can be derived from another configuration. That 1148 is, the new configuration is based on the versions in the "parent" 1149 configuration. Optionally, derived configurations can 1150 automatically inherit new versions in the parent configuration 1151 (assuming there are no conflicts). However, a configuration can be 1152 derived from at most one other configuration. 1154 Clients can specify configuration ids wherever a revision id can be 1155 specified. This requests that the default revision for the 1156 specified configuration be used. Requests that include both a 1157 revision id and a configuration id MUST fail if the specified 1158 revision is not part of the specified configuration. 1160 3.1. Discovery 1162 Configuration support is optional. This example shows that the 1163 /somefolder resource supports configurations. 1165 >> Request 1167 OPTIONS /somefolder/ HTTP/1.1 1168 Verify-Extension: DAV:versioning 1169 Host: foobar.com 1170 Content-Length: 0 1172 >> Response 1174 HTTP/1.1 200 OK 1175 Date: Tue, 20 Jan 1998 20:52:29 GMT 1176 Connection: close 1177 Accept-Ranges: none 1178 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 1179 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF 1180 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 1181 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF 1182 Verify-Extension: DAV:versioning 1183 Versioning-Support: DAV:basicversioning, DAV:configurations 1184 Configuration-Types: DAV:Label, DAV:Floating, DAV:Workspace 1185 Configuration-Root: /cfgs/ 1186 Content-Length: 0 1188 The Configuration-Types header in the OPTIONS reply indicates the 1189 types of configurations supported. Presence of this header 1190 indicates support for configurations. The BNF for this header is: 1192 Configuration-Types := "Configuration-Types" ":" Ctypes 1193 CTypes := CType | (CTypes "," CType) 1194 CType := "Label" | "Floating" | "Workspace" | 1195 URI 1197 The Configuration-Root header in the OPTIONS reply indicates the 1198 root of the configuration namespace. Note that there could be 1199 multiple configuration roots. The BNF for this headers is: 1201 Configuration-Root := "Configuration-Root" ":" URI-List 1203 3.2. Creating Configurations 1205 Servers maintain configurations in a private portion of the 1206 namespace. The root of this namespace is determined by examining 1207 the OPTIONS reply. All configurations names MUST be unique on a 1208 server. Using the configuration namespace, clients can create and 1209 manage configurations. 1211 Clients create new configurations by issuing the MKCOL method 1212 against the configuration namespace. This requests the server to 1213 create a new configuration. 1215 When a configuration is created, special tags can be used to define 1216 the characteristics and relationships (e.g. derivations) for the 1217 configuration. The following table enumerates these tags. 1219 Tag Description 1221 This tag defines the type 1222 xxx of configuration: 1223 DAV:Label, DAV:Floating, 1224 or DAV:Workspace. 1226 This tag allows the client 1227 xxx to specify a URI to 1228 identify another 1229 configuration from which 1230 this new configuration is 1231 to be derived. 1233 The configuration 1234 DAV:Auto automatically inherits 1235 changes from its derived- 1236 from configuration. 1237 Conflicts are recorded in 1238 resolution queues (see 1239 later section). 1241 The configuration inherits 1242 DAV:Manual changes from its derived- 1243 from configuration, but 1244 they are not automatically 1245 inserted into the 1246 configuration. Instead 1247 they are recorded in 1248 resolution queues (see 1249 later section). 1251 The configuration is a 1252 DAV:None snapshot of the current 1253 versions in the derived- 1254 from configuration. There 1255 is no inheritance of 1256 changes. This is the 1257 default type if no type is 1258 specified. 1260 "xxx" The configuration is based 1261 on the current versions in 1262 the derived-from 1263 configuration at the 1264 indicated time. Note that 1265 use of this tag is 1266 incompatible with DAV:Auto 1267 inheritance types and 1268 usage in this way MUST 1269 return an error. 1271 When a non-derived configuration is created, it contains no 1272 resources. Configurations that are derived from another 1273 configuration include the resources in the derived from 1274 configuration. 1276 The example below illustrates creating a new configuration that is 1277 derived from, and auto-inherits another configuration. For this 1278 example, the root of the configuration namespace has been 1279 determined to be /cfgs. 1281 >>Request 1283 MKCOL /cfgs/ HTTP/1.1 1284 Host: www.foobar.com 1285 Content-Type: text/xml 1286 Content-Length: xxxx 1288 1289 1290 DAV:Workspace 1291 http://www.foobar.com/cfgs/DDEJRJ445 1292 1293 Auto 1294 1296 >>Response 1298 HTTP/1.1 201 Created 1299 Location: http://www.foobar.com/cfgs/RYURUS99009 1300 Content-Length: 0 1302 3.3. Configuration Properties 1304 The standard PROPFIND and PROPPATCH methods can be used on the 1305 configuration resource to get and set properties on a 1306 configuration. Configurations MUST provide configuration 1307 properties if configurations are supported. The following list 1308 identifies pre-defined properties that MUST be supported: 1310 DAV:configurationtype - The type of the configuration. 1311 Configurations can choose to make this a read-only property. 1313 DAV:derivedfrom - The configuration from which the configuration is 1314 derived. Configurations can choose to make this a read-only 1315 property. 1317 DAV:inheritancetype - The type of inheritance for the 1318 configuration. Configurations can choose to make this a read-only 1319 property. 1321 DAV:basetime - The base time used to create the configuration. 1322 Configurations can choose to make this a read-only property. 1324 DAV:configurationame - A user-defined display name for the 1325 configuration. 1327 DAV:defaultconfiguration - This property on the configuration root 1328 identifies the default workspace configuration to use if one is not 1329 specified. 1331 3.4. Headers 1333 To support configurations, two new headers are introduced that can 1334 be used with a variety of the DAV and HTTP methods. The following 1335 list identifies these headers: 1337 Configuration-Id - This header is used to identify the 1338 configuration that is to be used when performing an operation. 1340 For workspace configurations, this can be specified to set default 1341 revisions per-configuration, enumeration of checkouts/checkins 1342 against a specific configuration, or to establish locks specific to 1343 a configuration. 1345 If a configuration is not specified, the default workspace 1346 configuration is used. All servers have a default workspace where 1347 resources reside. The configuration "*" can be specified with 1348 PROPFIND to locate properties irrespective of configuration. 1350 Configuration-Id := "Configuration-Id" ":" (URL | "*") 1352 Note that the configuration id can be used in place of a revision 1353 id. In this case, the revision selected is the default revision of 1354 the versioned resource within the specified configuration. 1356 Target-Configuration - This header is used to specify a target 1357 configuration when dealing with cross-configuration operations. 1358 For example, resources can be copied from one configuration to 1359 another using the Configuration-Id and Target-Configuration headers 1360 with the COPY method. 1362 Target-Configuration := "Target-Configuration" ":" URL 1364 3.5. Deleting Configurations 1366 To delete a configuration, use the location returned from the 1367 configuration creation. Note that configurations SHOULD NOT allow 1368 delete if other configurations are derived from them. 1370 >>Request 1372 DELETE /cfgs/RYURUS99009 HTTP/1.1 1373 Host: www.foobar.com 1374 Content-Length: 0 1376 3.6. Managing Configuration Content 1378 Clients need to be able to access and manage the contents of a 1379 configuration. This is done using the GET, COPY, and DELETE 1380 methods. 1382 3.6.1. Access Using Configurations 1384 Configurations are maintained as a special collection. 1385 Configurations maintain referential members to all revisions that 1386 are part of the configuration. Consequently, one approach to 1387 enumerating the contents of a configuration is to use PROPFIND to 1388 discover the contents of the collection. 1390 Alternatively, clients can request a specific resource from a 1391 configuration. This approach allows clients to use the URL they 1392 are familiar with. If a client requests a resource that is not 1393 part of a configuration, then an error is returned. 1395 >>Request 1397 GET /foo/bar.htm HTTP/1.1 1398 Host: www.foobar.com 1399 Configuration-Id: /cfgs/DFEE2034 1400 Version-Id: VER:JKGRKJ9094 1401 Content-Length: 0 1403 3.6.2. Adding Resources to a Configuration 1405 Resources are added to a configuration using the COPY method. A 1406 special body tag is used to indicate that the resource is being 1407 added to the configuration. 1409 >>Request 1411 COPY /foo/bar.htm HTTP/1.1 1412 Host: www.foobar.com 1413 Depth: infinity 1414 Configuration-Id: /cfgs/DFEE2034 1415 Target-Configuration: /cfgs/ERRJ3440 1416 Content-Type: text/xml 1417 Content-Length: xxxx 1419 1420 1422 If a specific revision is not specified, then the default revision 1423 is copied. 1425 Note that clients can also create referential members within the 1426 configuration collection to add them to the collection. 1428 3.6.3. Removing Resources from a Configuration 1430 Resources are removed from a configuration using the DELETE. The 1431 target URI indicates the resource to delete and the Configuration- 1432 Id header to identify the configuration. The Depth header can be 1433 used to remove collection contents. A special tag is used to 1434 indicate that the resource is being removed from the configuration 1435 (not deleted). 1437 >>Request 1438 DELETE /foo/bar.htm HTTP/1.1 1439 Host: www.foobar.com 1440 Depth: infinity 1441 Configuration-Id: /cfgs/DFEE2034 1442 Content-Type: text/xml 1443 Content-Length: xxxx 1445 1446 1448 Note that clients can also delete referential members within the 1449 configuration collection to remove them from the collection. 1451 3.7. Workspace Configurations 1453 Workspace configurations provide the ability to track multiple 1454 revisions of a resource independent of the resource in other 1455 workspace configurations. This section describes aspects of the 1456 protocol specific to workspace configurations. 1458 3.7.1. Default Workspace Configurations 1460 Clients can establish a default workspace configuration that is to 1461 be used, for all clients, if they do not specify a workspace 1462 configuration. To do this, clients set a property on the 1463 configuration namespace root collection identifying the default 1464 workspace configuration. 1466 >>Request 1468 PROPPATCH /cfgs/ HTTP/1.1 1469 Host: www.foobar.com 1470 Content-Type: text/xml 1471 Content-Length: xxxx 1473 1474 1475 1476 1477 /cfgs/RYURUS99009 1478 1479 1480 1481 1483 3.7.2. Synchronizing Worksapce Configurations 1485 In some scenarios, clients are working on separate workspace 1486 configurations to keep themselves isolated from other team members. 1487 However, they occasionally need to synchronize their workspace 1488 configuration with the derived-from workspace configuration so that 1489 they don�t get too far out of synchronization. As well, changes 1490 (or entire configurations) can be copied from one workspace 1491 configuration to another. Both operations are performed using the 1492 COPY method and special body tags. 1494 Clients can request that specific resources are copied by including 1495 the resource tag. If no resources are specified, then all 1496 resources are copied. Note that configurations MAY fail requests 1497 that do not fully synchronize. 1499 The example below shows the synchronization of one configuration 1500 against another. All resources are synchronized. 1502 >>Request 1504 COPY /cfgs/DHFHR99392 HTTP/1.1 1505 Host: www.foobar.com 1506 Destination: http://www.foobar.com/cfgs/RRURU329049 1507 Content-Type: text/xml 1508 Content-Length: xxx 1510 1511 1513 The example below shows the synchronization of one configuration 1514 against another. The specified resources are synchronized to the 1515 indicated time. 1517 >>Request 1519 COPY /cfgs/DHFHR99392 HTTP/1.1 1520 Host: www.foobar.com 1521 Destination: http://www.foobar.com/cfgs/RRURU329049 1522 Content-Type: text/xml 1523 Content-Length: xxx 1525 1526 1527 /foo/bar.htm 1528 /bing/bop.htm 1529 ... 1530 1532 A synchronization request could result in conflicts. By default, 1533 if conflicts exist, the synchronization fails and the conflicts are 1534 returned (as shown below). To override, clients should include the 1535 tag. This tag indicates that the synchronization 1536 should do as much as possible and return any conflicts. 1538 >>Response 1540 TBD - show failure response 1541 ... 1542 1543 1544 http://www.foobar.com/foo/bar.htm 1545 1546 VER:DJHFH443 1547 VER:DJHFH443 1548 VER:FDFEE55544 1550 1551 1552 ... 1553 1554 ... 1556 The sample response above shows that each conflict includes an ID 1557 and a reference to the resource in conflict. A configuration MAY 1558 choose to restrict operations until conflicts have been resolved. 1559 To inform the configuration that a conflict has been resolved, 1560 clients should include a Conflict-ID header on PUT, PROPPATCH, etc. 1561 methods specifying the ID returned in the synchronization response. 1563 Conflict-ID := "Conflict-ID" ":" URI 1565 It is permitted for servers to refuse (fail) synchronization 1566 requests that do not originate at the root. That is, arbitrary 1567 resources. 1569 3.7.3. Condensing Workspace Configurations 1571 Condensing a configuration means reducing the number of revisions 1572 in a configuration. That is, collapse the changes into a single 1573 revision. This is performed by extending the DELETE method. In 1574 the example below, all but the latest three versions are condensed 1575 into a single revision. 1577 >>Request 1579 DELETE /cfgs/BHFR59593 HTTP/1.1 1580 Host: www.foobar.com 1581 Content-Type: text/xml 1582 Content-Length: xxxx 1584 1585 1586 /foo/bar.htm3 1587 1589 Note that the DAV:maxrevisions property can be used to set the 1590 maximum number of revisions that are maintained for a versioned 1591 resource. 1593 If the DAV:revisionid header is specified, the condensing starts 1594 with the specified revision. This means that if a versioned 1595 resource has 10 revisions, revisions 3-6 can be condensed. 1597 Servers MUST fail this request if there are dependencies on 1598 revisions that will be eliminated. 1600 3.8. Configuration Reports 1602 Revision history and configuration dependency graphs are accessed 1603 via PROPFIND. Note that configurations MAY support multiple styles 1604 of history and dependency. To enumerate the supported history 1605 graphs, clients use PROPFIND and the property. 1606 The results indicate the different graphs and reports which can, 1607 themselves, be requested via PROPFIND. 1609 >>Request 1611 PROPFIND /cfgs/FHJRH3994 HTTP/1.1 1612 Host: www.foobar.com 1613 Content-Type: text/xml 1614 Content-Length: xxxx 1616 1617 1618 1619 1621 >>Response 1623 ... 1624 1625 1626 1627 DAV:configurationderivation 1628 1629 DAV:configurationmerge 1630 1631 1632 1633 ... 1635 Note that the report styles MUST be specified as DAV:href values. 1637 3.8.1. Configuration Derivation 1639 Configurations MUST support the DAV:configurationderivation report. 1640 This enumerates the full derivation of a configuraiton. Note that 1641 the limit parameter can be specified to limit the number of items 1642 returned. By definition the order of the configurations is 1643 immediate predecessor. 1645 >>Request 1647 PROPFIND /cfgs/BHFR59593 HTTP/1.1 1648 Host: www.foobar.com 1649 Content-Type: text/xml 1650 Content-Length: xxxx 1652 1653 1654 1655 1657 >>Response 1659 ... 1660 1661 1662 1663 1664 1665 1666 1667 1668 ... 1670 3.8.2. Configuration Merge Graph 1672 Configurations SHOULD support the DAV:configurationmerge report. 1673 This enumerates the derivation of a configuration including merges 1674 from one configuration to another. 1676 >>Request 1678 PROPFIND /cfgs/BHFR59593 HTTP/1.1 1679 Host: www.foobar.com 1680 Content-Type: text/xml 1681 Content-Length: xxxx 1683 1684 1685 1686 1688 >>Response 1690 ... 1691 1692 1693 1694 1696 1698 1700 1702 1704 1705 1706 1707 1708 1709 1710 ... 1712 3.9. Resolution Queues 1714 When configurations inherit, there is the potential for conflicts. 1715 Configurations have the option to help clients manage these 1716 conflicts. However, if they do not, then configurations MUST 1717 return an error if the operation would result in a conflict. 1719 Configurations that help resolve conflicts track and maintain lists 1720 of issues that need to be resolved as a result of actions. These 1721 lists are referred to as resolution queues. Clients can request 1722 the resolution issues and react accordingly. Note that the 1723 configuration only manages the list. That is, the client is 1724 responsible for resolving the issue (or deciding not to) and then 1725 removing the resolution item. 1727 3.9.1. Discovery 1729 Resolution queue support is optional for configurations. Support 1730 for resolution queues is determined by examining the 1731 DAV:resolutionqueue property on a configuration. If this property 1732 is not blank, then the configuration supports a resolution queue at 1733 the specified URL. If this property is blank, then it doesn�t 1734 support resolution queues. 1736 3.9.2. Obtaining Resolutions 1738 Conflicts can arise against any resource, however, they are always 1739 associated with a configuration. Pending resolutions items are 1740 obtained by examining the resolution queue for a configuration. 1741 The resolution queue is actually a configuration-specific 1742 collection in the DAV namespace. The collection resource 1743 identifying the resolution queue for a configuration is obtained 1744 via the DAV:resolutionqueue property on the configuration. To 1745 enumerate the pending resolutions, clients use PROPFIND to obtain 1746 the resources within the collection. 1748 Each resource within the collection represents a separate 1749 resolution queue item and are named such that a standard ANSI sort 1750 on the resource name will ensure correct temporal ordering. 1752 3.9.3. Processing Resolution Items 1754 Clients can GET the contents of a resolution item. This is an XML 1755 document that describes the action that caused the resolution item 1756 to be created. For example: 1758 1759 1760 http://foobar.com/reso/ZZZZ3493 1761 http:/foo/bar.htm 1762 DAV:FDFEE55544 1763 1765 Once a client has resolved an issue (or decided to ignore it), the 1766 client is responsible for canceling the resolution item. This is 1767 done using the DELETE method on the resolution item. 1769 >>Request 1770 DELETE http://foobar.com/reso/ZZZZ3493 HTTP/1.1 1771 Host: www.foobar.com 1772 Content-Type: text/xml 1773 Content-Length: 0 1775 3.10. Checkin Sets 1777 Clients may desire the ability to track a set of changes as a unit. 1778 That is, create a grouping of related changes. This is achieved 1779 using the MKCOL method to create a special collection. Clients 1780 refer to the checkin set on all checkin (or change) requests. The 1781 server automatically creates a "share" to the newly created 1782 revision in the identified collection. 1784 3.10.1. Discovery 1786 Servers may choose to restrict where checkin sets can be created in 1787 the namespace. Clients can discover this using OPTIONS. The 1788 Checkin-Sets-Root header identifies valid portions in the 1789 namespace. Each header (there can be multiple specified) identify 1790 a root and a depth. The BNF for this header is: 1792 Checkin-Sets-Root:= "Checkin-Sets-Root" ":" URL "," Depth 1793 Depth := "inifinity" | number 1795 Note that if a resource�s parent in the namespace has a defined 1796 checkin set root, the resource CANNOT define a separate root for 1797 itself. 1799 This example shows how to discover the checkin set root for the 1800 /somefolder resource. 1802 >> Request 1804 OPTIONS /somefolder/ HTTP/1.1 1805 Verify-Extension: DAV:versioning 1806 Host: foobar.com 1807 Content-Length: 0 1809 >> Response 1811 HTTP/1.1 200 OK 1812 Date: Tue, 20 Jan 1998 20:52:29 GMT 1813 Connection: close 1814 Accept-Ranges: none 1815 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 1816 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF 1817 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 1818 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF 1819 Verify-Extension: DAV:versioning 1820 Versioning-Support: DAV:basicversioning, DAV:configurations, 1821 DAV:checkinsets 1822 Checkin-Sets-Root: /, infinity 1823 Content-Length: 0 1825 3.10.2. Usage 1827 Clients create checkin sets using MKCOL and specify a special body 1828 tag to indicate that a checkin set collection is being created. 1830 >>Request 1832 MKCOL /cs/244 HTTP/1.1 1833 Host: www.foobar.com 1834 Content-Type: text/xml 1835 Content-Length: xxxx 1837 1838 1840 Clients refer to this checkin set using the Checkin-Set header. 1841 The BNF for this header is as follows: 1843 Checkin-Set := "Checkin-Set" ":" URI 1845 The following example illustrates use of checkin sets. 1847 >>Request 1849 UNLOCK /foo/bar HTTP/1.1 1850 Host: www.foobar.com 1851 Lock-Token: 1852 Checkin-Set: /cs/244 1853 Content-Type: text/html 1854 Content-Length: xxxx 1856 1857 ... 1858 1860 The following properties MUST be supported on all checkin set 1861 collections: 1863 DAV:closed - This is a true (1) / false (0) property that indicates 1864 if this checkin set can be referenced in CHECKIN requests. When a 1865 checkin set is created, this property is defaulted to 0. Note that 1866 resources MAY choose to disallow clients from setting this property 1867 to 0 once a client has set it to 1. 1869 The following properties MUST be supported on all resources: 1871 DAV:checkinid - This read-only property returns the checkin id 1872 associated with this revision of the resource. 1874 4. VERSION MAPPING 1876 This specification defines headers to specify configurations and 1877 resource versions. However, there are times when clients require a 1878 single URI for when working against configurations or versions. 1879 Version mapping support allows servers to create namespaces that 1880 map to configurations and versions. 1882 Note that mappings are dynamic. That is, as resources are added, 1883 removed, and modified, the changes are reflected in any active 1884 maps. 1886 4.1. Discovery 1888 Version mapping support is optional. This example shows that the 1889 /cfgs/DFEE2034 configuration supports mapping to the /map/ root in 1890 the namespace. 1892 >> Request 1894 OPTIONS /cfgs/DFEE2034 HTTP/1.1 1895 Verify-Extension: DAV:versioning 1896 Host: foobar.com 1897 Content-Length: 0 1899 >> Response 1901 HTTP/1.1 200 OK 1902 Date: Tue, 20 Jan 1998 20:52:29 GMT 1903 Connection: close 1904 Accept-Ranges: none 1905 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 1906 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF 1907 Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, 1908 MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF 1909 Verify-Extension: DAV:versioning 1910 Versioning-Support: DAV:basicversioning, DAV:mapping 1911 Mapping-Root: /map/ 1912 Mapping-Styles: DAV:detailedmap, DAV:branchmap, DAV:nestedbranch 1913 Content-Length: 0 1915 The BNF for this OPTIONS header is as follows: 1917 Mapping-Root := "Mapping-Root" ":" URL 1919 Mapping-Styles := "Mapping-Styles" ":" URL-List 1921 Note that multiple Mapping-Root headers is permitted. 1923 4.2. Mapping Configurations 1925 The MKCOL method is used to create namespaces based on a 1926 configuration. When a configuration is mapped to a new namespace, 1927 all elements within the configuration can be directly accessed 1928 within the namespace without requiring the configuration to be 1929 identified in the header. 1931 In the example below, a new namespace is created for accessing the 1932 contents of the /cfgs/DFEE2034 configuration. 1934 >> Request 1936 MKCOL /map/mymap HTTP/1.1 1937 Host: foobar.com 1938 Configuration-Id: /cfgs/DFEE2034 1939 Content-Type: text/xml 1940 Content-Length: xxxx 1942 1943 1945 >> Response 1947 HTTP/1.1 201 CREATED 1948 Context-Length: 0 1950 4.3. Mapping Resource Versions 1952 The MKCOL method is also used to create namespaces based on a 1953 resource�s versions (i.e., its revision graph). When a resource is 1954 mapped, its revision history (revision graph) within the 1955 configuration is made available without requiring the Revision-Id 1956 header. Within the mapped namespace, a hierarchy is created for 1957 the revisions. 1959 However, there are different ways to map the history. Consider the 1960 following revision history of the versioned resource bar.htm: 1962 V1 -> V2 -> V3 (primary branch) 1963 | 1964 +-> V1.1 -> V1.2 ("test" branch) 1966 The following diagrams illustrate possible mappings: 1968 (DAV:detailedmap) (DAV:branchmap) (DAV:nestedbranchmap) 1970 V1 Primary Test Primary 1971 | | | | 1972 +----+--------+ V1 V1.1 +------Test 1973 | | | | | | | 1974 V2 bar.htm V1.1 V2 V1.2 V1 V1.1 1975 | | | | | 1976 +----+ +-----+ V3 V2 V1.2 1977 | | | | | 1978 V3 bar.htm V1.2 bar.htm V3 1979 | | 1980 bar.htm bar.htm 1982 In the example below, a new namespace is created for accessing the 1983 versions of the /foo/bar.htm resource in the /cfgs/DFEE2034 1984 configuration. 1986 >> Request 1987 MKCOL /map/mymap2 HTTP/1.1 1988 Host: foobar.com 1989 Configuration-Id: /cfgs/DFEE2034 1990 Content-Type: text/xml 1991 Content-Length: xxx 1993 1994 1995 /foo/bar.htm 1996 DAV:detailedmap 1997 1999 >> Response 2001 HTTP/1.1 201 CREATED 2002 Context-Length: 0 2004 Note that resources MAY support any mapping styles, however, if 2005 they support DAV:detailedmap, DAV:branchmap, or 2006 DAV:nestedbranchmap, they must map as illustrated above. 2008 5. MISCELLANEOUS FUNCTIONS 2010 The following sub-sections detail miscellaneous versioning 2011 functions. 2013 5.1. Destroy 2015 Many version management systems use tombstones to note deleted 2016 items. These systems also support the ability to permanently 2017 destroy tombstones for an object. The DESTROY method provides this 2018 functionality and resources SHOULD support it, but resources are 2019 not required to implement it. Resources MUST return an error for 2020 DESTROY requests that are not honored. 2022 5.1.1. Discovery 2024 Discovery of this feature is determined by seeing if the resource 2025 options include the DESTROY method. 2027 5.1.2. Usage 2029 The DESTROY method is used against a specific resource to 2030 permanently remove it. This is a namespace level-operation. That 2031 is, all resources matching the specified URI are destroyed. 2033 >>Request 2035 DESTROY /foo/bar/x.cpp HTTP/1.1 2036 Host: www.foobar.com 2037 Content-Type: text/xml 2038 Content-Length: xxxx 2039 Note that this request can be qualified by a configuration. 2040 Requests to DESTROY resources that are in use by other 2041 configurations MAY fail or delay the destruction until all 2042 references are removed. 2044 5.1.3. Headers 2046 Clients may chose to display deleted but not destroyed objects 2047 however they choose. The header keyword Show-Deleted is used to 2048 indicate if deleted items should be included in the GET request. 2049 By default, they are not. Inclusion of "Show-Deleted: Y" indicates 2050 that deleted resources should be included. Using "Show-Deleted: O" 2051 indicates that only resources that have been deleted should be 2052 returned. Using "Show-Deleted: N" indicates that deleted resources 2053 shouldn�t be returned. 2055 Show-Deleted := "Show-Deleted" ":" ("Y" | "N" | "O") 2057 5.1.4. Properties 2059 DAV:isdeleted - A 0/1 property where 1 indicates that the resource 2060 has been deleted. 2062 6. THE DAV VERSIONING GRAMMAR 2064 To be supplied - Describe and detail the DTDs 2066 7. INTERNATIONALIZATION CONSIDERATIONS 2068 To be supplied. 2070 8. SECURITY CONSIDERATIONS 2072 To be supplied. 2074 9. SCALABILITY 2076 To be supplied. 2078 10. AUTHENTICATION 2080 Authentication mechanisms defined in WebDAV will also apply to DAV 2081 Versioning. 2083 11. IANA CONSIDERATIONS 2085 This document uses the namespace defined by [WebDAV] for XML 2086 elements. All other IANA considerations mentioned in [WebDAV] also 2087 applicable to DAV Versioning. 2089 12. COPYRIGHT 2091 To be supplied. 2093 13. INTELLECTUAL PROPERTY 2095 To be supplied. 2097 14. REFERENCES 2099 [DAVVERREQ] TBD, "Requirements for DAV Versioning and Variant 2100 Authoring", October 1998, work-in-progress, draft-ietf-webdav- 2101 versionreqs-00.txt 2103 [Kaler] C. Kaler, "Versioning Extensions for WebDAV", September 2104 1998, internet-draft, work-in-progress, draft-kaler-webdav- 2105 versioning-00. 2107 [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. 2108 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, 2109 U.C. Irvine, DEC, MIT/LCS, January 1997. 2111 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 2112 Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 2113 1997. 2115 [WebDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D. 2116 Jenson, "Extensions for Distributed Authoring on the World Wide 2117 Web", October 1998, internet-draft, work-in-progress, draft-ietf- 2118 webdav-protocol-09. 2120 [White] E.J. Whitehead, "A Web Versioning Protocol", June 1998, 2121 internet-draft, work-in-progress, draft-whitehead-webdav- 2122 versioning-00. 2124 15. AUTHOR'S ADDRESSES 2126 Christopher Kaler, Editor 2127 Microsoft 2128 One Microsoft Way 2129 Redmond WA, 9085-6933 2130 Email:ckaler@microsoft.com 2132 E. James Whitehead, Jr. 2133 Dept. of Information and Computer Science 2134 University of California, Irvine 2135 Irvine, CA 92697-3425 2136 Email: ejw@ics.uci.edu 2138 TBD - list all members of the working group 2140 16. OPEN ISSUES 2142 The following list identifies key open issues against this 2143 document: 2145 - Can you checkout a collection? What does it mean? 2147 - What tags do we want to use for resource/configuration report 2148 results? 2150 - What structure do we create for maps? 2152 - What time format should we use? 2154 - Should PIN be a method or a property? 2156 - What additional resource branching support is needed? 2158 - Schema discovery is an issue. For example, how to 2159 discover/change mutable/immutable properties? 2161 - There are several missing examples / replies that need to be 2162 specified. 2164 17. CHANGE HISTORY 2166 Sep 28, 1998 2168 Initial Draft based on [White] and [Kaler]. 2170 Oct 24, 1998 2172 Incorporate feedback from October 01-02 working group meeting.