Web Linking

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119],[RFC8174] when, and only when, they appear in all capitals, as shown here.

This document uses the Augmented Backus-Naur Form (ABNF) notation of [RFC7230], including the #rule, and explicitly includes the following rules from it: quoted-string, token, SP (space), BWS (bad whitespace), OWS (optional whitespace), RWS (required whitespace) LOALPHA, DIGIT.

Additionally, the following rules are included from [RFC3986]: URI and URI-Reference; from [RFC6838]: type-name and subtype-name; from [W3C.REC-css3-mediaqueries-20120619]: media-query-list; and from [RFC5646]: Language-Tag.

The requirements regarding conformance and error handling highlighted in [RFC7230], Section 2.5 apply to this document.

In the simplest case, a link relation type identifies the semantics of a link. For example, a link with the relation type “copyright” indicates that the current link context has a copyright resource at the link target.

Link relation types can also be used to indicate that the target resource has particular attributes, or exhibits particular behaviours; for example, a “service” link implies that the link target can be used as part of a defined protocol (in this case, a service description).

Relation types are not to be confused with media types [RFC2046]; they do not identify the format of the representation that results when the link is dereferenced. Rather, they only describe how the current context is related to another resource.

Relation types SHOULD NOT infer any additional semantics based upon the presence or absence of another link relation type, or its own cardinality of occurrence. An exception to this is the combination of the “alternate” and “stylesheet” registered relation types, which has special meaning in HTML for historical reasons.

There are two kinds of relation types: registered and extension.

Target attributes are a list of key/value pairs that describe the link or its target; for example, a media type hint.

They can be defined both by individual link relation types and by link serialisations.

This specification does not attempt to coordinate the name of target attributes, their cardinality or use. Those creating and maintaining serialisations SHOULD coordinate their target attributes to avoid conflicts in semantics or syntax, and MAY define their own registries of target attributes.

The names of target attributes SHOULD conform to the token rule, but SHOULD NOT include any of the characters “%”, “’” or “*”, for portability across serializations, and MUST be compared in a case-insensitive fashion.

• The serialisation of their values into Unicode or a subset thereof, to maximise their chances of portability across link serialisations.
• The semantics and error handling of multiple occurrences of the target attribute on a given link.

This specification does define target attributes for use in the Link HTTP header field in Section 3.4.

Each link-value conveys one target IRI as a URI-Reference (after conversion to one, if necessary; see [RFC3987], Section 3.1) inside angle brackets (“<>”). If the URI-Reference is relative, parsers MUST resolve it as per [RFC3986], Section 5. Note that any base IRI appearing in the message’s content is not applied.

By default, the context of a link conveyed in the Link header field is the URL of the representation it is associated with, as defined in [RFC7231], Section 3.1.4.1, serialised as a URI.

When present, the anchor parameter overrides this with another URI, such as a fragment of this resource, or a third resource (i.e., when the anchor value is an absolute URI). If the anchor parameter’s value is a relative URI, parsers MUST resolve it as per [RFC3986], Section 5. Note that any base URI from the body’s content is not applied.

  URI-Reference ; Section 4.1 of {{RFC3986}}

Link application can choose to ignore links with an anchor parameter. For example, the application in use might not allow the link context to be assigned to a different resource. In such cases, the entire link is to be ignored; link applications MUST NOT process the link without applying the anchor.

Note that depending on HTTP status code and response headers, the link context might be “anonymous” (i.e., no link context is available). For example, this is the case on a 404 response to a GET request.

The relation type of a link conveyed in the Link header field is conveyed in the “rel” parameter’s value. The “rel” parameter MUST be present but MUST NOT appear more than once in a given link-value; occurrences after the first MUST be ignored by parsers.

The “rel” parameter can, however, contain multiple link relation types. When this occurs, it establishes multiple links that share the same context, target, and target attributes.

The “rev” parameter has been used in the past to indicate that the semantics of the relationship are in the reverse direction. That is, a link from A to B with REL=”X” expresses the same relationship as a link from B to A with REV=”X”. “rev” is deprecated by this specification because it often confuses authors and readers; in most cases, using a separate relation type is preferable.

  relation-type *( 1*SP relation-type )

  relation-type  = reg-rel-type / ext-rel-type
  reg-rel-type   = LOALPHA *( LOALPHA / DIGIT / "." / "-" )
  ext-rel-type   = URI ; Section 3 of {{RFC3986}}

Note that extension relation types are REQUIRED to be absolute URIs in Link header fields, and MUST be quoted when they contain characters not allowed in tokens, such as semicolon (“;”) or comma (“,”) (as these characters are used as delimiters in the header field itself).

The Link header field defines several target attributes specific to this serialisation, and also allows extension target attributes. Target attributes are serialised in the Link header field as parameters (see [RFC7231], Section 3.1.1.1 for the definition of their syntax).

