idnits 2.17.1 draft-brown-versioning-link-relations-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 22, 2010) is 5180 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Brown 3 Internet-Draft G. Clemm 4 Intended status: Informational IBM 5 Expires: July 26, 2010 J. Reschke, Ed. 6 greenbytes 7 January 22, 2010 9 Link Relation Types for Simple Version Navigation between Web Resources 10 draft-brown-versioning-link-relations-07 12 Abstract 14 This specification defines a set of link relation types that may be 15 used on Web resources for navigation between a resource and and other 16 resources related to version control, such as past versions and 17 working copies. 19 Editorial Note (To be removed by RFC Editor before publication) 21 Please send comments to the Atom Syntax mailing list 22 (). 24 Note that although discussion takes place on the Atompub working 25 group's mailing list, this is not a working group document. 27 XML versions, latest edits and the issues list for this document are 28 available from . 31 Status of this Memo 33 This Internet-Draft is submitted to IETF in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF), its areas, and its working groups. Note that 38 other groups may also distribute working documents as Internet- 39 Drafts. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 The list of current Internet-Drafts can be accessed at 47 http://www.ietf.org/ietf/1id-abstracts.txt. 49 The list of Internet-Draft Shadow Directories can be accessed at 50 http://www.ietf.org/shadow.html. 52 This Internet-Draft will expire on July 26, 2010. 54 Copyright Notice 56 Copyright (c) 2010 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (http://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 72 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 73 3. Link Relations . . . . . . . . . . . . . . . . . . . . . . . . 5 74 3.1. version-history . . . . . . . . . . . . . . . . . . . . . 5 75 3.2. latest-version . . . . . . . . . . . . . . . . . . . . . . 5 76 3.3. working-copy . . . . . . . . . . . . . . . . . . . . . . . 5 77 3.4. working-copy-of . . . . . . . . . . . . . . . . . . . . . 5 78 3.5. predecessor-version . . . . . . . . . . . . . . . . . . . 6 79 3.6. successor-version . . . . . . . . . . . . . . . . . . . . 6 80 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 81 4.1. 'version-history' Link Relation Registration . . . . . . . 6 82 4.2. 'latest-version' Link Relation Registration . . . . . . . 6 83 4.3. 'working-copy' Link Relation Registration . . . . . . . . 7 84 4.4. 'working-copy-of' Link Relation Registration . . . . . . . 7 85 4.5. 'predecessor-version' Link Relation Registration . . . . . 7 86 4.6. 'successor-version' Link Relation Registration . . . . . . 7 87 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 88 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8 89 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 90 7.1. Normative References . . . . . . . . . . . . . . . . . . . 8 91 7.2. Informative References . . . . . . . . . . . . . . . . . . 8 92 Appendix A. Relationship to Java Content Repository (JCR) and 93 WebDAV . . . . . . . . . . . . . . . . . . . . . . . 9 94 A.1. Example: Use of Link Relations in HTTP Link Header . . . . 10 95 Appendix B. Change Log (to be removed by RFC Editor before 96 publication) . . . . . . . . . . . . . . . . . . . . 12 97 B.1. Since draft-brown-link-relations-00 . . . . . . . . . . . 12 98 B.2. Since draft-brown-link-relations-01 . . . . . . . . . . . 12 99 B.3. Since draft-brown-link-relations-02 . . . . . . . . . . . 12 100 B.4. Since draft-brown-link-relations-03 . . . . . . . . . . . 12 101 B.5. Since draft-brown-link-relations-04 . . . . . . . . . . . 12 102 B.6. Since draft-brown-link-relations-05 . . . . . . . . . . . 12 103 B.7. Since draft-brown-link-relations-06 . . . . . . . . . . . 12 104 Appendix C. Resolved issues (to be removed by RFC Editor 105 before publication) . . . . . . . . . . . . . . . . . 12 106 C.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 107 C.2. terseness . . . . . . . . . . . . . . . . . . . . . . . . 13 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 110 1. Introduction 112 This specification defines a set ot link relation types that may be 113 used on Web resources that exist in a system that supports versioning 114 to navigate among the different resources available, such as past 115 versions and working copies. 117 These link relations are used in the AtomPub ([RFC5023]) bindings of 118 the "Content Management Interoperability Services" (CMIS). See 119 Section 3.4.3.1 of [CMIS] for further information. 121 2. Terminology 123 Versioned Resource 125 When a resource is put under version control, it becomes a 126 "versioned resource". Many servers protect versioned resources 127 from modifications by considering them "checked in", and by 128 requiring a "checkout" operation before modification, and a 129 "checkin" operation to get back to the "checked-in" state. Other 130 servers allow modification, in which case the checkout/checkin 131 operation may happen implicitly. 133 Version History 135 A "version history" resource is a resource that contains all the 136 versions of a particular versioned resource. 138 Predecessor, Successor 140 When a versioned resource is checked out and then subsequently 141 checked in, the version that was checked out becomes a 142 "predecessor" of the version created by the checkin. A client can 143 specify multiple predecessors for a new version if the new version 144 is logically a merge of those predecessors. The inverse of the 145 predecessor relation is the "successor" relation. Therefore, if X 146 is a predecessor of Y, then Y is a successor of X. 148 Working Copy 150 A "working copy" is a resource at a server-defined URL that can be 151 used to create a new version of a versioned resource. 153 Checkout 155 A "checkout" is an operation on a versioned resource that creates 156 a working copy, or changes the versioned resource to be a working- 157 copy as well ("in-place versioning"). 159 Checkin 161 A "checkin" is an operation on a working copy that creates a new 162 version of its corresponding versioned resource. 164 Note: the operations for putting a resource under version control, 165 and for checking in and checking out depend on the protocol in use 166 and are beyond the scope of this document; see [CMIS], [RFC3253] 167 and [JSR-283] for examples. 169 3. Link Relations 171 The following link relations are defined: 173 3.1. version-history 175 When included on a versioned resource, this link points to a resource 176 containing the version history for this resource. 178 3.2. latest-version 180 When included on a versioned resource, this link points to a resource 181 containing the latest (e.g., current) version. 183 The latest version is defined by the system. For linear versioning 184 systems, this is probably the latest version by timestamp. For 185 systems that support branching, there will be multiple latest 186 versions, one for each branch in the version history. 188 Some systems may allow multiple of these link relations. 190 3.3. working-copy 192 When included on a versioned resource, this link points to a working 193 copy for this resource. 195 Some systems may allow multiple of these link relations. 197 3.4. working-copy-of 199 When included on a working copy, this link points to the versioned 200 resource from which this working copy was obtained. 202 3.5. predecessor-version 204 When included on a versioned resource, this link points to a resource 205 containing the predecessor version in the version history. 207 Some systems may allow multiple of these link relations in the case 208 of a multiple branches merging. 210 3.6. successor-version 212 When included on a versioned resource, this link points to a resource 213 containing the successor version in the version history. 215 Some systems may allow multiple of these link relations in order to 216 support branching. 218 4. IANA Considerations 220 The link relations below are to be registered by IANA per Section 7.1 221 of [RFC4287]: 223 4.1. 'version-history' Link Relation Registration 225 Attribute Value: version-history 227 Description: See Section 3.1. 229 Expected display characteristics: Undefined; this relation can be 230 used for background processing or to provide extended 231 functionality without displaying its value. 233 Security considerations: See Section 5. 235 4.2. 'latest-version' Link Relation Registration 237 Attribute Value: latest-version 239 Description: See Section 3.2. 241 Expected display characteristics: Undefined; this relation can be 242 used for background processing or to provide extended 243 functionality without displaying its value. 245 Security considerations: See Section 5. 247 4.3. 'working-copy' Link Relation Registration 249 Attribute Value: working-copy 251 Description: See Section 3.3. 253 Expected display characteristics: Undefined; this relation can be 254 used for background processing or to provide extended 255 functionality without displaying its value. 257 Security considerations: See Section 5. 259 4.4. 'working-copy-of' Link Relation Registration 261 Attribute Value: working-copy-of 263 Description: See Section 3.4. 265 Expected display characteristics: Undefined; this relation can be 266 used for background processing or to provide extended 267 functionality without displaying its value. 269 Security considerations: See Section 5. 271 4.5. 'predecessor-version' Link Relation Registration 273 Attribute Value: predecessor-version 275 Description: See Section 3.5. 277 Expected display characteristics: Undefined; this relation can be 278 used for background processing or to provide extended 279 functionality without displaying its value. 281 Security considerations: See Section 5. 283 4.6. 'successor-version' Link Relation Registration 285 Attribute Value: successor-version 287 Description: See Section 3.6. 289 Expected display characteristics: Undefined; this relation can be 290 used for background processing or to provide extended 291 functionality without displaying its value. 293 Security considerations: See Section 5. 295 5. Security Considerations 297 Automated agents should take care when these relations cross 298 administrative domains (e.g., the URI has a different authority than 299 the current document). Such agents should also take care to detect 300 circular references. 302 Care should be applied when versioned resources are subject to 303 differing access policies. In this case, exposing links may leak 304 information even if the linked resource itself is properly secured. 305 In particular, the syntax of the link URI/IRI could expose sensitive 306 information (see Section 16.2 of [RFC3253] for a similar 307 consideration in WebDAV Versioning). Note that this applies to 308 exposing link metadata in general, not only to links related to 309 versioning. 311 6. Acknowledgments 313 Thanks to the members of Content Management Interoperability Services 314 (CMIS) Technical Committee (TC) at OASIS for the initial proposal, 315 and to Jan Algermissen for feedback during IETF review. 317 7. References 319 7.1. Normative References 321 [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication 322 Format", RFC 4287, December 2005. 324 7.2. Informative References 326 [CMIS] Brown, A. , Gur-Esh, E. , McVeigh, R. , and F. Muller , 327 "Content Management Interoperability Services (CMIS) 328 Version 1.0" , OASIS CMIS v1.0 Committee Draft 04 , 329 September 2009 , . 332 Latest version available at 335 [JSR-283] Day Software, Nuescheler, D., and P. Piegaze, "Content 336 Repository API for Java(tm) Technology Specification", 337 Java Specification Request 283, August 2009, 338 . 340 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 341 Whitehead, "Versioning Extensions to WebDAV (Web 342 Distributed Authoring and Versioning)", RFC 3253, 343 March 2002. 345 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 346 Protocol", RFC 5023, October 2007. 348 [draft-nottingham-http-link-header] 349 Nottingham, M., "Web Linking", 350 draft-nottingham-http-link-header-07 (work in progress), 351 January 2010. 353 Appendix A. Relationship to Java Content Repository (JCR) and WebDAV 355 The link relations defined in Section 3 correspond to various 356 properties used in WebDAV Versioning [RFC3253] and JCR [JSR-283]: 358 version-history 360 WebDAV: the resource identified by the DAV:version-history 361 property ([RFC3253], Sections 5.2.1 and 5.3.1). 363 JCR: the node identified by jcr:versionHistory property 364 ([JSR-283], Section 3.13.2.4) for versionable nodes, the parent 365 folder for version nodes. 367 latest-version 369 WebDAV: for version-controlled resources, DAV:checked-in 370 ([RFC3253], Section 3.2.1) or DAV:checked-out ([RFC3253], Section 371 3.3.1), depending on checkin state. For version resources, a 372 successor version that itself does not have any successors. 374 JCR: the version node identified by the jcr:baseVersion property 375 ([JSR-283], Section 3.13.2.5) for versionable nodes; for version 376 nodes, a successor version that itself does not have any 377 successors. 379 working-copy 381 WebDAV: for version-controlled resources that are checked-out in 382 place: the resource itself. For version resources: each resource 383 identified by a member of the DAV:checkout-set property (see 384 [RFC3253], Section 3.4.3). 386 JCR: for checked-out versionable nodes: the node itself. 388 working-copy-of 390 WebDAV: the resource identified by the the DAV:checked-out 391 property (see [RFC3253], Section 3.3.1). 393 JCR: for checked-out versionable nodes: the node identified by the 394 jcr:baseVersion property ([JSR-283], Section 3.13.12.5). 396 predecessor-version 398 WebDAV: each resource identified by a member of DAV:predecessor- 399 set ([RFC3253], Sections 3.3.2 and 3.4.1). 401 JCR: each node identified by a member of jcr:predecessors 402 ([JSR-283], Section 3.13.3.3). 404 successor-version 406 WebDAV: each resource identified by a member of DAV:successor-set 407 ([RFC3253], Section 3.4.2). 409 JCR: each node identified by a member of jcr:successors 410 ([JSR-283], Section 3.13.3.4). 412 A.1. Example: Use of Link Relations in HTTP Link Header 414 The "Web Linking" specification ([draft-nottingham-http-link-header]) 415 generalizes Atom link relations, and also re-introduces the HTTP 416 "Link" header as a way to expose link relations in HTTP responses. 417 This will make it possible to expose version links independently from 418 a specific vocabulary, be it the Atom Feed Format ([RFC4287]) or 419 WebDAV properties ([RFC3253]). 421 For instance, a response to an VERSION-CONTROL request ([RFC3253], 422 Section 3.5) could expose newly created version-history and 423 checked-in version as link relations: 425 >> Request: 427 VERSION-CONTROL /docs/test.txt HTTP/1.1 428 Host: example.net 429 >> Response: 431 HTTP/1.1 204 No Content 432 Link: ; rel=latest-version; 433 anchor= 434 Link: ; rel=version-history; 435 anchor= 437 (Note that in this case, the anchor parameter is used, as the 438 response to a VERSION-CONTROL request is not a representation of the 439 resource at the Request-URI) 441 A subsequent HEAD request on that resource could expose the version- 442 history and latest-version relations as well: 444 >> Request: 446 HEAD /docs/test.txt HTTP/1.1 447 Host: example.net 449 >> Response: 451 HTTP/1.1 200 OK 452 Content-Type: text/plain; charset=UTF-8 453 Content-Length: 12345 454 Link: ; rel=latest-version 455 Link: ; rel=version-history 457 After creating more versions, following the latest-version would then 458 expose predecessors of a version: 460 >> Request: 462 HEAD /system/v/84345634/3 HTTP/1.1 463 Host: example.net 465 >> Response: 467 HTTP/1.1 200 OK 468 Content-Type: text/plain; charset=UTF-8 469 Content-Length: 12323 470 Link: ; rel=predecessor-version 472 Appendix B. Change Log (to be removed by RFC Editor before publication) 474 B.1. Since draft-brown-link-relations-00 476 Added Geoff Clemm as author. 478 Renamed link relation "all-versions" to "version-history". Fixed 479 description of "working-resource" relation to state that it appears 480 on a version resource. 482 B.2. Since draft-brown-link-relations-01 484 Rewrite terminology and link relations using simpler definitions that 485 can reflect versioning approaches different from WebDAV. 487 Add JCR/WebDAV property table. And reference to Web Linking draft 488 (for now informative) and examples showing use of the Link header. 490 B.3. Since draft-brown-link-relations-02 492 Add and resolve issue "iana". 494 B.4. Since draft-brown-link-relations-03 496 Fix typo ("working-resource" instead of "working-copy"). Add and 497 resolve issues "checked-out", "cmis" and "working-copy-of". 499 B.5. Since draft-brown-link-relations-04 501 Close issue "working-copy-of", which was really fixed in -04. 503 B.6. Since draft-brown-link-relations-05 505 Fix VERSION-CONTROL example to return 204 (there's no response body). 506 Fix country names in contact information. Add and resolve issue 507 "expose-urls". 509 B.7. Since draft-brown-link-relations-06 511 Update reference to draft-nottingham-http-link-header. Add "latest 512 version" link to CMIS reference. Change title to "Link Relations for 513 Simple Version Navigation between Web Resources" and minimally expand 514 Abstract and Introduction text (see "terseness"). 516 Appendix C. Resolved issues (to be removed by RFC Editor before 517 publication) 519 Issues that were either rejected or resolved in this version of this 520 document. 522 C.1. edit 524 Type: edit 526 julian.reschke@greenbytes.de (2009-11-19): Umbrella issue for 527 editorial fixes/enhancements. 529 C.2. terseness 531 Type: edit 533 lars.eggert@nokia.com (2010-01-19): I'd be good to mention ATOM 534 somewhere in the title. Also, both the abstract and the introduction 535 are extremely terse, to the point where it's hard to understand what 536 technologies/protocols this applies to. 538 Resolution (2010-01-22): Done. 540 Authors' Addresses 542 Al Brown 543 IBM 544 3565 Harbor Blvd 545 Costa Mesa, California 92626 546 USA 548 Email: albertcbrown@us.ibm.com 550 Geoffrey Clemm 551 IBM 552 20 Maguire Road 553 Lexington, MA 02421 554 USA 556 Email: geoffrey.clemm@us.ibm.com 557 Julian F. Reschke (editor) 558 greenbytes GmbH 559 Hafenweg 16 560 Muenster, NW 48155 561 Germany 563 Email: julian.reschke@greenbytes.de 564 URI: http://greenbytes.de/tech/webdav/