Web Linking

This specification defines a way to indicate the relationships between resources on the Web (“links”) and the type of those relationships (“link relation types”).

HTML [W3C.REC-html5-20141028] and Atom [RFC4287] both have well-defined concepts of linking; this specification generalises this into a framework that encompasses linking in these formats and (potentially) elsewhere.

Furthermore, this specification formalises an HTTP header field for conveying such links, having been originally defined in Section 19.6.2.4 of [RFC2068], but removed from [RFC2616].

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14, [RFC2119], as scoped to those conformance targets.

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.CR-css3-mediaqueries-20090915]: media_query_list; and from [RFC5646]: Language-Tag..

• A link context,
• a link relation type (Section 4),
• a link target, and
• optionally, target attributes (Section 5).

A link can be viewed as a statement of the form “{link context} has a {link relation type} resource at {link target}, which has {target attributes}”.

Link contexts and link targets are both IRIs [RFC3987]. However, in the common case, the link context will also be a URI [RFC3986], because many protocols (such as HTTP) do not support dereferencing IRIs. Likewise, the link target will be sometimes be converted to a URI (see [RFC3987], Section 3.1) in places that do not support IRIs (such as the Link header field defined in Section 6).

This specification does not place restrictions on the cardinality of links; there can be multiple links to and from a particular target, and multiple links of the same or different types between a given context and target. Likewise, the relative ordering of links in any particular serialisation, or between serialisations (e.g., the Link header field and in-content links) is not specified or significant in this specification; applications that wish to consider ordering significant can do so.

Links are conveyed in link serialisations; they are the “bytes on the wire”, and can occur in various forms. For example, Atom [RFC4287] and HTML [W3C.REC-html5-20141028] both defined serialisations of links into their respective formats, and Section 6 defines how to serialise links in HTTP header fields.

This specification does not define a general syntax for links across different serialisations, nor does it mandate a specific context for any given link; it is expected that serialisations of links will specify both aspects.

Finally, links are consumed by link applications. Generally, an application will define the link relation types it uses, along with the serialisations that they might occur within. For example, the application “Web browsing” looks for the “stylesheet” link relation type in the HTML link serialisation, whereas the application “AtomPub” uses the “edit” and “edit-media” link relations.

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 resource identified by the link target is a statement of the copyright terms applying to the current link context.

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 identified resource is part of a defined protocol (in this case, a service description).

Relation types are not to be confused with media types [RFC6838]; 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 set of key/value pairs that describe the link or its target; for example, a media type hint.

This specification does not attempt to coordinate the name of target attributes, their cardinality or use; they are defined both by individual link relations and by link serialisations.

Serialisations SHOULD coordinate their target attributes to avoid conflicts in semantics or syntax. Relation types MAY define additional target attributes specific to them.

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.

• Their serialisation 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 attribute on a given link.

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

The Link header field provides a means for serialising one or more links into HTTP headers.

  Link       = #link-value
  link-value = "<" URI-Reference ">" *( OWS ";" OWS link-param )
  link-param = token BWS "=" BWS ( token / quoted-string )

Note that any link-param can be generated with values using either the token or the quoted-string syntax, and therefore recipients MUST be able to parse both forms. Individual link-params specify their syntax in terms of the value after any necessary unquoting (as per [RFC7230], Section 3.2.6).

This specification defines the link-params “rel”, “anchor”, “rev”, “hreflang”, “media”, “title”, “title*”, and “type”; see Section 6.2, Section 6.3 and Section 6.4.

In addition to the actions below, IANA should terminate the Link Relation Application Data Registry, as it has not been used, and future use is not anticipated.

The content of the Link header field is not secure, private or integrity-guaranteed, and due caution should be exercised when using it. Use of Transport Layer Security (TLS) with HTTP ([RFC2818] and [RFC2817]) is currently the only end-to-end way to provide such protection.

Link applications ought to consider the attack vectors opened by automatically following, trusting, or otherwise using links gathered from HTTP headers. In particular, Link header fields that use the “anchor” parameter to associate a link’s context with another resource should be treated with due caution.