Link: <http://example.com/TheBook/chapter2>; rel="previous";
      title="previous chapter"

indicates that “chapter2” is previous to this resource in a logical navigation path.

Similarly,

Link: </>; rel="http://example.net/foo"

indicates that the root resource (“/”) is related to this resource with the extension relation type “http://example.net/foo”.

Link: </terms>; rel="copyright"; anchor="#foo"

indicates that the linked copyright terms only apply to the portion of the document indicated by the (media type-specific) fragment identifier “foo”.

The example below shows an instance of the Link header field encoding multiple links, and also the use of RFC 5987 encoding to encode both non-ASCII characters and language information.

Link: </TheBook/chapter2>;
      rel="previous"; title*=UTF-8'de'letztes%20Kapitel,
      </TheBook/chapter4>;
      rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel

Here, both links have titles encoded in UTF-8, use the German language (“de”), and the second link contains the Unicode code point U+00E4 (“LATIN SMALL LETTER A WITH DIAERESIS”).

Link: <http://example.org/>;
      rel="start http://example.net/relation/other"

Here, the link to “http://example.org/” has the registered relation type “start” and the extension relation type “http://example.net/relation/other”.

Link: <https://example.org/>; rel="start",
      <https://example.org/index>; rel="index"

Link: <https://example.org/>; rel="start"
Link: <https://example.org/index>; rel="index"

This specification updates the Message Header registry entry for “Link” in HTTP [RFC3864] to refer to this document.

Header field: Link
Applicable protocol: http
Status: standard
Author/change controller:
    IETF  (iesg@ietf.org)
    Internet Engineering Task Force
Specification document(s):
    [this document]

This specification updates the registration procedures for the Link Relation Type registry; see Section 2.1.1.1.

IANA will direct any incoming requests regarding the registry to this document and, if defined, the processes established by the expert(s); typically, this will mean referring them to the registry Web page.

Note that the expert(s) are allowed (as per Section 2.1.1.1) to define additional fields to be collected in the registry.

This specification removes the Link Relation Application Data Registry, as it has not been used, and future use is not anticipated. IANA is instructed to remove it.

HTML motivated the original syntax of the Link header field, and many of the design decisions in this document are driven by a desire to stay compatible with it.

In HTML, the link element can be mapped to links as specified here by using the “href” attribute for the target URI, and “rel” to convey the relation type, as in the Link header field. The context of the link is the URI associated with the entire HTML document. HTML also defines several attributes on links that can be seen as target attributes, including “media”, “hreflang”, “type” and “sizes”.

Section 4.8 of HTML5 ([W3C.REC-html5-20141028]) defines modern HTML links. That document links to the Microformats Wiki as a registry; over time, the IANA registry ought to mirror its contents, and ideally eventually replace it (although that depends on the HTML community).

Surveys of existing HTML content have shown that unregistered link relation types that are not URIs are (perhaps inevitably) common. Consuming HTML implementations ought not consider such unregistered short links to be errors, but rather relation types with a local scope (i.e., their meaning is specific and perhaps private to that document).

Finally, the HTML specification gives a special meaning when the “alternate” relation types coincides with other relation types in the same link. Such links ought to be serialised in the Link header field using a single list of relation-types (e.g., rel=”alternate stylesheet”) to preserve this relationship.

Atom [RFC4287] is a link serialisation that conveys links in the atom:link element, with the “href” attribute indicating the link target and the “rel” attribute containing the relation type. The context of the link is either a feed locator or an entry ID, depending on where it appears; generally, feed-level links are obvious candidates for transmission as a Link header field.

When serialising an atom:link into a Link header field, it is necessary to convert link targets (if used) to URIs.

Atom defines extension relation types in terms of IRIs. This specification re-defines them as URIs, to simplify and reduce errors in their comparison.

Atom allows registered link relation types to be serialised as absolute URIs using a prefix, “http://www.iana.org/assignments/relation/”. This prefix is specific to the Atom serialisation.

Furthermore, link relation types are always compared in a case-sensitive fashion; therefore, registered link relation types SHOULD be converted to their registered form (usually, lowercase) when serialised in an Atom document.

Note also that while the Link header field allows multiple relations to be serialised in a single link, atom:link does not. In this case, a single link-value may map to several atom:link elements.

As with HTML, atom:link defines some attributes that are not explicitly mirrored in the Link header field syntax, but they can also be used as link-extensions to maintain fidelity.

This algorithm can be used to parse the Link header fields that a HTTP header set contains. Given a header_set of (string field_name, string field_value) pairs, assuming ASCII encoding, it returns a list of link objects.

