RFC 8574

cite-as: A Link Relation to Convey a Preferred URI for Referencing

📅 published April 2019, from ietf

cite-as: A Link Relation to Convey a Preferred URI for Referencing 🎀

Okay bestie, this is RFC 8574 💖 It was published in April 2019 as an Independent Submission in the Informational category, with ISSN 2070-1721. The authors are H. Van de Sompel (Data Archiving and Networked Services), M. Nelson (Old Dominion University), G. Bilder (Crossref), J. Kunze (California Digital Library), and S. Warner (Cornell University) 🫶. The header doesn't list anything this one obsoletes or updates, so it's not replacing any other RFC ✨.

Abstract 🌸

Okay so a web resource is usually referenced by the URI you directly access it with. But sometimes referencing it with a different URI is the move 💅. This spec defines a link relation type that can be used to convey that preference 🦋.

Status of This Memo 📜

Real talk, this document is not an Internet Standards Track specification 🙈. It's published for informational purposes.

It's a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor picked it for publication at their discretion and makes no statement about its value for implementation or deployment. Documents the RFC Editor approves for publication aren't candidates for any level of Internet Standard. See Section 2 of RFC 7841 for more on that 🧚

Info about the current status of this doc, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8574 💌

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

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they're in effect on the date of publication. Please read these carefully, bestie, because they describe your rights and restrictions with respect to this document 📖

Table of Contents 🗂️

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     3.1.  Persistent Identifiers  . . . . . . . . . . . . . . . . .   3
     3.2.  Version Identifiers . . . . . . . . . . . . . . . . . . .   5
     3.3.  Preferred Social Identifier . . . . . . . . . . . . . . .   5
     3.4.  Multi-resource Publications . . . . . . . . . . . . . . .   6
   4.  The "cite-as" Relation Type for Expressing a Preferred URI
       for the Purpose of Referencing  . . . . . . . . . . . . . . .   6
   5.  Distinction with Other Relation Types . . . . . . . . . . . .   8
     5.1.  The "bookmark" Relation Type  . . . . . . . . . . . . . .   9
     5.2.  The "canonical" Relation Type . . . . . . . . . . . . . .   9
   6.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .  10
     6.1.  Persistent HTTP URI . . . . . . . . . . . . . . . . . . .  11
     6.2.  Version URIs  . . . . . . . . . . . . . . . . . . . . . .  12
     6.3.  Preferred Profile URI . . . . . . . . . . . . . . . . . .  13
     6.4.  Multi-resource Publication  . . . . . . . . . . . . . . .  13
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  14
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  14
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  15
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  15
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  15
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  17
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  17

1. Introduction ✨

Okay so a web resource gets referenced all the time, like linked or bookmarked, by the URI you directly access it with 🔗. But sometimes referencing a resource with a different URI is the better call, for example because that other URI is meant to stick around longer. Right now there's no link relation type for conveying that alternative referencing preference. This spec fixes that gap by introducing a link relation type built for exactly that job 🫶.

2. Terminology 📚

The BCP 14 key words, which are "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL", mean what BCP 14 [RFC2119] [RFC8174] says they mean, but only when they show up in all capitals, just like that 💅. Otherwise they're just regular words.

This spec uses the terms "link context" and "link target" as defined in [RFC8288]. They line up with "Context IRI" and "Target IRI" from [RFC5988]. They're defined as IRIs (Internationalized Resource Identifiers), but in common scenarios they're also URIs 🌈

Also, this spec uses these terms:

  • "access URI": A URI at which a user agent accesses a web resource.
  • "reference URI": A URI, other than the access URI, that should preferentially be used for referencing. 🎯

By interacting with the access URI, the user agent may discover typed links. For those links, the access URI is the link context 🧚

3. Scenarios 🎬

3.1. Persistent Identifiers 🔒

Despite sound advice about designing Cool URIs [CoolURIs], link rot (HTTP 404 Not Found) is super common when you follow links on the Web 💀. Certain communities of practice (see examples below) have come up with solutions to fight this. These solutions usually look like this:

  • Accepting the reality that the web location of a resource -- the access URI -- may change over time.
  • Minting an additional URI for the resource -- the reference URI -- that is specifically intended to remain persistent over time.
  • Redirecting (typically with HTTP 301 Moved Permanently, HTTP 302 Found, or HTTP 303 See Other) from the reference URI to the access URI.
  • Committing, as a community of practice, to adjust that redirection whenever the access URI changes over time. 🔁

