RFC 5829

Link Relation Types for Simple Version Navigation between Web Resources

📅 published April 2010, from ietf

okay bestie, this one is RFC 5829 💖 It's an Informational doc from the IETF (Internet Engineering Task Force), published in April 2010, and it's all about Link Relation Types for Simple Version Navigation between Web Resources. The authors are A. Brown and G. Clemm from IBM, plus J. Reschke, Ed. from greenbytes (the "Ed." just means J. Reschke was the editor 🫶). Its category is Informational and its ISSN is 2070-1721. The title block doesn't list anything it obsoletes or updates, so it isn't replacing or changing any other RFC 🌸.

Abstract ✨

so this spec defines a set of link relation types that may be used on Web resources to hop between a resource and other resources tied to version control, like past versions and working copies. it's giving navigation 🧭

Status of This Memo 💅

this doc is not an Internet Standards Track spec. it's published for informational purposes, so no pressure 🫶

It's an IETF product and it represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every doc the IESG approves is a candidate for any level of Internet Standard, so check Section 2 of RFC 5741 if you're curious about that. 🤓

For the current status, any errata, and how to give feedback, head to http://www.rfc-editor.org/info/rfc5829. 🔗

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. ✨

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the date of publication. Please actually read these, because they spell out your rights and restrictions for this document 📜

Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. They come without warranty, as described in the Simplified BSD License. 💜

Table of Contents 🍓

1. Introduction ....................................................3
2. Terminology .....................................................3
3. Link Relations ..................................................4
   3.1. 'version-history' ..........................................4
   3.2. 'latest-version' ...........................................4
   3.3. 'working-copy' .............................................4
   3.4. 'working-copy-of' ..........................................4
   3.5. 'predecessor-version' ......................................4
   3.6. 'successor-version' ........................................5
4. IANA Considerations .............................................5
   4.1. 'version-history' Link Relation Registration ...............5
   4.2. 'latest-version' Link Relation Registration ................5
   4.3. 'working-copy' Link Relation Registration ..................5
   4.4. 'working-copy-of' Link Relation Registration ...............6
   4.5. 'predecessor-version' Link Relation Registration ...........6
   4.6. 'successor-version' Link Relation Registration .............6
5. Security Considerations .........................................6
6. Acknowledgments .................................................7
7. References ......................................................7
   7.1. Normative References .......................................7
   7.2. Informative References .....................................7
Appendix A.  Relationship to Java Content Repository (JCR) and
             WebDAV ................................................9
   A.1.  Example: Use of Link Relations in HTTP Link Header .......10

1. Introduction ✨

this spec defines a set of link relation types that may be used on Web resources in a system that supports versioning 🎀 so you can navigate between the different resources available, like past versions and working copies. main character navigation 💅

these link relations get used in the AtomPub ([RFC5023]) bindings of the "Content Management Interoperability Services" (CMIS). check Section 3.4.3.3 of [CMIS] if you want the details 🫶

2. Terminology 🧚

Versioned Resource

when a resource is put under version control, it becomes a "versioned resource" 🦋 lots of servers protect these from changes by treating them as "checked in." before you can modify one, you need a "checkout" operation, and then a "checkin" operation gets you back to the "checked-in" state. other servers let you modify things directly, and in that case the checkout/checkin can happen implicitly 🙈

Version History

a "version history" resource is a resource that holds all the versions of one particular versioned resource 📚

Predecessor, Successor

when a versioned resource gets checked out and then checked back in, the version that got checked out becomes a "predecessor" of the version the checkin creates 🔁 a client can name multiple predecessors for a new version if that version is logically a merge of them, which is so iconic 🫶 the inverse of the predecessor relation is the "successor" relation. so if X is a predecessor of Y, then Y is a successor of X ✨

Working Copy

a "working copy" is a resource at a server-defined URL that you can use to create a new version of a versioned resource 🌸

Checkout

a "checkout" is an operation on a versioned resource that creates a working copy, or changes the versioned resource into a working copy as well ("in-place versioning") 💅

Checkin

