idnits 2.17.1 draft-ietf-webdav-versioning-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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. == There is 1 instance 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 14 longer pages, the longest (page 6) being 66 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 31 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 214 instances of too long lines in the document, the longest one being 2 characters in excess of 72. == There are 10 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 203 has weird spacing: '... set of ortho...' == Line 679 has weird spacing: '... set of immut...' == Line 920 has weird spacing: '...lection to re...' == Line 1055 has weird spacing: '...RL's of the r...' == Line 1519 has weird spacing: '...nged if both ...' -- 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 25, 1999) is 9043 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) == Missing Reference: 'Merging' is mentioned on line 915, but not defined == Missing Reference: 'Activity' is mentioned on line 989, but not defined == Missing Reference: 'Core' is mentioned on line 1057, but not defined == Missing Reference: 'Activty' is mentioned on line 1000, but not defined == Missing Reference: 'Configuration' is mentioned on line 1015, but not defined == Missing Reference: 'Baseline' is mentioned on line 1027, but not defined == Missing Reference: 'RFC2026' is mentioned on line 1552, but not defined ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2518 (Obsoleted by RFC 4918) -- Possible downref: Non-RFC (?) normative reference: ref. 'AdvCol' -- Possible downref: Non-RFC (?) normative reference: ref. 'VerGoal' Summary: 7 errors (**), 0 flaws (~~), 17 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Geoffrey Clemm, Rational Software 2 draft-ietf-webdav-versioning-02.txt Chris Kaler, Microsoft 4 Expires December 25, 1999 June 25, 1999 6 Versioning Extensions to WebDAV 8 Status of this Memo. 10 This document is an Internet-Draft and is in full conformance with all 11 provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering Task 14 Force (IETF), its areas, and its working groups. Note that other groups 15 may also distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference material 20 or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Abstract 30 This document specifies a set of methods, headers, and resource-types 31 that define the WebDAV Versioning extensions to the HTTP/1.1 protocol. 32 WebDAV Versioning will minimize the complexity of clients so as to 33 facilitate widespread deployment of applications capable of utilizing 34 the WebDAV Versioning services. WebDAV Versioning includes: 36 - Automatic versioning support for versioning-unaware clients, 38 - Linear versioning , and 40 - Support for parallel development and configuration management. 42 Table of Contents 44 VERSIONING EXTENSIONS TO WEBDAV...........................1 46 STATUS OF THIS MEMO.......................................1 48 ABSTRACT..................................................1 50 TABLE OF CONTENTS.........................................2 52 1 INTRODUCTION...........................................4 53 1.1 Relationship to DAV.................................4 54 1.2 Terms...............................................5 55 1.3 Notational Conventions..............................5 57 2 CONCEPTS AND DEFINITIONS...............................5 59 3 WEBDAV VERSIONING SEMANTICS...........................10 60 3.1 Creating Versioned Resources.......................10 61 3.2 Modifying a Versioned Resource.....................11 62 3.3 Naming Revisions: Revision Ids and Labels..........11 63 3.4 Parallel Development and Activities................12 64 3.5 Revision Selection and Workspaces..................12 65 3.6 Configurations.....................................13 66 3.7 Versioned Collections..............................13 68 4 VERSIONING RESOURCE TYPES AND PROPERTIES..............14 69 4.1 Property Attributes................................14 70 4.1.1 Writeable/Readonly Properties....................14 71 4.1.2 Immutable/Mutable Properties.....................14 72 4.1.3 Property Resources...............................14 73 4.2 Resource Properties................................15 74 4.2.1 DAV:author (immutable) [Core]...................15 75 4.2.2 DAV:comment (immutable) [Core]..................15 76 4.3 Revision Properties................................15 77 4.3.1 DAV:revision-id (readonly) [Core]................15 78 4.3.2 DAV:predecessor (readonly, resource) [Core]......15 79 4.3.3 DAV:successors (readonly, mutable, collection)...15 80 4.3.4 DAV:single-checkout (mutable) [Core].............15 81 4.3.5 DAV:auto-version (mutable) [Core]................16 82 4.3.6 DAV:revision-labels (mutable) [Core].............16 83 4.3.7 DAV:checkin-date (readonly) [Core]...............16 84 4.3.8 DAV:working-resources (readonly, collection) ....16 85 4.3.9 DAV:history-uuid (readonly) [Core]...............16 86 4.3.10DAV:history (readonly, resource) [Core]..........16 87 4.3.11DAV:merge-predecessors (mutable, collection).....16 88 4.3.12DAV:merge-successors ............................17 89 4.4 Working Resource Properties........................17 90 4.4.1 DAV:workspace (readonly, resource) [Core]........17 91 4.4.2 DAV:predecessor (read-only, resource) [Core].....17 92 4.4.3 DAV:checkin-policy [Core]........................17 93 4.4.4 DAV:merge-predecessors (collection) [Merging]....18 94 4.4.5 DAV:activity (readonly, resource) [Activity].....18 95 4.5 Workspace Properties...............................18 96 4.5.1 DAV:working-resources (readonly, collection) ....18 97 4.5.2 DAV:revision-selection-rule [Core]..............18 98 4.5.3 DAV:label [Core].................................19 99 4.5.4 DAV:activity [Activity]..........................19 100 4.6 Activity Properties................................19 101 4.6.1 DAV:revisions (readonly, collection) [Activity]..19 102 4.6.2 DAV:required-activities (collection) [Activity]..19 103 4.6.3 DAV:workspace (resource) [Activty]...............19 104 4.7 Configuration Properties...........................19 105 4.7.1 DAV:roots (immutable, collection) [Configuration]20 106 4.8 Versioned Collection Properties....................20 107 4.8.1 DAV:baselines (resource) [Baseline]..............20 108 4.9 History Resource Properties........................20 109 4.9.1 DAV:uuid (readonly) [Core].......................20 110 4.9.2 DAV:revisions (readonly, collection) [Core]......20 111 4.9.3 DAV:revision-labels (collection) [Core]..........20 113 5 VERSIONING METHODS....................................21 114 5.1 Existing Methods...................................21 115 5.1.1 GET..............................................21 116 5.1.2 BIND.............................................21 117 5.1.3 PUT..............................................21 118 5.1.4 PROPFIND.........................................22 119 5.1.5 PROPPATCH........................................22 120 5.1.6 DELETE...........................................22 121 5.1.7 COPY.............................................22 122 5.1.8 MOVE.............................................22 123 5.1.9 LOCK.............................................23 124 5.1.10 OPTIONS..........................................23 125 5.2 New Methods........................................23 126 5.2.1 MKRESOURCE.......................................23 127 5.2.2 REPORT...........................................24 128 5.3 New Versioning Methods.............................24 129 5.3.1 CHECKOUT.........................................24 130 5.3.2 CHECKIN..........................................25 131 5.3.3 UNCHECKOUT.......................................25 132 5.4 New Versioning Headers.............................26 133 5.4.1 Target-Selector..................................26 135 6 THE DAV VERSIONING XML ELEMENTS.......................26 136 6.1 Revision Selection Rule Elements...................26 137 6.1.1 DAV:rsr-configuration............................26 138 6.1.2 DAV:rsr-activity-latest..........................26 139 6.1.3 DAV:rsr-label....................................27 140 6.1.4 DAV:rsr-revision-id..............................27 141 6.1.5 DAV:rsr-latest...................................27 142 6.1.6 DAV:rsr-or.......................................27 143 6.1.7 DAV:rsr-merge....................................27 144 6.2 Report Elements....................................28 145 6.2.1 Conflicts Report.................................28 146 6.2.2 Compare Report...................................28 148 7 INTERNATIONALIZATION CONSIDERATIONS...................29 150 8 SECURITY CONSIDERATIONS...............................29 152 9 SCALABILITY...........................................29 154 10 AUTHENTICATION......................................30 156 11 IANA CONSIDERATIONS..................................30 158 12 INTELLECTUAL PROPERTY................................30 160 13 ACKNOWLEDGEMENTS.....................................30 162 14 INDEX................................................30 164 15 REFERENCES...........................................31 166 16 AUTHORS ADDRESSES....................................31 168 17 OPEN ISSUES..........................................31 170 1 INTRODUCTION 172 This document defines DAV Versioning extensions, an application of 173 HTTP/1.1 for handling resource versioning in a DAV environment. 174 [VerGoal] describes the motivation and requirements for DAV 175 Versioning. 177 DAV Versioning will minimize the complexity of clients so as to 178 facilitate widespread deployment of applications capable of 179 utilizing the DAV services. As well, DAV Versioning supports a 180 rich level of versioning options for versioning-aware clients. 182 DAV Versioning consists of: 184 - Automatic versioning support for versioning-unaware clients, 186 - Linear versioning , and 188 - Support for parallel development and configuration management. 190 1.1 Relationship to DAV 192 To maximize interoperability and use of existing protocol 193 functionality, versioning support is designed as extensions to the 194 WebDAV [RFC2518] and advanced-collection protocols [AdvCol]. In 195 particular, DAV Versioning relies on the resource and property 196 model defined by [RFC2518] and the binding model defined by 197 [AdvCol]. The versioning protocol is designed so that WebDAV 198 locking (class 2) support is optional. The effect of a lock on 199 versioning methods and content-types will be defined to provide 200 interoperability of servers that provide locking support. 202 Versioning support is defined in the form of Core versioning 203 support, supplemented by a set of orthogonal extensions to the 204 Core: Activity, Merging, Configuration, Versioned Collection, and 205 Baseline versioning support. Core support provides versioning of 206 largely independent resources. It allows authors to concurrently 207 create and access distinct revisions of a resource. Activity 208 support extends Core support with logical change tracking and 209 management through activities. Merging support extends Core 210 support with conflict detection and resolution through merging. 211 Configuration support extends Core support with the creation of 212 sets of consistent revisions. Versioned Collection support extends 213 Core support with the ability to version the URL namespace. 214 Baseline support extends Configuration and Versioned Collection 215 support with the ability to create and compare configurations of 216 all revisions in a URL subtree. 218 Throughout this specification the [xyz] notation is used to 219 indicate that a property is introduced at the "xyz" level of 220 versioning support. The levels of versioning support provided by a 221 server can be discovered via an OPTIONS request. 223 1.2 Terms 225 This draft uses the terms defined in [RFC2068] and [RFC2518]. 227 1.3 Notational Conventions 229 The augmented BNF used by this document to describe protocol 230 elements is exactly the same as the one described in Section 2.1 of 231 [RFC2068]. Because this augmented BNF uses the basic production 232 rules provided in Section 2.2 of [RFC2068], those rules apply to 233 this document as well. 235 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 236 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 237 this document are to be interpreted as described in [RFC2119]. 239 2 CONCEPTS AND DEFINITIONS 241 The section presents the versioning concepts and terms/definitions 242 used in this protocol. 244 Versionable Resource 246 A versionable resource is a resource that can be placed under 247 version control. A null resource is a versionable resource. 249 Versioned Resource 251 A versioned resource is a resource that is under version control. 252 To update a resource under version control, it must be checked out 253 and then subsequently checked in. The checked in states of a 254 versioned resource are saved by the server to capture the history 255 of that resource. 257 Revision 258 A revision contains a particular state of a versioned resource. An 259 immutable revision is a revision whose body and immutable 260 properties cannot be modified. A mutable revision is a revision 261 whose state can be overwritten by a subsequent check in request. 263 Revision Name 265 A revision name is a name that can be used to identify a single 266 revision of a versioned resource. There are two types of revision 267 names: revision identifiers and revision labels. 269 Revision Identifier 271 A revision identifier (or revision ID) is a revision name that is 272 assigned by the server when the revision is created and cannot be 273 changed to refer to a different revision. 275 Revision Label 277 A revision label is a revision name that is assigned by a client 278 and may later be changed to refer to a different revision. The same 279 label may be assigned to many different versioned resources. 281 Initial Revision 283 An initial revision is the first revision of a versioned resource. 285 Predecessor, Successor 287 A predecessor of a revision is the previous revision that was 288 checked out to create the revision. A successor of a revision is a 289 revision whose predecessor is that revision. Each revision has a 290 single predecessor (except for the initial revision which has no 291 predecessor) and zero or more successors. 293 Merge Predecessor, Merge Successor 295 A merge predecessor of a revision is a revision that has been 296 merged into this revision. A merge successor of a revision is a 297 revision into which that revision has been merged. A revision can 298 have zero or more merge predecessors and zero or more merge 299 successors. 301 Line Of Descent 303 A line of descent to a specified revision is a sequence of 304 revisions connected by successor relationships from the initial 305 revision to that revision. 307 The following diagram illustrates several of the previous 308 definitions. 310 Versioned --> Foo.htm 311 Resource 312 +----+ \ 313 Label --> "initial" | V1 | | | 314 \ +----+ | | 315 \ | | | 316 \ v | | 317 \ +----+ | Line | 318 -> "beta1" | V2 | | of | 319 +----+ | Descent | 320 / | | | 321 v v | | 322 +----+ +----+ | | 323 Revision Id --> | V3 | | V4 | | | History 324 +----+ +----+ | | 325 ^ | | | | 326 | v v | | 327 Predecessor | +----+ +----+ v | 328 | V5 | | V6 | | 329 +----+ +----+ | 330 \ | | Successor | 331 | v v | | 332 Merge Successor | +----+ v | 333 v | V7 | | 334 +----+ / 336 Immutable/Mutable Property 338 An immutable property is a property of an immutable revision that 339 cannot be changed. A mutable property is a property of an 340 immutable revision that can be changed. Only properties of 341 revisions can be immutable or mutable. 343 Working Resource 345 A working resource is an editable resource created by checking out 346 a revision of a versioned resource. 348 Checkout/Checkin Model 350 The checkout/checkin model is the process by which updates are made 351 to a versioned resource. A versioned resource is checked out to 352 create an editable working resource. The working resource is 353 updated or augmented as desired, and then checked in to make it 354 part of the revision history of the versioned resource. 356 The following diagram illustrates the checkout/checkin process. 358 ===CHECKOUT==> ===CHECKIN==> 360 Foo.htm | Foo.htm | Foo.htm 361 | | 362 +----+ | +----+ | +----+ 363 | V1 | | | V1 | | | V1 | 364 +----+ | +----+ | +----+ 365 | | | | | 366 v | v | v 367 +----+ | +----+ | +----+ 368 | V2 | | | V2 | | | V2 | 369 +----+ | +----+ | +----+ 370 | | | | 371 | v | v 372 | +----+ | +----+ 373 | | WR | | | V3 | 374 | +----+ | +----+ 376 Activity 378 An activity is a resource that selects a set of revisions that 379 correspond to some unit of work or conceptual change. An activity 380 can contain revisions of multiple versioned resources, and multiple 381 revisions of the same versioned resource. If an activity contains 382 multiple revisions of the same versioned resource, all of those 383 revisions must be on a single line of descent to one of those 384 revisions, and this revision is called the latest revision selected 385 by that activity for that versioned resource. 387 The following diagram illustrates activities. Revision V3 is the 388 latest revision of Foo.htm selected by activity 2, and revision V7 389 is the latest revision of Bar.htm selected by activity 2. 391 Foo.htm | Bar.htm 392 | 393 +----+ | +----+ 394 | V1 | | | V5 | 395 +----+ | +----+ 396 | Activity | | Activity 397 v 1 | v 2 398 +----+ | +----+ 399 | V2 | | | V6 | 400 +----+ | +----+ 401 | Activity | | Activity 402 v 2 | v 2 403 +----+ | +----+ 404 | V3 | | | V7 | 405 +----+ | +----+ 406 | | Activity 407 | v 3 408 | +----+ 409 | | V8 | 410 | +----+ 412 Workspace 414 A workspace is a resource that is used to identify working 415 resources. A workspace can also contain a revision selection rule 416 that specifies what revision of an arbitrary versioned resource 417 should be accessed when the resource is referenced in the context 418 of that workspace. A revision selection rule provides revision 419 selection based on criteria such as revision name, latest in an 420 activity, and membership in a configuration. 422 A workspace that does not contain a revision selection rule (and 423 therefore can only be used to identify working resources) is called 424 a basic workspace. A workspace that contains a revision selection 425 rule (and therefore can be used to specify revision selection) is 426 called an extended workspace. 428 The following diagram illustrates an extended workspace. 430 Foo.htm Bar.htm Bing.htm 431 +----+ +----+ 432 | V1 | | V1 | 433 +----+ +----+ 434 | | 435 | | 436 +-----------------|------------|------------------+ 437 | v v | 438 | +----+ +----+ +----+ | 439 | | V1 | | V2 | | WR | Workspace X | 440 | +----+ +----+ +----+ | 441 | | | 442 +-----------------|-------------------------------+ 443 | 444 v 445 +----+ 446 | V3 | 447 +----+ 449 Target 451 The target of a versioned resource is the working resource or 452 revision of that versioned resource that is selected by the current 453 workspace. 455 Conflict Report 457 A conflict report lists all versioned resources for which the 458 revision selection rule of a workspace selects multiple revisions 459 on different lines of descent. A conflict is resolved by checking 460 out one of the selected revisions, modifying the resulting working 461 resource so that it represents the logical merge of all selected 462 revisions, and then indicating these merges by adding these 463 revisions as merge predecessors of the working resource. Checking 464 in this working resource creates a new revision that resolves the 465 conflict. 467 Default Workspace 469 A server MUST provide a default workspace that is used to perform 470 version selection for versioning-unaware clients. The revision 471 selection rule of the default workspace MAY be a modifiable by a 472 client. 474 Default Target 476 The default target of a versioned resource is the target selected 477 by the default workspace. 479 Configuration 481 A configuration selects a particular revision from each of a set of 482 versioned resources. Unlike a workspace, which can select both 483 working resources and revisions, a configuration can only select 484 revisions. Also, while the revision selected by a workspace for a 485 versioned resource can change as a result of a change to the 486 versioned resource (such as adding a label), the revision selected 487 by a configuration can change only by explicitly modifying the 488 configuration itself. Unlike an activity, a configuration can 489 select at most one revisions of a given versioned resource. Unlike 490 both a workspace and an activity, a configuration can be versioned. 492 The following diagram illustrates a configuration. 494 Foo.htm Bar.htm Bing.htm 496 +----+ 497 | V1 | 498 +----+ 499 | 500 | 501 +-----------------|-------------------------------+ 502 | | | 503 | +----+ +----+ +----+ Configuration | 504 | | V1 | | V2 | | V1 | V1.1 | 505 | +----+ +----+ +----+ | 506 | | | | 507 +-----------------|------------|------------------| 508 | | 509 v v 510 +----+ +----+ 511 | V3 | | V2 | 512 +----+ +----+ 514 Versioned Collection 516 A versioned collection is a type of versioned resource that results 517 from placing a collection under version control. The members of a 518 versioned collection revision are all versioned resources. 520 Baselined Collection 522 A baselined collection is a special type of versioned collection 523 that is associated with a versioned configuration. A revision of 524 the associated versioned configuration is called a baseline of the 525 baselined collection. A baseline contains a revision of the 526 versioned collection and a revision of every member of every 527 versioned collection revision in that baseline. 529 History Resource 531 A history resource for a versioned resource contains all revisions 532 of that versioned resource. 534 3 WEBDAV VERSIONING SEMANTICS 536 3.1 Creating Versioned Resources 538 A resource may or may not be versioned. When a resource is created 539 by a PUT or MKRESOURCE request, it is commonly created as an 540 unversioned resource. Some unversioned resources can be put under 541 version control; these are called versionable resources. After a 542 resource is put under version control, it becomes a versioned 543 resource, and an initial revision is created that is a copy of the 544 versionable resource. This initial revision becomes the target of 545 the versioned resource. 547 3.2 Modifying a Versioned Resource 549 A versioned resource must be checked out before it can be modified. 550 Checking out a versioned resource produces a new resource, called a 551 working resource. A working resource is a modifiable copy of the 552 revision, and is identical to an unversioned resource in all 553 respects other than that it is associated with a particular 554 revision of a particular versioned resource. It may be edited by 555 setting its properties or contents any number of times. When the 556 author is satisfied that the working resource is in a state that 557 should be retained in the versioned resource history, the author 558 checks in the working resource to create a new revision of the 559 versioned resource. The revision that was checked out is the 560 predecessor of the new revision. 562 The use of checkout/checkin and working resources to update a 563 versioned resource addresses the lost update problem by ensuring 564 that each author is updating his or her own working resource rather 565 than a shared resource, and by ensuring that the predecessor of the 566 updated resource is reliably tracked. Authors can use 567 checkout/checkin to register intent to modify a versioned resource 568 similar to the way lock /unlock are used in WebDAV level 2, but the 569 underlying semantics are very different. With lock/unlock, work is 570 serialized and avoiding lost updates depends on clients using the 571 lock/unlock protocol. With checkout/checkin, work can be performed 572 in parallel, and the server prevents lost updates by retaining all 573 saved states (revisions) of the resource. 575 A revision may be created as either immutable or mutable. An 576 immutable revision cannot be changed and provides a stable 577 environment for history management, change recovery, merging, and 578 configuration management. A mutable revision is more suitable for 579 situations where versioning is treated more informally, and it is 580 not necessary or desirable to maintain strict version histories, or 581 to guarantee the possibility of backtracking to a previous saved 582 state. If the revision is mutable, the author may request that a 583 subsequent checkin should overwrite the revision that was checked 584 out, instead of creating a new revision. In this case, the 585 previous state captured by that revision is lost. Servers may 586 choose to support only immutable revisions, only mutable revisions, 587 or both. 589 3.3 Naming Revisions: Revision Ids and Labels 591 Revision names are used to distinguish a revision of a versioned 592 resource from other revisions of that versioned resource. A 593 revision name is either a revision id or any number of revision 594 labels. A revision of a versioned resource is given a server 595 assigned revision id when it is created. This revision id acts as a 596 persistent, immutable identifier distinguishing this revision from 597 all others of the same versioned resource. The revision id cannot 598 be changed, assigned to another revision, or reused. 600 A user may assign revision labels to a revision in order to provide 601 a more meaningful name for the revision. A given revision label 602 can be assigned to at most one revision of a given versioned 603 resource, but may be reassigned to any revision of the versioned 604 resource at any time. Revisions of different versioned resources 605 may have the same label. 607 3.4 Parallel Development and Activities 609 In a locking model, when a resource is locked for modifications by 610 one author, all other authors are supposed to respect that lock and 611 not work on a copy of that resource until the lock has been 612 released. To avoid the work serialization inherent in the locking 613 model, a versioning model allows multiple authors in different 614 workspaces to check out the same revision at the same time, work on 615 their respective working resources in parallel, check in their 616 respective working resources as soon as their changes are complete, 617 and then merge the resulting revisions at some later time. 619 Although a simple versioning model works well for isolated changes 620 to independent resources, the required merge process becomes 621 unmanageable when sequences of inter-related changes are performed 622 on sets of related resource. To address this merge problem, 623 resources can be checked out in the context of an activity. An 624 activity captures the set of revisions that form a set of related 625 changes an author is making to one or more versioned resources. 626 Each activity represents a thread of development, where any thread 627 can be isolated from other threads to provide a stable environment 628 for parallel work. In case parallel work on isolated activities 629 results in branches in the underlying versioned resource histories, 630 the activities can be unified through a merge operation. 632 3.5 Revision Selection and Workspaces 634 Resources, working resources, and revisions of versioned resources 635 are all accessed using a URL. When a client accesses a versioned 636 resource, it is necessary to provide additional information to 637 specify which working resource or which revision of the versioned 638 resource should be accessed. Specifying the resource URL and a 639 revision name can access a specific revision of the versioned 640 resource. However, this requires the user to add and remember 641 labels for each revision; it does not provide a way of accessing a 642 consistent set of revisions captured by an activity or contained in 643 a configuration; it does not enable non-versioning aware clients to 644 access revisions; and it does not provide a client with access to a 645 working resource of a versioned resource. 647 To address the restrictions inherent in revision-name based 648 revision selection, the revision selected when a specific revision 649 name is not specified is resolved through a workspace. A workspace 650 is a resource whose primary purpose is to identify working 651 resources. If the workspace contains no working resource for a 652 given versioned resource, it can also be used to select an 653 appropriate revision of the versioned resource. This allows 654 versioned resources and unversioned resources to be accessed 655 consistently by both versioning-aware and versioning-unaware 656 clients. 658 In order to specify revision selection, a workspace contains a 659 revision selection rule. A revision selection rule can specify 660 revision names, activities, configurations, or use operators that 661 combine several of these rule elements. A revision name selects a 662 revision with that name. An activity selects the latest revision 663 that was created in that activity. Configurations select the 664 revision contained in the configuration. The "or" operator contains 665 a sequence of rule elements, and applies them in order until the 666 first match is found. If there is no matching revision, then a 667 resource-not-found status is returned. 669 If a request is made and no workspace is specified, a server 670 determined default workspace is used. This is the workspace used by 671 all versioning-unaware clients. A server MAY allow modifications to 672 the revision selection rule of the default workspace. 674 3.6 Configurations 676 A workspace selects a volatile set of revisions. Changes to 677 selected activities or changes to labels may result in the 678 selection of different revisions. A configuration is a resource 679 that selects a set of immutable revisions. A workspace whose 680 version selection rule contains a configuration will always select 681 the same revisions as long as the configuration is not modified and 682 no checkouts are performed in that workspace. 684 Configurations are convenient for defining a persistent set of 685 revisions that relate to each other in some specific way at some 686 point in time. This can be useful for a variety of purposes such as 687 publishing consistent versions of resources to deploy an 688 application, or for recovering a specific state for legal or 689 maintenance reasons. 691 3.7 Versioned Collections 693 A collection contains a set of named bindings to other resources 694 that are the members of that collection. For a versioned 695 collection, the bindings are to versioned resources, not to 696 particular revisions. To modify the state of a versioned collection 697 (i.e. add or remove a binding), the versioned collection must be 698 checked out, just like any other versioned resource. Requests that 699 modify the state of a collection member, such as checking it out or 700 checking in a new revision, have no effect on the state of the 701 collection. Conversely, requests that modify the state of a 702 versioned collection, such as deleting or adding a binding to 703 resource, have no effect on the state of that resource. In 704 particular, the resource will remain bound in any other revisions 705 of the collection of which it was a member. 707 If a URL identifies a sequence of nested versioned collections, 708 revision selection is performed for each versioned collection in 709 the sequence, to select the versioned collection revision that will 710 be used to map the next segment of the URL to the appropriate 711 versioned resource. 713 4 VERSIONING RESOURCE TYPES AND PROPERTIES 715 This section defines the new resource types and properties 716 introduced by WebDAV versioning. 718 4.1 Property Attributes 720 There are several important attributes of properties that will be 721 defined for every property introduced by this document. 723 4.1.1 Writeable/Readonly Properties 725 A writeable property can be modified by a client, while a readonly 726 property can only be modified by the server. 728 All properties defined in this document are writeable unless 729 explicitly marked as "readonly". 731 4.1.2 Immutable/Mutable Properties 733 An immutable resource is a resource whose value cannot change. An 734 immutable property is a property whose value cannot change when it 735 appears on an immutable resource. A mutable property is a property 736 whose value can change, even when it appears on an immutable 737 resource. 739 All properties defined in this document are immutable unless 740 explicitly marked as "mutable". 742 4.1.3 Property Resources 744 There are various properties whose contents can be represented as 745 an HTTP resource. Doing so allows a client to use the full set of 746 HTTP methods to manipulate the contents of that property, rather 747 than being limited to the functionality provided by PROPFIND and 748 PROPPATCH. This is particularly valuable for a property value that 749 is naturally represented as a collection resource. By default, 750 PROPFIND returns an XML document as the value of a property 751 resource; however, when a DAV:property-resource-URL element is 752 specified in the PROPFIND request body, PROPFIND will return the 753 URL of the property resource. Servers MAY support DAV:property- 754 resource-URL for a property, but MUST support the default XML 755 value. 757 All properties that are property resources are explicitly marked as 758 "resource". If the property resource is a collection, the property 759 is marked as "collection". 761 4.2 Resource Properties 763 WebDAV versioning introduces the following additional properties 764 for a resource: 766 4.2.1 DAV:author (immutable) [Core] 768 This property is used to track the author of a resource. 770 4.2.2 DAV:comment (immutable) [Core] 772 This property is used to track a brief comment about a resource. 774 4.3 Revision Properties 776 WebDAV versioning introduces the following additional properties 777 for a revision: 779 4.3.1 DAV:revision-id (readonly) [Core] 781 The DAV:revision-id is an identifier assigned to a revision by the 782 server. Whenever a revision is created or modified by a CHECKIN, it 783 must be assigned a new DAV:revision-id. A revision cannot be given 784 a DAV:revision-id that has been given to any other revision of that 785 versioned resource, even a revision that has been deleted. 787 4.3.2 DAV:predecessor (readonly, resource) [Core] 789 The DAV:predecessor of a revision is the revision that was checked 790 out to produce a working resource that was checked in to produce 791 this revision. The XML document for DAV:predecessor contains the 792 revision-id of the DAV:predecessor. 794 4.3.3 DAV:successors (readonly, mutable, collection) [Core] 796 The DAV:successors collection of a revision contains the revisions 797 whose DAV:predecessor is that revision. The XML document for 798 DAV:successors contains a list of the revision-id's of the 799 DAV:successors. 801 4.3.4 DAV:single-checkout (mutable) [Core] 803 When the DAV:single-checkout property of a revision is set, only 804 one working resource can be checked out from that revision at any 805 time. 807 4.3.5 DAV:auto-version (mutable) [Core] 809 When the DAV:auto-version property of a revision is set, a PUT 810 request (or any request that modifies an immutable aspect of the 811 revision) to this revision is automatically preceded by a CHECKOUT 812 into the default workspace and followed by a CHECKIN. This allows 813 a versioning-unaware client to modify a version-controlled 814 resource. The DAV:auto-version value can take the same values as 815 the DAV:checkin-policy of a working resource, and the DAV:checkin- 816 policy of the automatically created working resource is set to be 817 the DAV:auto-version policy of the revision. 819 4.3.6 DAV:revision-labels (mutable) [Core] 821 This property is used to identify labels that are associated with a 822 specific revision. 824 4.3.7 DAV:checkin-date (readonly) [Core] 826 This property contains the date when the revision was checked in. 827 This property is automatically assigned and is formatted using 828 ISO8061. 830 4.3.8 DAV:working-resources (readonly, collection) [Core] 832 This property is a collection of the workspaces that contain 833 working resources whose DAV:predecessor is this revision. The XML 834 document for DAV:working-resources contains a description of these 835 working resources. 837 4.3.9 DAV:history-uuid (readonly) [Core] 839 The DAV:history-uuid of a revision is the DAV:uuid of the history 840 resource whose DAV:revisions collection contains this revision. 842 4.3.10 DAV:history (readonly, resource) [Core] 844 The DAV:history of a revision is the history resource whose 845 DAV:revisions collection contains this revision. The XML document 846 for DAV:history contains a description of revisions that form the 847 line-of-descent to this revision. 849 4.3.11 DAV:merge-predecessors (mutable, collection) [Merging] 851 The DAV:merge-predecessors collection of a revision contains the 852 revisions whose contents were explicitly merged by the client into 853 that revision. The client is free to add or delete members to this 854 collection to more accurately reflect the contents of that 855 revision. The XML document for DAV:merge-predecessors contains the 856 revision id's of the DAV:merge-predecessors. 858 4.3.12 DAV:merge-successors (mutable, collection, readonly) [Merging] 860 The DAV:merge-successors collection of a revision contains a 861 binding to each revision whose DAV:merge-predecessors collection 862 contains a binding to that revision. The XML document for 863 DAV:merge-successors contains the revision id's of the DAV:merge- 864 successors. 866 4.4 Working Resource Properties 868 WebDAV versioning introduces the following additional properties 869 for a working resource: 871 4.4.1 DAV:workspace (readonly, resource) [Core] 873 The DAV:workspace of a working resource is the workspace that 874 contains this working resource. The XML document for DAV:workspace 875 contains the URL of this workspace. 877 4.4.2 DAV:predecessor (read-only, resource) [Core] 879 This property contains the revision that was checked out to create 880 this working resource. The XML document for DAV:predecessor 881 contains the revision id of DAV:predecessor. 883 4.4.3 DAV:checkin-policy [Core] 885 The DAV:checkin-policy property of a working resource indicates how 886 this working resource should be checked in. The following are 887 defined values for DAV:checkin-policy. The default value is 888 DAV:immutable. 890 DAV:identical-abort - the CHECKIN should fail if the working 891 resource is identical to its DAV:predecessor. 893 DAV:identical-uncheckout - an UNCHECKOUT should be applied instead 894 of CHECKIN if the working resource is identical to its 895 DAV:predecessor. 897 DAV:overwrite - the working resource should be copied into its 898 DAV:predecessor instead of creating a new revision. 900 DAV:mutable - a new revision is created that can be overwritten by 901 a subsequent DAV:overwrite CHECKIN. 903 DAV:immutable - a new revision is created that cannot be 904 overwritten by a subsequent DAV:overwrite CHECKIN. 906 DAV:keep-checked-out - create a new revision but does not delete 907 the working resource. The DAV:predecessor of the working resource 908 is changed to be the new revision. 910 DAV:baseline - instead of creating a new revision of the versioned 911 collection, create a new baseline for it (the CHECKIN fails unless 912 it is applied to a versioned collection with a DAV:baselines 913 property). 915 4.4.4 DAV:merge-predecessors (collection) [Merging] 917 The DAV:merge-predecessors collection of a working resource 918 contains the revisions whose contents were explicitly merged by the 919 client into that working resource. The client adds and deletes 920 members of this collection to reflect the set of revisions that 921 were merged by the client into the working resource. The name of a 922 DAV:merge-predecessors binding is the DAV:revision-id of that 923 revision. The XML document for DAV:merge-predecessors contains the 924 revision id's of the DAV:merge-predecessors. 926 4.4.5 DAV:activity (readonly, resource) [Activity] 928 The DAV:activity property of a working resource is the DAV:activity 929 of the workspace when the working resource was checked out. The 930 XML document for DAV:activity is the URL for the activity. 932 4.5 Workspace Properties 934 WebDAV versioning introduces the following additional properties 935 for a workspace: 937 4.5.1 DAV:working-resources (readonly, collection) [Core] 939 The DAV:working-resources collection contains the versioned 940 resources that are checked out into this workspace. The XML 941 document for DAV:working-resources contains a description of these 942 working resources. 944 4.5.2 DAV:revision-selection-rule [Core] 946 The DAV:revision-selection-rule of a workspace can contain an XML 947 document that describes how revision selection will be performed in 948 that workspace. The working resources checked out into a workspace 949 take priority over revisions selected by the revision selection 950 rule, thus target of a versioned resource in a workspace is the 951 working resource in that workspace for that versioned resource, 952 else the revision selected by the workspace revision selection 953 rule. To ensure that working resources continue to be visible in a 954 workspace after they are checked in, the DAV:label or DAV:activity 955 of a workspace is usually the first element of the DAV:revision- 956 selection-rule. If the DAV:revision-selection-rule is not set or is 957 empty, the revision selection rule will select no revision for any 958 versioned resource. 960 Standard revision selection rule elements are defined in this 961 document, but additional revision selection rule elements may be 962 supported by a WebDAV server. 964 4.5.3 DAV:label [Core] 966 The DAV:label property of a workspace can contain a revision label. 967 When a working resource in a workspace is checked in, it will be 968 given this label. 970 4.5.4 DAV:activity [Activity] 972 The DAV:activity property of a workspace is the activity that is 973 currently being performed in that workspace. A new working 974 resource in a workspace will have its DAV:activity property set to 975 this activity. The XML document for DAV:activity contains the URL 976 of DAV:activity. 978 4.6 Activity Properties 980 WebDAV versioning introduces the following additional properties 981 for an activity: 983 4.6.1 DAV:revisions (readonly, collection) [Activity] 985 The DAV:revisions collection of an activity contains all revisions 986 whose DAV:activity property contains this activity. The XML 987 document for DAV:revisions contains the URL's of these revisions. 989 4.6.2 DAV:required-activities (collection) [Activity] 991 The DAV:required-activities collection of an activity contains the 992 other activities that form a part of the logical change being 993 captured by the activity. The DAV:needed-activities of an activity 994 contribute to the revision selection behavior of that activity when 995 it is used in a revision selection rule. The purpose of this 996 property is to identify other activities that are a prerequisite to 997 this activity. The XML document for DAV:required-activities 998 contains the URL's of these activities. 1000 4.6.3 DAV:workspace (resource) [Activty] 1002 The DAV:workspace property of an activity contains the workspace 1003 that currently has that activity as its DAV:current activity. This 1004 implies that at most one workspace can be working in a given 1005 activity at a time. If any working resource of a workspace is 1006 checked out into a given activity, the DAV:workspace of that 1007 activity can only be that workspace. The XML document for 1008 DAV:workspace contains the URL of the workspace. 1010 4.7 Configuration Properties 1012 WebDAV versioning introduces the following properties for a 1013 configuration: 1015 4.7.1 DAV:roots (immutable, collection) [Configuration] 1017 The DAV:roots collection of a configuration contains the versioned 1018 resources that are not named by versioned collection revisions in 1019 that configuration. The XML document for DAV:roots contains the 1020 URL's of these versioned resources. 1022 4.8 Versioned Collection Properties 1024 WebDAV versioning introduces the following additional properties 1025 for a versioned collection: 1027 4.8.1 DAV:baselines (resource) [Baseline] 1029 The DAV:baselines of a versioned collection is a versioned 1030 configuration whose DAV:roots contains only that versioned 1031 collection. A revision of the DAV:baselines of a versioned 1032 collection effectively provides a "deep-revision" of that versioned 1033 collection. The XML document for DAV:baselines contains the URL of 1034 the versioned configuration. 1036 4.9 History Resource Properties 1038 WebDAV versioning introduces the following additional properties 1039 for a history resource: 1041 4.9.1 DAV:uuid (readonly) [Core] 1043 The DAV:uuid is an identifier assigned to a history resource by the 1044 server. A history resource cannot be given a DAV:uuid that has been 1045 given to any other history resource, even a history resource that 1046 has been deleted. 1048 4.9.2 DAV:revisions (readonly, collection) [Core] 1050 The DAV:revisions collection of a history resource contains all 1051 revisions of that history resource, where the name of a revision in 1052 the DAV:revisions collection is its DAV:revision-id. If a revision 1053 id contains a URL reserved character, that character is escaped in 1054 the DAV:revisions name. The XML document for DAV:revisions 1055 contains the URL's of the revisions. 1057 4.9.3 DAV:revision-labels (collection) [Core] 1059 The DAV:revision-labels collection of a history resource contains a 1060 binding for each label assigned to any revision of that history 1061 resource, where the binding name is that label (reserved URL 1062 characters are escaped) and the binding is to the revision selected 1063 by that label. The client can label and unlabel revisions by 1064 adding and deleting members of the DAV:revision-labels collection. 1066 The XML document for DAV:revision-labels contains the URL's of the 1067 members of the DAV:revision-labels collection. 1069 5 VERSIONING METHODS 1071 5.1 Existing Methods 1073 This section describes the extensions to the existing WebDAV 1074 methods. Under versioning, the methods inherit all of the WebDAV 1075 functionality with the following extensions. 1077 5.1.1 GET 1079 When GET is applied to a versioned resource, it returns the body of 1080 the target of that versioned resource. The result of GET on a 1081 workspace, activity, or history resource is undefined. 1083 5.1.2 BIND 1085 When BIND creates a binding in a working resource for a versioned 1086 collection, it MUST fail if the request URL of the BIND is not a 1087 versioned resource. 1089 5.1.3 PUT 1091 When PUT is applied to a versioned resource whose target is a 1092 working resource, the PUT is applied to that working resource. 1093 When PUT is applied to a versioned resource whose target is a 1094 revision, the PUT MUST fail except in the following two cases. If 1095 the revision has a DAV:auto-version property and no Target-Selector 1096 header has been specified, the revision is checked out into the 1097 default workspace, the PUT is applied to the resulting working 1098 resource, and the working resource is checked in. If the revision 1099 is a revision of a baselined collection and the value of 1100 DAV:checkin-policy is DAV:baseline, a new revision of the 1101 DAV:baselines configuration is created by the CHECKIN. 1103 When PUT is applied directly to a revision (i.e. not indirectly 1104 via a versioned resource), it MUST fail. 1106 When PUT is applied to a null resource that is an internal member 1107 of a versioned collection whose target is a working resource, a new 1108 versioned resource is created at the request URL of the PUT. When 1109 the target is a versioned collection revision, the PUT request 1110 fails unless the revision has a DAV:auto-version property and no 1111 Target-Selector header has been specified. If DAV:auto-version is 1112 set, the versioned collection revision is checked out into the 1113 default workspace, a new versioned resource is created as a member 1114 of the working collection, and the working collection is checked 1115 in. 1117 When a PUT is applied to a workspace, activity or history resource, 1118 it fails. 1120 5.1.4 PROPFIND 1122 If a DAV:property-resource-URL is specified under a DAV:prop 1123 element in a PROPFIND request body, the property resource URL of 1124 that property will be returned in the PROPFIND response instead of 1125 the default XML document for that property resource. If a 1126 DAV:property-resource-URL is specified directly under the 1127 DAV:propfind element, the property resource URL will be returned 1128 for all of the property resources in the PROPFIND response. 1130 5.1.5 PROPPATCH 1132 When PROPPATCH is applied to a versioned resource, its behavior is 1133 similar to that of PUT. In particular, when PROPPATCH is applied to 1134 an immutable property of a revision, it MUST fail unless the 1135 revision has a DAV:auto-version property. 1137 5.1.6 DELETE 1139 When DELETE is applied to a versioned resource whose target is a 1140 revision, the versioned resource is deleted from the collection 1141 that contains it, but the revision is unaffected. When DELETE is 1142 applied to a workspace, the workspace and all working resources of 1143 that workspace are deleted. 1145 When DELETE is applied to a member of the DAV:revisions collection 1146 of a history resource, it fails unless the All-Bindings header is 1147 specified. When DELETE is applied to a history resource, the 1148 history resource and all members of the DAV:revisions collection of 1149 that history resource are deleted. 1151 5.1.7 COPY 1153 When COPY is applied to a versioned resource, it is applied to the 1154 target of the versioned resource. That is, only the selected 1155 revision is copied, not the full version history. 1157 When a COPY request is applied to a workspace, activity, or history 1158 resource, it fails. 1160 5.1.8 MOVE 1162 When MOVE is applied to a versioned resource, the MOVE request MUST 1163 fail unless a binding to that versioned resource can be created at 1164 the Destination of the MOVE. 1166 When a MOVE request is applied to an activity or a history 1167 resource, it fails. 1169 Any request to MOVE a specific revision, and not the versioned 1170 resource, MUST fail. 1172 5.1.9 LOCK 1174 A write lock on a versioned resource is applied to the target of 1175 that versioned resource. 1177 A write lock on a revision prevents unauthorized modifications to 1178 the properties of that revision. 1180 A write lock on a working resource prevents unauthorized changes to 1181 the body or properties of that working resource. 1183 A write lock on an activity prevents unauthorized modifications to 1184 the properties of that activity. 1186 A write lock on a history resource places a write lock on all 1187 revisions of that history resource. 1189 A write lock on a workspace prevents unauthorized modifications to 1190 the properties of that workspace. 1192 5.1.10 OPTIONS 1194 The OPTIONS method allows the client to discover the level of 1195 versioning support provided by a server. 1197 The following defines the BNF for the Versioning header: 1199 Versioning := "Versioning" ":" Ver-type-list 1200 Ver-type-list := Ver-type | (Ver-type-list "," Ver-type) 1201 Ver-type := "Core" 1202 | "Activity" 1203 | "Merging" 1204 | "Configuration" 1205 | "Versioned-Collection" 1206 | "Baseline" 1208 5.2 New Methods 1210 WebDAV versioning introduces two new methods, MKRESOURCE and 1211 REPORT, that are not specific to versioning but are needed to 1212 support the versioning extensions. 1214 5.2.1 MKRESOURCE 1216 The MKRESOURCE method requests the simultaneous creation of a 1217 resource, identified by the Request URI, and initialization of its 1218 properties. Creation of the resource and initialization of its 1219 properties MUST both occur, or neither occurs. The request message 1220 body of the MKRESOURCE method is the same as for the PROPPATCH 1221 method, i.e. it MUST contain the DAV:propertyupdate XML element, 1222 defined in section 12.13 of [RFC2518]. The property update 1223 directives in the request message body provide the initial values 1224 of the properties of the new resource. The type of the created 1225 resource is specified by the DAV:resourcetype property, if present. 1226 If the DAV:resourcetype property is not specified, the created 1227 resource is an ordinary (i.e. untyped) resource. Like PROPPATCH, 1228 instruction processing MUST occur in the order instructions are 1229 received (i.e. from top to bottom). Instructions MUST all be 1230 executed, or none executed. If MKRESOURCE is applied to an 1231 existing resource, that resource is deleted prior to MKRESOURCE 1232 processing. The behavior of MKRESOURCE on an existing resource can 1233 be explicitly controlled through use of the Overwrite header. 1235 MKRESOURCE can be used to create a new activity in a repository 1236 DAV:activities collection. When MKRESOURCE is used to create a 1237 repository from an existing versionable collection, every member of 1238 that versionable collection is also placed under version control as 1239 a history resource in that repository. 1241 Status Codes: 1243 201 (Created) - The new resource has successfully been created. 1245 207 (Multi-Status) - If any error was encountered in the creation 1246 of the resource, this response is generated. Status codes defined 1247 for use with PROPPATCH (defined in section 8.2.1 of [RFC2518]) 1248 SHOULD be used to represent error cases in setting the value of 1249 properties. 1251 TBD - Explain effect on existing resource types 1253 TBD - Give request/response example 1255 5.2.2 REPORT 1257 The REPORT request is an extensible mechanism for obtaining 1258 information about a resource. This differs from OPTIONS because 1259 the information is not static. That is, it is typically a report 1260 that requires server processing in order to generate. 1262 The REPORT method takes an XML body document that specifies the 1263 type of report. If no report is requested, the method returns a 1264 list of available reports. 1266 TBD - More details on error codes 1268 TBD - Give request/response example 1270 5.3 New Versioning Methods 1272 WebDAV versioning introduces three new methods to support the 1273 checkout/checkin versioning model. 1275 5.3.1 CHECKOUT 1277 A CHECKOUT request can only be applied to a versioned resource. 1278 When a CHECKOUT request is applied to a versioned resource whose 1279 target is a revision, a new working resource is created that is a 1280 copy of the revision, and the DAV:predecessor of the working 1281 resource is set to be that revision. If the DAV:predecessor has a 1282 DAV:single-checkout property and is already checked out into a 1283 workspace, the CHECKOUT request fails. The DAV:workspace of the 1284 working resource is set to be the workspace specified in the 1285 Target-Selector header. If the Target-Selector is not a workspace 1286 or if there is no Target-Selector header, the DAV:workspace for 1287 that working resource is allocated by the server. The body of the 1288 CHECKOUT request can be used to initialize the DAV:checkin-policy 1289 of the working resource. 1291 When a CHECKOUT request is applied to a versioned resource whose 1292 target is a working resource, the CHECKOUT request MUST fail. 1294 On CHECKOUT, the DAV:activity of the new working resource is set to 1295 be the DAV:activity of the current workspace. If DAV:activity is 1296 not set, a server with activity support automatically assigns an 1297 activity to the new working resource. The CHECKOUT request fails 1298 if neither DAV:activity nor DAV:label is set. 1300 TBD - Failures must include "policy not supported" 1302 TBD - More details on error codes 1304 TBD - Give request/response example 1306 5.3.2 CHECKIN 1308 When a CHECKIN request is applied to a versioned resource whose 1309 target is a working resource, a copy of the working resource is 1310 made a new revision of that versioned resource and the working 1311 resource is deleted. The new revision is added to the 1312 DAV:successors collection of the DAV:predecessor of the new 1313 revision, and the workspace of the working resource is deleted from 1314 the DAV:working-resources collection of the DAV:predecessor. 1316 The body of a CHECKIN request can be used to override the current 1317 DAV:checkin-policy values of the working resource. The effect of 1318 DAV:checkin-policy on a CHECKIN request is described in the 1319 definition of the DAV:checkin-policy property. 1321 When the CHECKIN method is applied to a resource that is 1322 versionable, but not currently versioned, the resource is put under 1323 version control. If a versionable collection is put under version 1324 control, all members of that collection are put under version 1325 control as well. 1327 TBD - More details on error codes 1329 TBD - Explain effect on existing resource types 1331 TBD - Give request/response example 1333 5.3.3 UNCHECKOUT 1335 When an UNCHECKOUT request is applied to a versioned resource whose 1336 target is a working resource, the DAV:workspace of that working 1337 resource is deleted from the DAV:working-resources collection of 1338 the DAV:revision of the working resource, and the working resource 1339 is deleted. This effectively cancels the CHECKOUT request that 1340 produced the working resource. 1342 TBD - More details on error codes 1344 TBD - Explain effect on existing resource types 1346 TBD - Give request/response example 1348 5.4 New Versioning Headers 1350 5.4.1 Target-Selector 1352 The Target-Selector header contains a workspace URL or a revision 1353 name. The Target-Selector header is used to specify which working 1354 resource or revision of a versioned resource should be its target. 1355 If a Target-Selector header is omitted in a request on a versioned 1356 resource, the default workspace is implicitly used as the Target- 1357 Selector. 1359 6 THE DAV VERSIONING XML ELEMENTS 1361 6.1 Revision Selection Rule Elements 1363 A revision selection rule document is the value of the 1364 DAV:revision-selection-rule property of a workspace. 1365 Semantically, a revision selection rule (or RSR) element can be 1366 applied to an arbitrary versioned resource, and will either select 1367 a particular revision of that versioned resource or select no 1368 revision of that versioned resource. If it selects a particular 1369 revision, it may also detect a conflict (e.g. when there were 1370 multiple candidates for selection). A document describing the 1371 conflicts can be obtained through a conflict REPORT request. 1373 6.1.1 DAV:rsr-configuration 1375 A DAV:rsr-configuration element contains the URL of a 1376 configuration. If the configuration contains a revision of the 1377 versioned resource, that revision is selected by the DAV:rsr- 1378 configuration element; otherwise, no revision is selected. A 1379 DAV:rsr-configuration element never generates a conflict. 1381 6.1.2 DAV:rsr-activity-latest 1383 A DAV:rsr-activity-latest element contains the URL of an activity. 1384 If the DAV:revisions collection of the activity contains one or 1385 more revisions of the versioned resource, then the latest revision 1386 in that activity is selected. The semantics of activities ensures 1387 that there always is a unique latest revision for an activity. If 1388 the activity contains no revisions of a versioned resource, the 1389 DAV:rsr-activity-latest element selects no revisions of that 1390 versioned resource. 1392 If the DAV:needed-activities collection of an activity is non- 1393 empty, then the DAV:rsr-activity element acts like a DAV:rsr-merge 1394 element that contains that activity and each of the DAV:needed- 1395 activities. A DAV:rsr-activity-latest element can generate 1396 conflicts only if the DAV:needed-activities collection is non- 1397 empty. 1399 6.1.3 DAV:rsr-label 1401 A DAV:rsr-label element contains a label. If a revision of the 1402 versioned resource has that label, that revision is selected by the 1403 DAV:rsr-label element; otherwise, no revision is selected. A 1404 DAV:rsr-label element never generates a conflict. 1406 6.1.4 DAV:rsr-revision-id 1408 A DAV:rsr-revision-id element contains a revision id. If a 1409 revision of the versioned resource has that revision id, that 1410 revision is selected by the DAV:rsr-revision-id element; otherwise, 1411 no revision is selected. A DAV:rsr-revision-id element never 1412 generates a conflict. 1414 6.1.5 DAV:rsr-latest 1416 A DAV:rsr-latest element selects the revision of that versioned 1417 resource with the latest DAV:creationdate. A DAV:rsr-latest 1418 element never generates a conflict. 1420 6.1.6 DAV:rsr-or 1422 A DAV:rsr-or element contains a sequence of RSR elements. The 1423 behavior of a DAV:rsr-or element is identical to the behavior of 1424 the first element in this sequence that selects a revision of the 1425 versioned resource. If no element selects a revision, then the 1426 DAV:rsr-or element selects no revision of that versioned resource. 1428 6.1.7 DAV:rsr-merge 1430 A DAV:rsr-merge element contains a sequence of RSR elements. If 1431 one of the elements in this sequence selects a revision that is the 1432 descendent of all of the other revisions selected by elements in 1433 this sequence, then that revision is selected by the DAV:rsr-merge 1434 element. If no selected revision is a descendent of all the other 1435 selected revisions, then the result of the DAV:rsr-merge is a 1436 "conflict". A conflicts REPORT request can be used to identify the 1437 conflicts. 1439 6.2 Report Elements 1441 6.2.1 Conflicts Report 1443 A conflicts report describes the conflicts in a specified workspace 1444 for a specified resource or for all the members of a specified 1445 versioned collection. 1447 6.2.1.1 DAV:conflicts-report-request 1449 A DAV:conflicts-report-request contains the URL of a workspace and 1450 the URL of a versioned resource. 1452 6.2.1.2 DAV:conflicts-report-response 1454 A DAV:conflicts-report-response contains a DAV:conflict element for 1455 each versioned resource for which the revision selection rule 1456 specified in the DAV:conflicts-report-request produced a conflict. 1457 The DAV:conflict element identifies the versioned resource which 1458 generated a conflict, as well as information about how to resolve 1459 the conflict (such as the revisions that would need to be merged). 1461 6.2.1.3 DAV:conflict 1463 The DAV:conflict element contains the URL of a versioned resource 1464 for which the revision selection rule generated a conflict, a 1465 DAV:common-ancestor for the conflict, and two or more 1466 DAV:contributor elements for the conflict. 1468 6.2.1.4 DAV:common-ancestor 1470 The DAV:common-ancestor element identifies a revision that is a 1471 common ancestor of all the DAV:contributor elements for a 1472 particular conflict. 1474 6.2.1.5 DAV:contributor 1476 The DAV:contributor element identifies a revision that is selected 1477 by an element of the revision selection rule but that is not an 1478 ancestor of any of the other revisions selected by the revision 1479 selection rule. 1481 6.2.2 Compare Report 1483 6.2.2.1 DAV:compare-report-request 1485 A DAV:compare-report-request contains the URL's of two resources of 1486 the same type. 1488 6.2.2.2 DAV:compare-report-response 1490 A DAV:compare-report-response identifies the differences between 1491 two resources of the same type. These differences are indicated by 1492 appropriate DAV:added, DAV:deleted, and DAV:changed elements. 1494 In particular, if a DAV:compare-report-request is applied to two 1495 configuration revisions. The DAV:compare-report-response contains 1496 the revisions, needed-configurations, and activities that are 1497 selected by one configuration revision but not the other. 1499 6.2.2.3 DAV:added 1501 A DAV:added element identifies something that appears in the second 1502 resource but not in the first. 1504 6.2.2.4 DAV:deleted 1506 A DAV:deleted element identifies something that appears in the 1507 first resource but not in the second. 1509 6.2.2.5 DAV:changed 1511 A DAV:changed element identifies something that is in both 1512 resources but that is in some way different in the two resources. 1513 For example, when two configurations are being compared, a 1514 DAV:changed element can identify a versioned resource, a versioned 1515 collection, or an activity. A versioned resource has changed if 1516 the configurations select different revisions of that versioned 1517 resource. A versioned collection has changed if the configurations 1518 select different revisions or different baselines of that versioned 1519 collection. An activity has changed if both configurations 1520 contain that activity but the DAV:revisions or DAV:needed- 1521 activities of that activity were different when those 1522 configurations were created. 1524 7 INTERNATIONALIZATION CONSIDERATIONS 1526 To be supplied. 1528 NOTE: If a revision label contains a URL reserved character, that 1529 character is escaped in the DAV:revision-labels name. 1531 8 SECURITY CONSIDERATIONS 1533 To be supplied. 1535 9 SCALABILITY 1537 To be supplied. 1539 10 AUTHENTICATION 1541 Authentication mechanisms defined in WebDAV will also apply to DAV 1542 Versioning. 1544 11 IANA CONSIDERATIONS 1546 This document uses the namespace defined by [RFC2518] for XML 1547 elements. All other IANA considerations mentioned in [RFC2518] 1548 also applicable to DAV Versioning. 1550 12 INTELLECTUAL PROPERTY 1552 The following notice is copied from RFC 2026 [RFC2026], section 1553 10.4, and describes the position of the IETF concerning 1554 intellectual property claims made against this document. 1556 The IETF takes no position regarding the validity or scope of any 1557 intellectual property or other rights that might be claimed to 1558 pertain to the implementation or use other technology described in 1559 this document or the extent to which any license under such rights 1560 might or might not be available; neither does it represent that it 1561 has made any effort to identify any such rights. Information on 1562 the IETF's procedures with respect to rights in standards-track and 1563 standards-related documentation can be found in BCP-11. Copies of 1564 claims of rights made available for publication and any assurances 1565 of licenses to be made available, or the result of an attempt made 1566 to obtain a general license or permission for the use of such 1567 proprietary rights by implementers or users of this specification 1568 can be obtained from the IETF Secretariat. 1570 The IETF invites any interested party to bring to its attention any 1571 copyrights, patents or patent applications, or other proprietary 1572 rights which may cover technology that may be required to practice 1573 this standard. Please address the information to the IETF 1574 Executive Director. 1576 13 ACKNOWLEDGEMENTS 1578 This protocol is the collaborative product of the Delta-V design 1579 team: Jim Amsden (IBM, DeltaV Chair), Geoffrey Clemm (Rational), 1580 Bruce Cragun (Novell), David Durand (INSO), Chris Kaler 1581 (Microsoft), Jeff McAffer (OTI), Bradley Sergeant (Merant), and Jim 1582 Whitehead (UCI). We would like to acknowledge the foundation laid 1583 for us by the authors of the WebDAV and HTTP protocols upon which 1584 this protocol is layered, and the invaluable feedback from the 1585 WebDAV and DeltaV working groups. 1587 14 INDEX 1589 To be supplied. 1591 15 REFERENCES 1593 [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. 1594 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, 1595 U.C. Irvine, DEC, MIT/LCS, January 1997. 1597 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 1598 Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1599 1997. 1601 [RFC2518] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D. 1602 Jenson, "HTTP Extensions for Distributed Authoring - WEBDAV", RFC 1603 2518, Microsoft, UCIrvine, Netscape, Novell, February. 1999. 1605 [AdvCol] http://www.ietf.org/internet-drafts/draft-ietf-webdav- 1606 collection-protocol-03.txt 1608 [VerGoal] http://www.ietf.org/internet-drafts/draft-ietf-webdav- 1609 version-goals-02.txt 1611 16 AUTHORS� ADDRESSES 1613 Geoffrey Clemm 1614 Rational Software 1615 20 Maguire Road 1616 Lexington MA 02421-3104 1617 Email: geoffrey.clemm@rational.com 1619 Christopher Kaler 1620 Microsoft 1621 One Microsoft Way 1622 Redmond WA 9085-6933 1623 Email: ckaler@microsoft.com 1625 17 OPEN ISSUES 1627 The following list identifies key open issues against this 1628 document: 1630 @ TODO: Add the appropriate DAV:resourcetype properties to 1631 workspace, history resource, activity, and configuration. 1633 @ TODO: Flush out details on methods: e.g., request/response 1634 examples needed. 1636 @ TODO: DTDs and semantics of properties 1638 @ TODO: Lots of details 1640 @ ISSUE: How are policies discovered? 1642 @ ISSUE: Does Versioning have to be a header, or can it be the body 1643 of the OPTIONS response? 1645 @ ISSUE: Couldn't MKRESOURCE be handled just by allowing PROPPATCH 1646 to be applied to a null resource?