This approach is used by, for example:

  • Scholarly publishers that use DOIs (Digital Object Identifiers) [DOIs] to identify articles, and DOI URLs [DOI-URLs] to keep cross-publisher article-to-article links working. That's true even when the journals the articles appear in change hands from one publisher to another, for example as a result of an acquisition 📰
  • Authors of controlled vocabularies that use PURLs (Persistent Uniform Resource Locators) [PURLs] for vocabulary terms. That way the URIs they give vocabulary terms stay stable even if the vocabulary gets handed off to a new custodian 🏷️
  • A variety of organizations (including libraries, archives, and museums) that assign ARK (Archival Resource Key) URLs [ARK] to information objects to support long-term access 🏛️

For the investments in infrastructure behind these approaches to pay off, and for links to actually stay operational as intended, it's crucial that a resource gets referenced by its reference URI 🫶. But the access URI is where a user agent actually accesses the resource. For example, it's the URI in the browser's address bar. So there's a real risk that the access URI gets used for referencing instead of the reference URI [PIDs-must-be-used] 😬

The link relation type defined in this document lets user agents tell the reference URI apart from the access URI 💜

3.2. Version Identifiers 🕰️

Resource versioning systems often use a naming approach where:

  • The most recent version of a resource is always available at the same, generic URI.
  • Each version of the resource -- including the most recent one -- has a distinct version URI. 🏷️

For example, Wikipedia uses generic URIs of the form <https://en.wikipedia.org/wiki/John_Doe> and version URIs of the form <https://en.wikipedia.org/w/index.php?title=John_Doe&oldid=776253882> 📖

The current version of a resource is accessed at the generic URI, but some versioning systems have a policy that favors linking and referencing a specific version URI. Using the terminology from Section 2, these policies intend for the generic URI to be the access URI and for the version URI to be the reference URI. The reasoning is that the content at the generic URI will likely evolve over time, and accurate links or references should lead to the content as it was at the time of referencing ⏳. So Wikipedia's "Permanent link" and "Cite this page" features promote the version URI, not the generic URI 🌸

The link relation type defined in this document lets user agents tell the version URI apart from the generic URI ✨

3.3. Preferred Social Identifier 🧑‍🎤

A web user usually has multiple profiles on the Web, like one per social network, a personal homepage, a professional homepage, a FOAF (Friend Of A Friend) profile [FOAF], and so on. Each of these profiles is accessible at a distinct URI. But the user may prefer one of them, for example because it's the most complete, kept up to date, or expected to be long lived 💅. As an example, the first author of this document has, among others, these profile URIs:

Of these, from the perspective of the person the profiles describe, the first URI may be the preferred profile URI for referencing, because its domain isn't under the custodianship of a third party 🫶. When an agent accesses another profile URI, such as <https://orcid.org/0000-0002-0715-6126>, this preference for referencing by the first URI could be expressed 🦋

The link relation type defined in this specification lets user agents tell the preferred profile URI apart from the accessed profile URI 💖

3.4. Multi-resource Publications 📚

When publishing on the Web, it's not uncommon to make different components of a publication available as different web resources, each with their own URI 🌈. For example:

  • Contemporary scholarly publications routinely consist of a traditional article plus additional materials that are considered an integral part of the publication, like supplementary information, high-resolution images, or a video recording of an experiment 🔬
  • Scientific or governmental open data sets frequently consist of multiple files 🗂️
  • Online books typically consist of multiple chapters 📖

Each of these components is accessible at its own distinct URI, which is the access URI. But they often also share a URI assigned to the intellectual publication they're components of, which is the reference URI 🫶

The link relation type defined in this document lets user agents tell the URI of the intellectual publication apart from the access URI of one of its components 🧚

Okay so, a link with the "cite-as" relation type is basically saying "hey, when someone wants to reference this, use the link target's URI instead of the link context's URI" 💅. It lets the resource at the access URI (the link context) point super clearly at its reference URI (the link target), so everyone knows the target is the one to use for permanent citation 🎀.

The link target of a "cite-as" link SHOULD support protocol-based access, so that apps which store these links can actually reuse them to get to the resource 🔥.

The link target of a "cite-as" link SHOULD also let a user agent follow its nose back to the context of the link, for example by following redirects and/or links 🧚. That helps the user agent trust the target URI 🫶.