1. Let field_values be a list containing the members of header_set whose field_name is a case-insensitive match for “link”.
2. Let links be an empty list.
3. For each field_value in field_values:
   1. Let value_links be the result of Parsing A Link Field Value (Appendix B.2) from field_value.
   2. Append each member of value_links to links.
4. Return links.

This algorithm parses zero or more comma-separated link-values from a Link header field. Given a string field_value, assuming ASCII encoding, it returns a list of link objects.

1. Let links be an empty list.
2. While field_value has content:
   1. Consume any leading OWS.
   2. If the first character is not “<”, return links.
   3. Discard the first character (“<”).
   4. Consume up to but not including the first “>” character or end of field_value and let the result be target_string.
   5. If the next character is not “>”, return links.
   6. Discard the leading “>” character.
   7. Let link_parameters, be the result of Parsing Parameters (Appendix B.3) from field_value (consuming zero or more characters of it).
   8. Let target be the result of relatively resolving (as per [RFC3986], Section 5.2) target_string. Note that any base URI carried in the payload body is NOT used.
   9. Let relations_string be the second item of the first tuple of link_parameters whose first item matches the string “rel”, or the empty string (“”) if it is not present.
   10. Split relations_string on RWS (removing it in the process) into a list of strings relation_types.
   11. Let context_string be the second item of the first tuple of link_parameters whose first item matches the string “anchor”. If it is not present, context_string is the URL of the representation carrying the Link header [RFC7231], Section 3.1.4.1, serialised as a URI. Where the URL is anonymous, context_string is null.
   12. Let context be the result of relatively resolving (as per [RFC3986], Section 5.2) context_string, unless context_string is null in which case context is null. Note that any base URI carried in the payload body is NOT used.
   13. Let target_attributes be an empty list.
   14. For each tuple (param_name, param_value) of link_parameters:
       1. If param_name matches “rel” or “anchor”, skip this tuple.
       2. If param_name matches “media”, “title”, “title*” or “type” and target_attributes already contains a tuple whose first element matches the value of param_name, skip this tuple.
       3. Append (param_name, param_value) to target_attributes.
   15. Let star_param_names be the set of param_names in the (param_name, param_value) tuples of link_parameters where the last character of param_name is an asterisk (“*”).
   16. For each star_param_name in star_param_names:
       1. Let base_param_name be star_param_name with the last character removed.
       2. If the implementation does not choose to support an internationalised form of a parameter named base_param_name for any reason (including, but not limited to, it being prohibited by the parameter’s specification), remove all tuples from link_parameters whose first member is star_param_name and skip to the next star_param_name.
       3. Remove all tuples from link_parameters whose first member is base_param_name.
       4. Change the first member of all tuples in link_parameters whose first member is star_param_name to base_param_name.
   17. For each relation_type in relation_types:
       1. Case-normalise relation_type to lowercase.
       2. Append a link object to links with the target target, relation type of relation_type, context of context, and target attributes target_attributes.
3. Return links.

This algorithm parses the parameters from a header field value. Given an ASCII string input, it returns a list of (string parameter_name, string parameter_value) tuples that it contains. input is modified to remove the parsed parameters.

1. Let parameters be an empty list.
2. While input has content:
   1. Consume any leading OWS.
   2. If the first character is not “;”, return parameters.
   3. Discard the leading “;” character.
   4. Consume any leading OWS.
   5. Consume up to but not including the first BWS, “=”, “;”, “,” character or end of input and let the result be parameter_name.
   6. Consume any leading BWS.
   7. If the next character is “=”:
      1. Discard the leading “=” character.
      2. Consume any leading BWS.
      3. If the next character is DQUOTE, let parameter_value be the result of Parsing a Quoted String (Appendix B.4) from input (consuming zero or more characters of it).
      4. Else, consume the contents up to but not including the first “;”, “,” character or end of input and let the results be parameter_value.
      5. If the last character of parameter_name is an asterisk (“*”), decode parameter_value according to [I-D.ietf-httpbis-rfc5987bis]. Continue processing input if an unrecoverable error is encountered.
   8. Else:
      1. Let parameter_value be an empty string.
   9. Case-normalise parameter_name to lowercase.
   10. Append (parameter_name, parameter_value) to parameters.
   11. Consume any leading OWS.
   12. If the next character is “,” or the end of input, stop processing input and return parameters.

This algorithm parses a quoted string, as per [RFC7230], Section 3.2.6. Given an ASCII string input, it returns an unquoted string. input is modified to remove the parsed string.

1. Let output be an empty string.
2. If the first character of input is not DQUOTE, return output.
3. Discard the first character.
4. While input has content:
   1. If the first character is a backslash (“\”):
      1. Discard the first character.
      2. If there is no more input, return output.
      3. Else, consume the first character and append it to output.
   2. Else, if the first character is DQUOTE, discard it and return output.
   3. Else, consume the first character and append it to output.
5. Return output.