The Link header field makes extensive use of IRIs and URIs. See [RFC3987] for security considerations relating to IRIs. See [RFC3986] for security considerations relating to URIs. See [RFC7230] for security considerations relating to HTTP headers.

Link targets may need to be converted to URIs in order to express them in serialisations that do not support IRIs. This includes the Link HTTP header field.

Similarly, the anchor parameter of the Link header field does not support IRIs, and therefore IRIs must be converted to URIs before inclusion there.

Relation types are defined as URIs, not IRIs, to aid in their comparison. It is not expected that they will be displayed to end users.

Note that registered Relation Names are required to be lower-case ASCII letters.

Header fields (Section 6) are only one serialisation of links; other specifications have defined alternative serialisations.

1. Let links be an empty list.
2. Create link_strings by splitting field_value on “,” characters, excepting “,” characters within quoted strings as per [RFC7230], Section 3.2.6, or which form part of link’s URI-Reference (i.e. between “<” and “>” characters where the “<” is immediately preceded by OWS and either a “,” character or the beginning of the field_value string).
3. For each link_string in link_strings:
   1. Let target_string be the string between the first “<” and first “>” characters in link_string. If they do not appear, or do not appear in that order, fail parsing.
   2. Let rest be the remaining characters (if any) after the first “>” character in link_string.
   3. Split rest into an array of strings parameter_strings, on the “;” character, excepting “;” characters within quoted strings as per [RFC7230], Section 3.2.6.
   4. Let link_parameters be an empty array.
   5. For each item parameter in parameter_strings:
      1. Remove OWS from the beginning and end of parameter.
      2. Skip this item if parameter matches the empty string (“”).
      3. Split parameter into param_name and param_value on the first “=” character. If parameter does not contain “=”, let param_name be parameter and param_value be null.
      4. Remove OWS from the end of param_name and the beginning of param_value.
      5. Case-normalise param_name to lowercase.
      6. If the first and last characters of param_value are both DQUOTE:
         1. Remove the first and last characters of param_value.
         2. Replace quoted-pairs within param_value with the octet following the backslash, as per [RFC7230], Section 3.2.6.
      7. If the last character of param_name is an asterisk (“*”), decode param_value according to [I-D.ietf-httpbis-rfc5987bis]. Skip this item if an unrecoverable error is encountered.
      8. Append the tuple (param_name, param_value) to link_parameters.
   6. 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.
   7. 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.
   8. Split relations_string into an array of strings relation_types, on RWS (removing all whitespace in the process).
   9. 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 identity of the representation carrying the Link header [RFC7231], Section 3.1.4.1, serialised as a URI. Where the identity is “anonymous” context_string is null.
   10. 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.
   11. Let target_attributes be an empty array.
   12. 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.
   13. 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 (“*”).
   14. 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.
   15. 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.
4. Return links.

• The initial relation type registrations were removed, since they’ve already been registered by 5988.
• The introduction has been shortened.
• The Link Relation Application Data Registry has been removed.
• Incorporated errata.
• Updated references.
• Link cardinality was clarified.
• Terminology was changed from “target IRI” and “context IRI” to “link target” and “link context” respectively.
• Made assigning a URI to registered relation types serialisation-specific.
• Removed misleading statement that the link header field is semantically equivalent to HTML and Atom links.
• More carefully defined how the Experts and IANA should interact.
• More carefully defined and used “link serialisations” and “link applications.”
• Clarified the cardinality of target attributes (generically and for “type”).
• Corrected the default link context for the Link header field, to be dependent upon the identity of the representation (as per RFC7231).
• Defined a suggested parsing algorithm for the Link header.
• The value space of target attributes and their definition has been specified.
• The ABNF has been updated to be compatible with [RFC7230]. In particular, whitespace is now explicit.
• Some parameters on the HTTP header field can now appear as a token.
• Handling of quoted strings is now defined by [RFC7230].
• The type header field parameter now needs to be quoted (as token does not allow “/”).