Because a "cite-as" link is all about expressing a preferred URI for referencing, the access URI SHOULD only provide one link with that relation type 💖. If there's more than one, the user agent may decide to pick one (for example, an HTTP URI over a mailto URI) based on what the reference URI is going to be used for 🌸.

Providing a "cite-as" link doesn't stop anyone from using the access URI for referencing if the app needs that extra specificity 📚. For example, in the scenario from Section 3.4, the access URI is likely required for annotating a specific component of an intellectual publication. Still, the annotation app might also want to include the reference URI in the annotation ✨.

Applications can use the info from a "cite-as" link in a bunch of ways, like:

  • Bookmarking tools and citation managers can take this preference into account when recording a URI.
  • Webometrics applications that trace URIs can trace both the access URI and the reference URI.
  • Discovery tools can support lookup by means of both the access URI and the reference URI. This includes web archives, which usually make archived versions of web resources findable by the original access URI of the archived resource. They can also make those archived resources findable by the associated reference URI 🗂️.

Some existing IANA-registered relationships kinda look like what "cite-as" is meant to convey 👀. But a closer look at them, as covered in the blog posts [identifier-blog], [canonical-blog], and [bookmark-blog], shows they aren't appropriate for various reasons, and that a new link relation type is required. The rest of this section is a summary of the detailed explanations in those blog posts.

It's pretty obvious that the following link relation types don't meet the requirements from Section 3 💀:

  • "alternate" [RFC4287]: The link target provides an alternate version of the content at the link context. These are usually variants based on dimensions that are subject to content negotiation, like the same content with a different Content-Type (for example, application/pdf vs. text/html) and/or a different Content-Language (for example, en vs. fr). The representations provided by the context URIs and target URIs in the scenarios in Sections 3.1 through 3.4 are not variants in the sense intended by [RFC4287], so "alternate" is not appropriate.
  • "duplicate" [RFC6249]: The link target is a resource whose available representations are byte-for-byte identical with the corresponding representations of the link context, like an identical file on a mirror site. In none of the scenarios described in Sections 3.1 through 3.4 do the link context and the link target provide identical content. So "duplicate" is not appropriate.
  • "related" [RFC4287]: The link target is a resource that is related to the link context. While "related" could be used in all of the scenarios described in Sections 3.1 through 3.4, its semantics are too vague to convey the specific semantics intended by "cite-as".

Two existing IANA-registered relationships deserve a closer look, and we'll dig into them in the rest of this section 🔍.

"bookmark" [W3C.REC-html52-20171214]: The link target provides a URI for the purpose of bookmarking the link context.

The intent of "bookmark" is the closest to "cite-as", since the link target is meant to be a permalink for the link context, for bookmarking purposes 📌. But this relation type goes way back to the earliest days of news syndication, before blogs and news feeds had permalinks to identify the individual resources aggregated into a single page. So its intent was to provide permalinks for different sections of an HTML document 📰. It was originally used with HTML elements like <div>, <h1>, and <h2>. More recently, HTML5 revised it to be used exclusively with the <article> element. On top of that, it's explicitly excluded from use in the <link> element in the HTML <head> and, as a consequence, in the HTTP Link header, which is semantically equivalent. For these technical and semantic reasons, using "bookmark" to convey the relationship intended by "cite-as" is not appropriate 🙈.

A more detailed justification for why "bookmark" is inappropriate, including a thorough overview of its turbulent history, is provided in [bookmark-blog] 📖.

"canonical" [RFC6596]: The meaning of "canonical" is commonly misunderstood based on its brief definition as being "the preferred version of a resource." The description in the abstract of [RFC6596] is more helpful. It states that "canonical" is intended to link to a resource that is preferred over resources with duplicative content. A closer reading of [RFC6596] makes clear that "canonical" is preferred for the purpose of content indexing. A typical use case is linking from each page in a multi-page magazine article to a single-page version of the article, provided for indexing by search engines. The former pages provide content that duplicates the superset content available on the latter page 📰✨.

