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/