a "checkin" is an operation on a working copy that creates a new version of its corresponding versioned resource 💖

Note: the operations for putting a resource under version control and for checking in and checking out depend on the protocol in use, and they're beyond the scope of this document. see [CMIS], [RFC3253], and [JSR-283] for examples 👑

these are the link relations that get defined here 🎀

3.1. 'version-history'

when this is included on a versioned resource, the link points to a resource containing the version history for that resource 📚

3.2. 'latest-version'

when this is included on a versioned resource, the link points to a resource containing the latest (e.g., current) version 👑

the latest version is defined by the system. for linear versioning systems, that's probably the latest version by timestamp. for systems that support branching, there will be multiple latest versions, one for each branch in the version history 🌿

some systems may allow more than one of these link relations 💜

3.3. 'working-copy'

when this is included on a versioned resource, the link points to a working copy for that resource ✨

some systems may allow more than one of these link relations 💜

3.4. 'working-copy-of'

when this is included on a working copy, the link points to the versioned resource that this working copy was obtained from 🔗

3.5. 'predecessor-version'

when this is included on a versioned resource, the link points to a resource containing the predecessor version in the version history ⏪

some systems may allow more than one of these link relations when multiple branches merge 🔀

3.6. 'successor-version'

when this is included on a versioned resource, the link points to a resource containing the successor version in the version history ⏩

some systems may allow more than one of these link relations in order to support branching 🌳

4. IANA Considerations 🎀

the link relations below have been registered by IANA per Section 7.1 of [RFC4287] 📝

  • Attribute Value: version-history
  • Description: See Section 3.1.
  • Expected display characteristics: Undefined. This relation can be used for background processing or to provide extended functionality without displaying its value. 🙈
  • Security considerations: See Section 5.
  • Attribute Value: latest-version
  • Description: See Section 3.2.
  • Expected display characteristics: Undefined. This relation can be used for background processing or to provide extended functionality without displaying its value. 🙈
  • Security considerations: See Section 5.
  • Attribute Value: working-copy
  • Description: See Section 3.3.
  • Expected display characteristics: Undefined. This relation can be used for background processing or to provide extended functionality without displaying its value. 🙈
  • Security considerations: See Section 5.
  • Attribute Value: working-copy-of
  • Description: See Section 3.4.
  • Expected display characteristics: Undefined. This relation can be used for background processing or to provide extended functionality without displaying its value. 🙈
  • Security considerations: See Section 5.
  • Attribute Value: predecessor-version
  • Description: See Section 3.5.
  • Expected display characteristics: Undefined. This relation can be used for background processing or to provide extended functionality without displaying its value. 🙈
  • Security considerations: See Section 5.
  • Attribute Value: successor-version
  • Description: See Section 3.6.
  • Expected display characteristics: Undefined. This relation can be used for background processing or to provide extended functionality without displaying its value. 🙈
  • Security considerations: See Section 5.

7.2. Informative References 📚

okay so these are the "good to know" refs, bestie 🫶 Not required reading to implement the spec, but they're where the big WebDAV, JCR, and CMIS vibes come from 💖

[CMIS] Brown, A., Gur-Esh, E., McVeigh, R., and F. Mueller, "Content Management Interoperability Services (CMIS) Version 1.0", OASIS Content Management Interoperability Services (CMIS) Version 1.0 Committee Specification 01, March 2010, <http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html>.

Latest version available at <http://docs.oasis-open.org/cmis/CMIS/v1.0/cmis-spec-v1.0.html>

[JSR-283] Day Software, Nuescheler, D., and P. Piegaze, "Content Repository API for Java(tm) Technology Specification", Java Specification Request 283, August 2009, <http://www.day.com/specs/jcr/2.0/>.

[RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. Whitehead, "Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)", RFC 3253, March 2002.

[RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing Protocol", RFC 5023, October 2007.

[WEB-LINKING] Nottingham, M., "Web Linking", Work in Progress, March 2010.

Appendix A. Relationship to Java Content Repository (JCR) and WebDAV ✨

okay this appendix is the translation guide 🌈 The link relations from Section 3 line up with a bunch of properties in WebDAV Versioning [RFC3253] and JCR [JSR-283], so here's the matching cheat sheet 💅

version-history

  • WebDAV: the resource identified by the DAV:version-history property ([RFC3253], Sections 5.2.1 and 5.3.1).
  • JCR: the node identified by jcr:versionHistory property ([JSR-283], Section 3.13.2.4) for versionable nodes, the parent folder for version nodes.

latest-version

  • WebDAV: for version-controlled resources, DAV:checked-in ([RFC3253], Section 3.2.1) or DAV:checked-out ([RFC3253], Section 3.3.1), depending on checkin state. For version resources, a successor version that itself does not have any successors.
  • JCR: the version node identified by the jcr:baseVersion property ([JSR-283], Section 3.13.2.5) for versionable nodes; for version nodes, a successor version that itself does not have any successors.

working-copy

  • WebDAV: for version-controlled resources that are checked-out in place: the resource itself. For version resources: each resource identified by a member of the DAV:checkout-set property (see [RFC3253], Section 3.4.3).
  • JCR: for checked-out versionable nodes: the node itself.

working-copy-of

  • WebDAV: the resource identified by the DAV:checked-out property (see [RFC3253], Section 3.3.1).
  • JCR: for checked-out versionable nodes: the node identified by the jcr:baseVersion property ([JSR-283], Section 3.13.12.5).

predecessor-version

  • WebDAV: each resource identified by a member of DAV:predecessor-set ([RFC3253], Sections 3.3.2 and 3.4.1).
  • JCR: each node identified by a member of jcr:predecessors ([JSR-283], Section 3.13.3.3).

successor-version

  • WebDAV: each resource identified by a member of DAV:successor-set ([RFC3253], Section 3.4.2).
  • JCR: each node identified by a member of jcr:successors ([JSR-283], Section 3.13.3.4).

the "Web Linking" spec ([WEB-LINKING]) takes Atom link relations and generalizes them, and it also brings back the HTTP "Link" header as a way to show link relations in HTTP responses 🔥 This means you can expose version links without being locked into one vocabulary, whether that's the Atom Feed Format ([RFC4287]) or WebDAV properties ([RFC3253]) 💜

for example, a response to a VERSION-CONTROL request ([RFC3253], Section 3.5) could expose a newly created version-history and checked-in version as link relations 🎀

>> Request:

VERSION-CONTROL /docs/test.txt HTTP/1.1
Host: example.net

>> Response:

HTTP/1.1 204 No Content
Link: </system/v/84345634/1>; rel=latest-version;
      anchor=</docs/test.txt>
Link: </system/vh/84345634>; rel=version-history;
      anchor=</docs/test.txt>
(Note that in this case, the anchor parameter is used, as the response to a VERSION-CONTROL request is not a representation of the resource at the Request-URI.)

a subsequent HEAD request on that resource could expose the version-history and latest-version relations as well 🌸

>> Request:

HEAD /docs/test.txt HTTP/1.1
Host: example.net

>> Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: 12345
Link: </system/v/84345634/1>; rel=latest-version
Link: </system/vh/84345634>; rel=version-history

after creating more versions, following the latest-version would then expose predecessors of a version 🧚

>> Request:

HEAD /system/v/84345634/3 HTTP/1.1
Host: example.net

>> Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: 12323
Link: </system/v/84345634/2>; rel=predecessor-version

Authors' Addresses 🫶

and here are the people who made this happen, with their addresses 💖

Al Brown
IBM
3565 Harbor Blvd
Costa Mesa, California 92626
USA

EMail: albertcbrown@us.ibm.com


Geoffrey Clemm
IBM
20 Maguire Road
Lexington, MA 02421
USA

EMail: geoffrey.clemm@us.ibm.com


Julian F. Reschke (editor)
greenbytes GmbH
Hafenweg 16
Muenster, NW 48155
Germany

EMail: julian.reschke@greenbytes.de
URI:   http://greenbytes.de/tech/webdav/

that's the whole spec, bestie 🌈✨💅 slay!

📦 where this page comes from