The semantics of "canonical" as preferred for content indexing are different from the semantics of "cite-as" as preferred for referencing. Looking at the various scenarios shows that "canonical" isn't appropriate for conveying what "cite-as" is meant to convey 🙅‍♀️:

  • Scenario of Section 3.1: The reference URI that is intended to be persistent over time doesn't serve content that needs to be indexed. It just redirects to the access URI. Since "canonical" is preferred for content indexing, it's not appropriate to point at the reference URI (the persistent identifier) using the "canonical" link relation type. Also, Section 6.1 shows that scholarly publishers that assign persistent identifiers already use the "canonical" link relation type for search engine optimization, and it shows how that use contrasts with the intended use of "cite-as" 🔎.
  • Scenario of Section 3.2: In most common cases, custodians of resource versioning systems want search engines to index the most recent version of a page. So they'd use a "canonical" link to point from version URIs of a resource to the associated generic URI. Wikipedia effectively does this. However, for some resource versioning systems, including Wikipedia, version URIs are preferred for the purpose of referencing. So a "cite-as" link would point from the generic URI to the most recent version URI, which is the opposite direction of the "canonical" link 🔄.
  • Scenario of Section 3.3: The content at the link target and the link context are different profiles for the same person. Each profile, not just a preferred one, should be indexed. But a single one could be preferred for referencing 👤.
  • Scenario of Section 3.4: The content at the link target, if there is one, would typically be a landing page that includes descriptive metadata about the multi-resource publication and links to its component resources. Each component resource provides content that is different from, not duplicative of, the landing page 🗃️.

A more detailed justification for how "canonical" is inappropriate for addressing the requirements described in this document, including examples, is provided in [canonical-blog] 💡.

6. Examples

Sections 6.1 through 6.4 show examples of the use of links with the "cite-as" relation type. They illustrate how the typed links can be used in a response header and/or response body 🎀.

6.1. Persistent HTTP URI

PLOS ONE is one of many scholarly publishers that assigns DOIs to the articles it publishes. For example, https://doi.org/10.1371/journal.pone.0171057 is the persistent identifier for such an article 🧾. Via the DOI resolver, this persistent identifier redirects to https://journals.plos.org/plosone/doi?id=10.1371/journal.pone.0171057 in the plos.org domain. That URI itself redirects to https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0171057, which delivers the actual article in HTML 🌈.

The HTML article contains a <link> element with the "canonical" link relation type pointing at itself, https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0167475. As per Section 5.2, this indicates that the article content at that URI should be indexed by search engines 🔍.

PLOS ONE can also provide a link with the "cite-as" relation type pointing at the persistent identifier, to indicate that it's the preferred URI for permanent citation of the article 💜. Figure 1 shows the addition of the "cite-as" link in both the HTTP header and the HTML that results from an HTTP GET on the article URI https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0167475 🦋.

HTTP/1.1 200 OK
Link: <https://doi.org/10.1371/journal.pone.0171057> ; rel="cite-as"
Content-Type: text/html;charset=utf-8

<html>
 <head>
 ...
  <link rel="cite-as"
        href="https://doi.org/10.1371/journal.pone.0171057" />
  <link rel="canonical"
        href="https://journals.plos.org/plosone/article?
                           id=10.1371/journal.pone.0167475" />
 ...
 </head>
 <body>
  ...
 </body>
</html>

Figure 1: Response to HTTP GET on the URI of a Scholarly Article

6.2. Version URIs ✨

okay bestie, arXiv.org is literally doing the versioning thing from Section 3.2, and it's so clean 💅🦋 The most recent version of a preprint always lives at the same generic URI, so the preprint https://arxiv.org/abs/1711.03787 is the main character 👑

Here's the timeline tea ☕ If you hit https://arxiv.org/abs/1711.03787 between 10 November 2017 and 23 January 2018, you got version one. Starting 24 January 2018, that same URI served version two. So the generic URI is giving different content at different times 🙈

To make citations accurate, arXiv.org could add a "cite-as" link pointing from the generic URI to the most recent version URI. Then, assuming reference manager tools that read "cite-as" links exist (they do, iykyk 🧚), you'd get:

Figure 2 shows the header arXiv.org would send back in the first case, when someone does an HTTP HEAD on the generic URI https://arxiv.org/abs/1711.03787. The Link header is the star of the show ⭐

HTTP/1.1 200 OK
Date: Sun, 24 Dec 2017 16:12:43 GMT
Content-Type: text/html; charset=utf-8
Link: <https://arxiv.org/abs/1711.03787v1> ; rel="cite-as"
Vary: Accept-Encoding,User-Agent
     Figure 2: Response to HTTP HEAD on the Generic URI of the Landing
                       Page of an arXiv.org Preprint

