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/