idnits 2.17.1 draft-brown-versioning-link-relations-03.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 (November 20, 2009) is 5270 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'TM' is mentioned on line 256, but not defined Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 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: May 24, 2010 J. Reschke, Ed. 6 greenbytes 7 November 20, 2009 9 Link Relations for Simple Version Navigation 10 draft-brown-versioning-link-relations-03 12 Abstract 14 This specification defines Atom link relations for navigation between 15 a resource and its versions. 17 Editorial Note (To be removed by RFC Editor before publication) 19 Please send comments to the Atom Syntax mailing list 20 (). 22 Status of this Memo 24 This Internet-Draft is submitted to IETF in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that 29 other groups may also distribute working documents as Internet- 30 Drafts. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 The list of current Internet-Drafts can be accessed at 38 http://www.ietf.org/ietf/1id-abstracts.txt. 40 The list of Internet-Draft Shadow Directories can be accessed at 41 http://www.ietf.org/shadow.html. 43 This Internet-Draft will expire on May 24, 2010. 45 Copyright Notice 47 Copyright (c) 2009 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3. Link Relations . . . . . . . . . . . . . . . . . . . . . . . . 3 65 3.1. version-history . . . . . . . . . . . . . . . . . . . . . 3 66 3.2. latest-version . . . . . . . . . . . . . . . . . . . . . . 4 67 3.3. working-copy . . . . . . . . . . . . . . . . . . . . . . . 4 68 3.4. predecessor-version . . . . . . . . . . . . . . . . . . . 4 69 3.5. successor-version . . . . . . . . . . . . . . . . . . . . 4 70 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 71 4.1. 'version-history' Link Relation Registration . . . . . . . 4 72 4.2. 'latest-version' Link Relation Registration . . . . . . . 5 73 4.3. 'working-copy' Link Relation Registration . . . . . . . . 5 74 4.4. 'predecessor-version' Link Relation Registration . . . . . 5 75 4.5. 'successor-version' Link Relation Registration . . . . . . 6 76 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 77 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 78 6.1. Normative References . . . . . . . . . . . . . . . . . . . 6 79 6.2. Informative References . . . . . . . . . . . . . . . . . . 6 80 Appendix A. Relationship to Java Content Repository (JCR) and 81 WebDAV . . . . . . . . . . . . . . . . . . . . . . . 7 82 A.1. Example: Use of Link Relations in HTTP Link Header . . . . 8 83 Appendix B. Contributors . . . . . . . . . . . . . . . . . . . . 9 84 Appendix C. Change Log (to be removed by RFC Editor before 85 publication) . . . . . . . . . . . . . . . . . . . . 9 86 C.1. Since draft-brown-link-relations-00 . . . . . . . . . . . 9 87 C.2. Since draft-brown-link-relations-01 . . . . . . . . . . . 10 88 C.3. Since draft-brown-link-relations-02 . . . . . . . . . . . 10 89 Appendix D. Resolved issues (to be removed by RFC Editor 90 before publication) . . . . . . . . . . . . . . . . . 10 91 D.1. iana . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 92 Appendix E. Open issues (to be removed by RFC Editor prior to 93 publication) . . . . . . . . . . . . . . . . . . . . 10 94 E.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 97 1. Introduction 99 This specification defines link relations that may be used on a 100 resource that exists in a system that supports versioning to navigate 101 among the different resources available, such as past versions. 103 2. Terminology 105 Versioned Resource 107 When a resource is put under version control, it becomes a 108 "versioned resource". A versioned resource can be "checked out" 109 to allow modification. 111 Version History 113 A "version history" resource is a resource that contains all the 114 versions of a particular versioned resource. 116 Predecessor, Successor 118 When a versioned resource is checked out and then subsequently 119 checked in, the version that was checked out becomes a 120 "predecessor" of the version created by the checkin. A client can 121 specify multiple predecessors for a new version if the new version 122 is logically a merge of those predecessors. The inverse of the 123 predecessor relation is the "successor" relation. Therefore, if X 124 is a predecessor of Y, then Y is a successor of X. 126 Working Copy 128 A "working copy" is a resource at a server-defined URL that can be 129 modified to create a new version of a versioned resource. 131 3. Link Relations 133 The following link relations are defined: 135 3.1. version-history 137 When included on a versioned resource, this link points to a resource 138 containing the version history for this resource. 140 3.2. latest-version 142 When included on a versioned resource, this link points to a resource 143 containing the latest (e.g., current) version. 145 The latest version is defined by the system. For linear versioning 146 systems, this is probably the latest version by timestamp. For 147 systems that support branching, there will be multiple latest 148 versions, one for each branch in the version history. 150 Some systems may allow multiple of these link relations. 152 3.3. working-copy 154 When included on a versioned resource, this link points to a working 155 copy for this resource. 157 Some systems may allow multiple of these link relations. 159 3.4. predecessor-version 161 When included on a versioned resource, this link points to a resource 162 containing the predecessor version in the version history. 164 Some systems may allow multiple of these link relations in the case 165 of a multiple branches merging. 167 3.5. successor-version 169 When included on a versioned resource, this link points to a resource 170 containing the successor version in the version history. 172 Some systems may allow multiple of these link relations in order to 173 support branching. 175 4. IANA Considerations 177 The link relations below are to be registered by IANA per Section 7.1 178 of [RFC4287]: 180 4.1. 'version-history' Link Relation Registration 182 Attribute Value: version-history 183 Description: See Section 3.1. 185 Expected display characteristics: Undefined; this relation can be 186 used for background processing or to provide extended 187 functionality without displaying its value. 189 Security considerations: See Section 5. 191 4.2. 'latest-version' Link Relation Registration 193 Attribute Value: latest-version 195 Description: See Section 3.2. 197 Expected display characteristics: Undefined; this relation can be 198 used for background processing or to provide extended 199 functionality without displaying its value. 201 Security considerations: See Section 5. 203 4.3. 'working-copy' Link Relation Registration 205 Attribute Value: working-copy 207 Description: See Section 3.3. 209 Expected display characteristics: Undefined; this relation can be 210 used for background processing or to provide extended 211 functionality without displaying its value. 213 Security considerations: See Section 5. 215 4.4. 'predecessor-version' Link Relation Registration 217 Attribute Value: predecessor-version 219 Description: See Section 3.4. 221 Expected display characteristics: Undefined; this relation can be 222 used for background processing or to provide extended 223 functionality without displaying its value. 225 Security considerations: See Section 5. 227 4.5. 'successor-version' Link Relation Registration 229 Attribute Value: successor-version 231 Description: See Section 3.5. 233 Expected display characteristics: Undefined; this relation can be 234 used for background processing or to provide extended 235 functionality without displaying its value. 237 Security considerations: See Section 5. 239 5. Security Considerations 241 Automated agents should take care when these relation crosses 242 administrative domains (e.g., the URI has a different authority than 243 the current document). Such agents should also take care to detect 244 circular references. 246 6. References 248 6.1. Normative References 250 [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication 251 Format", RFC 4287, December 2005. 253 6.2. Informative References 255 [JSR-283] Day Software, Nuescheler, D., and P. Piegaze, "Content 256 Repository API for Java[TM] Technology Specification", 257 Java Specification Request 283, August 2009, 258 . 260 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 261 Whitehead, "Versioning Extensions to WebDAV (Web 262 Distributed Authoring and Versioning)", RFC 3253, 263 March 2002. 265 [draft-nottingham-http-link-header] 266 Nottingham, M., "Web Linking", 267 draft-nottingham-http-link-header-06 (work in progress), 268 July 2009. 270 Appendix A. Relationship to Java Content Repository (JCR) and WebDAV 272 The link relations defined in Section 3 correspond to various 273 properties used in WebDAV Versioning [RFC3253] and JCR [JSR-283]: 275 version-history 277 WebDAV: the resource identified by the DAV:version-history 278 property ([RFC3253], Sections 5.2.1 and 5.3.1). 280 JCR: the node identified by jcr:versionHistory property 281 ([JSR-283], Section 3.13.2.4) for versionable nodes, the parent 282 folder for version nodes. 284 latest-version 286 WebDAV: for version-controlled resources, DAV:checked-in 287 ([RFC3253], Section 3.2.1) or DAV:checked-out ([RFC3253], Section 288 3.3.1), depending on checkin state. For version resources, a 289 successor version that itself does not have any successors. 291 JCR: the version node identified by the jcr:baseVersion property 292 ([JSR-283], Section 3.13.2.5) for versionable nodes; for version 293 nodes, a successor version that itself does not have any 294 successors. 296 working-resource 298 WebDAV: for version-controlled resources that are checked-out in 299 place: the resource itself. For version resources: each resource 300 identified by a member of the DAV:checkout-set property (see 301 [RFC3253], Section 3.4.3). 303 JCR: for checked-out versionable nodes: the node itself. 305 predecessor-version 307 WebDAV: each resource identified by a member of DAV:predecessor- 308 set ([RFC3253], Sections 3.3.2 and 3.4.1). 310 JCR: each node identified by a member of jcr:predecessors 311 ([JSR-283], Section 3.13.3.3). 313 successor-version 315 WebDAV: each resource identified by a member of DAV:successor-set 316 ([RFC3253], Section 3.4.2). 318 JCR: each node identified by a member of jcr:successors 319 ([JSR-283], Section 3.13.3.4). 321 A.1. Example: Use of Link Relations in HTTP Link Header 323 The "Web Linking" specification ([draft-nottingham-http-link-header]) 324 generalizes Atom link relations, and also re-introduces the HTTP 325 "Link" header as a way to expose link relations in HTTP responses. 326 This will make it possible to expose version links independently from 327 a specific vocabulary, be it the Atom Feed Format ([RFC4287]) or 328 WebDAV properties ([RFC3253]). 330 For instance, a response to an VERSION-CONTROL request ([RFC3253], 331 Section 3.5) could expose newly created version-history and 332 checked-in version as link relations: 334 >> Request: 336 VERSION-CONTROL /docs/test.txt HTTP/1.1 337 Host: example.net 339 >> Response: 341 HTTP/1.1 200 OK 342 Link: ; rel=latest-version; 343 anchor= 344 Link: ; rel=version-history; 345 anchor= 347 (Note that in this case, the anchor parameter is used, as the 348 response to a VERSION-CONTROL request is not a representation of the 349 resource at the Request-URI) 351 A subsequent HEAD request on that resource could expose the version- 352 history and latest-version relations as well: 354 >> Request: 356 HEAD /docs/test.txt HTTP/1.1 357 Host: example.net 358 >> Response: 360 HTTP/1.1 200 OK 361 Content-Type: text/plain; charset=UTF-8 362 Content-Length: 12345 363 Link: ; rel=latest-version 364 Link: ; rel=version-history 366 After creating more versions, following the latest-version would then 367 expose predecessors of a version: 369 >> Request: 371 HEAD /system/v/84345634/3 HTTP/1.1 372 Host: example.net 374 >> Response: 376 HTTP/1.1 200 OK 377 Content-Type: text/plain; charset=UTF-8 378 Content-Length: 12323 379 Link: ; rel=predecessor-version 381 Appendix B. Contributors 383 The content and concepts within are a product of the Content 384 Management Interoperability Services (CMIS) Technical Committee (TC) 385 at OASIS. 387 All members of the TC have contributed. 389 Appendix C. Change Log (to be removed by RFC Editor before publication) 391 C.1. Since draft-brown-link-relations-00 393 Added Geoff Clemm as author. 395 Renamed link relation "all-versions" to "version-history". Fixed 396 description of "working-resource" relation to state that it appears 397 on a version resource. 399 C.2. Since draft-brown-link-relations-01 401 Rewrite terminology and link relations using simpler definitions that 402 can reflect versioning approaches different from WebDAV. 404 Add JCR/WebDAV property table. And reference to Web Linking draft 405 (for now informative) and examples showing use of the Link header. 407 C.3. Since draft-brown-link-relations-02 409 Add and resolve issue "iana". 411 Appendix D. Resolved issues (to be removed by RFC Editor before 412 publication) 414 Issues that were either rejected or resolved in this version of this 415 document. 417 D.1. iana 419 Type: change 421 julian.reschke@greenbytes.de (2009-11-20): Use proper IANA 422 registration template. 424 Appendix E. Open issues (to be removed by RFC Editor prior to 425 publication) 427 E.1. edit 429 Type: edit 431 julian.reschke@greenbytes.de (2009-11-19): Umbrella issue for 432 editorial fixes/enhancements. 434 Authors' Addresses 436 Al Brown 437 IBM 438 3565 Harbor Blvd 439 Costa Mesa, California 92626 440 US 442 Email: albertcbrown@us.ibm.com 443 Geoffrey Clemm 444 IBM 445 20 Maguire Road 446 Lexington, MA 02421 447 US 449 Email: geoffrey.clemm@us.ibm.com 451 Julian F. Reschke (editor) 452 greenbytes GmbH 453 Hafenweg 16 454 Muenster, NW 48155 455 Germany 457 Email: julian.reschke@greenbytes.de 458 URI: http://greenbytes.de/tech/webdav/