6.3. Preferred Profile URI 🎀

Say the access URI is John Doe's home page. John can add a link with the "cite-as" relation type to it, which basically says "hey, please reference me through my FOAF profile instead" 🧚 Figure 3 shows the response to an HTTP GET on John's home page. Look at that <link rel="cite-as"> tag, it's so organized 🫶

HTTP/1.1 200 OK
Content-Type: text/html;charset=utf-8

<html>
 <head>
 ...
  <link rel="cite-as" href="http://johndoe.example.com/foaf"
        type="text/ttl"/>
 ...
 </head>
 <body>
  ...
 </body>
</html>
  Figure 3: Response to HTTP GET on the URI of John Doe's Home Page

6.4. Multi-resource Publication 📊

The Dryad Digital Repository at datadryad.org is all about hosting and preserving scientific datasets 🍓 A dataset is usually made of multiple resources. For example, the dataset "Data from: Climate, demography, and lek stability in an Amazonian bird" has an Excel spreadsheet, a csv file, and a zip file. Each one has different content and its own URI. The dataset also has a landing page at https://datadryad.org/resource/doi:10.5061/dryad.5d23f.

Each of these resources should be permanently cited by the persistent identifier given to the entire dataset as an intellectual publication, which is https://doi.org/10.5061/dryad.5d23f. So Dryad can add "cite-as" links on each resource's URI pointing to https://doi.org/10.5061/dryad.5d23f. Figure 4 shows this for the csv file, using the HTTP Link header 📁

HTTP/1.1 200 OK
Date: Tue, 12 Jun 2018 19:19:22 GMT
Last-Modified: Wed, 17 Feb 2016 18:37:02 GMT
Content-Type: text/csv;charset=ISO-8859-1
Content-Length: 25414
Link: <https://doi.org/10.5061/dryad.5d23f> ; rel="cite-as"

DATE,Year,PLOT/TRAIL,LOCATION,SPECIES CODE,BAND NUM,COLOR,SEX,AGE,
 TAIL,WING,TARSUS,NARES,DEPTH,WIDTH,WEIGHT
6/26/02,2002,DANTA,325,PIPFIL,969,B/O,M,AHY,80,63,16,7.3,3.9,4.1,
 14.4
...
2/3/13,2013,LAGO,,PIPFIL,BR-5095,O/YPI,M,SCB,78,65.5,14.2,7.5,3.8,
 3.7,14.3
  Figure 4: Response to HTTP GET on the URI of a csv File That Is a
                Component of a Scientific Dataset

7. IANA Considerations 🌈

IANA registered the link relation type per Section 2.1.1 of [RFC8288], and here's the registration 📝

   Relation Name: cite-as

   Description: Indicates that the link target is preferred over the
   link context for the purpose of permanent citation.

   Reference: RFC 8574

8. Security Considerations 🚨

Real talk, this section is serious, so read carefully 🙈

In cases where the agent has no way to automatically verify the correctness of the reference URI (cf. Section 4), out-of-band mechanisms might be required to establish trust. Translation: you might need to check things some other way, not just trust the link.

If a trusted site gets compromised, the "cite-as" link relation could be used with malicious intent to supply misleading URIs for referencing. That's a full-on disaster 💀 Following these links might send user agents to an attacker's site, break the referencing record they're supposed to support, or corrupt algorithmic interpretation of referencing data.

9. References 📚

9.1. Normative References

9.2. Informative References

Acknowledgements 🫶

The authors would like to thank the following individuals for their comments and suggestions: Martin Klein, Harihar Shankar, Peter Williams, John Howard, Mark Nottingham, and Graham Klyne. 💜

Authors' Addresses 🖋️

Herbert Van de Sompel Data Archiving and Networked Services Email: herbert.van.de.sompel@dans.knaw.nl URI: https://orcid.org/0000-0002-0715-6126

Michael Nelson Old Dominion University Email: mln@cs.odu.edu URI: http://www.cs.odu.edu/~mln/

Geoffrey Bilder Crossref Email: gbilder@crossref.org URI: https://www.crossref.org/authors/geoffrey-bilder/

John Kunze California Digital Library Email: jak@ucop.edu URI: https://orcid.org/0000-0001-7604-8041

Simeon Warner Cornell University Email: simeon.warner@cornell.edu URI: https://orcid.org/0000-0002-7970-7855

📦 where this page comes from