summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc8288.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc8288.txt')
-rw-r--r--doc/rfc/rfc8288.txt1347
1 files changed, 1347 insertions, 0 deletions
diff --git a/doc/rfc/rfc8288.txt b/doc/rfc/rfc8288.txt
new file mode 100644
index 0000000..b2a517e
--- /dev/null
+++ b/doc/rfc/rfc8288.txt
@@ -0,0 +1,1347 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) M. Nottingham
+Request for Comments: 8288 October 2017
+Obsoletes: 5988
+Category: Standards Track
+ISSN: 2070-1721
+
+
+ Web Linking
+
+Abstract
+
+ This specification defines a model for the relationships between
+ resources on the Web ("links") and the type of those relationships
+ ("link relation types").
+
+ It also defines the serialisation of such links in HTTP headers with
+ the Link header field.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 7841.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ https://www.rfc-editor.org/info/rfc8288.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Nottingham Standards Track [Page 1]
+
+RFC 8288 Web Linking October 2017
+
+
+Copyright Notice
+
+ Copyright (c) 2017 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) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+ This document may contain material from IETF Documents or IETF
+ Contributions published or made publicly available before November
+ 10, 2008. The person(s) controlling the copyright in some of this
+ material may not have granted the IETF Trust the right to allow
+ modifications of such material outside the IETF Standards Process.
+ Without obtaining an adequate license from the person(s) controlling
+ the copyright in such materials, this document may not be modified
+ outside the IETF Standards Process, and derivative works of it may
+ not be created outside the IETF Standards Process, except to format
+ it for publication as an RFC or to translate it into languages other
+ than English.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Nottingham Standards Track [Page 2]
+
+RFC 8288 Web Linking October 2017
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
+ 1.2. Conformance and Error Handling . . . . . . . . . . . . . 4
+ 2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 2.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 6
+ 2.1.1. Registered Relation Types . . . . . . . . . . . . . . 6
+ 2.1.2. Extension Relation Types . . . . . . . . . . . . . . 8
+ 2.2. Target Attributes . . . . . . . . . . . . . . . . . . . . 9
+ 3. Link Serialisation in HTTP Headers . . . . . . . . . . . . . 9
+ 3.1. Link Target . . . . . . . . . . . . . . . . . . . . . . . 10
+ 3.2. Link Context . . . . . . . . . . . . . . . . . . . . . . 10
+ 3.3. Relation Type . . . . . . . . . . . . . . . . . . . . . . 11
+ 3.4. Target Attributes . . . . . . . . . . . . . . . . . . . . 11
+ 3.4.1. Serialisation-Defined Attributes . . . . . . . . . . 11
+ 3.4.2. Extension Attributes . . . . . . . . . . . . . . . . 13
+ 3.5. Link Header Field Examples . . . . . . . . . . . . . . . 13
+ 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
+ 4.1. Link HTTP Header Field Registration . . . . . . . . . . . 14
+ 4.2. Link Relation Type Registry . . . . . . . . . . . . . . . 14
+ 4.3. Link Relation Application Data Registry . . . . . . . . . 15
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15
+ 6. Internationalisation Considerations . . . . . . . . . . . . . 16
+ 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
+ 7.1. Normative References . . . . . . . . . . . . . . . . . . 16
+ 7.2. Informative References . . . . . . . . . . . . . . . . . 17
+ Appendix A. Notes on Other Link Serialisations . . . . . . . . . 19
+ A.1. Link Serialisation in HTML . . . . . . . . . . . . . . . 19
+ A.2. Link Serialisation in Atom . . . . . . . . . . . . . . . 19
+ Appendix B. Algorithms for Parsing Link Header Fields . . . . . 20
+ B.1. Parsing a Header Set for Links . . . . . . . . . . . . . 20
+ B.2. Parsing a Link Field Value . . . . . . . . . . . . . . . 21
+ B.3. Parsing Parameters . . . . . . . . . . . . . . . . . . . 22
+ B.4. Parsing a Quoted String . . . . . . . . . . . . . . . . . 23
+ Appendix C. Changes from RFC 5988 . . . . . . . . . . . . . . . 24
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Nottingham Standards Track [Page 3]
+
+RFC 8288 Web Linking October 2017
+
+
+1. Introduction
+
+ This specification defines a model for 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; Section 2 generalises this into a
+ framework that encompasses linking in these formats and (potentially)
+ elsewhere.
+
+ Furthermore, Section 3 defines an HTTP header field for conveying
+ such links.
+
+1.1. Notational Conventions
+
+ 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) [RFC5234]
+ 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:
+
+ o URI and URI-Reference from [RFC3986],
+ o type-name and subtype-name from [RFC6838],
+ o media-query-list from [W3C.REC-css3-mediaqueries-20120619], and
+ o Language-Tag from [RFC5646].
+
+1.2. Conformance and Error Handling
+
+ The requirements regarding conformance and error handling highlighted
+ in [RFC7230], Section 2.5 apply to this document.
+
+
+
+
+
+
+
+
+
+
+
+
+Nottingham Standards Track [Page 4]
+
+RFC 8288 Web Linking October 2017
+
+
+2. Links
+
+ In this specification, a link is a typed connection between two
+ resources and is comprised of:
+
+ o a link context,
+ o a link relation type (Section 2.1),
+ o a link target, and
+ o optionally, target attributes (Section 2.2).
+
+ 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".
+
+ For example, "https://www.example.com/" has a "canonical" resource at
+ "https://example.com", which has a "type" of "text/html".
+
+ Link contexts and link targets are both Internationalized Resource
+ Identifiers (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 sometimes be converted to a URI (see [RFC3987], Section 3.1) in
+ serialisations that do not support IRIs (such as the Link header
+ field defined in Section 3).
+
+ 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 3 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 used by link applications. Generally, an
+ application will define the link relation type(s) it uses, along with
+ the serialisation(s) that they might occur within. For example, the
+
+
+
+Nottingham Standards Track [Page 5]
+
+RFC 8288 Web Linking October 2017
+
+
+ application "Web browsing" looks for the "stylesheet" link relation
+ type in the HTML link serialisation (and optionally in the Link
+ header field), whereas the application "AtomPub" uses the "edit" and
+ "edit-media" link relations in the Atom serialisation.
+
+2.1. Link Relation Types
+
+ 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.
+
+2.1.1. Registered Relation Types
+
+ Well-defined relation types can be registered as tokens for
+ convenience and/or to promote reuse by other applications, using the
+ procedure in Section 2.1.1.1.
+
+ Registered relation type names MUST conform to the reg-rel-type rule
+ (see Section 3.3) and MUST be compared character by character in a
+ case-insensitive fashion. They SHOULD be appropriate to the
+ specificity of the relation type; that is, if the semantics are
+ highly specific to a particular application, the name should reflect
+ that, so that more general names are available for less-specific use.
+
+ Registered relation types MUST NOT constrain the media type of the
+ link context and MUST NOT constrain the available representation
+ media types of the link target. However, they can specify the
+ behaviours and properties of the target resource (e.g., allowable
+
+
+
+Nottingham Standards Track [Page 6]
+
+RFC 8288 Web Linking October 2017
+
+
+ HTTP methods, and request and response media types that are required
+ be supported).
+
+ Historically, registered relation types have been identified with a
+ URI [RFC3986] by prefixing their names with an application-defined
+ base URI (e.g., see Appendix A.2). This practice is NOT RECOMMENDED,
+ because the resulting strings will not be considered equivalent to
+ the registered relation types by other applications. Applications
+ that do use such URIs internally MUST NOT use them in link
+ serialisations that do not explicitly accommodate them.
+
+2.1.1.1. Registering Link Relation Types
+
+ The "Link Relations" registry is located at
+ <https://www.iana.org/assignments/link-relations/>. Registration
+ requests can be made by following the instructions located there or
+ by sending an email to the <link-relations@ietf.org> mailing list.
+
+ Registration requests consist of at least the following information:
+
+ o *Relation Name*: The name of the relation type
+
+ o *Description*: A short English description of the type's
+ semantics. It SHOULD be stated in terms of the relationship
+ between the link context and link target.
+
+ o *Reference*: Reference to the document that specifies the link
+ relation type, preferably including a URI that can be used to
+ retrieve a copy of the document. An indication of the relevant
+ section(s) can also be included but is not required.
+
+ The expert(s) can define additional fields to be collected in the
+ registry.
+
+ General requirements for registered relation types are described in
+ Section 2.1.1.
+
+ Registrations MUST reference a freely available, stable
+ specification.
+
+ Note that relation types can be registered by third parties
+ (including the expert(s)), if the expert(s) determines that an
+ unregistered relation type is widely deployed and not likely to be
+ registered in a timely manner otherwise. Such registrations still
+ are subject to the requirements defined, including the need to
+ reference a specification.
+
+
+
+
+
+Nottingham Standards Track [Page 7]
+
+RFC 8288 Web Linking October 2017
+
+
+2.1.1.2. Registration Request Processing
+
+ Relation types are registered using the Specification Required policy
+ (see Section 4.6 of [RFC8126]), which implies review and approval by
+ a designated expert.
+
+ The goal of the registry is to reflect common use of links on the
+ Internet. Therefore, the expert(s) should be strongly biased towards
+ approving registrations, unless they are abusive, frivolous, not
+ likely to be used on the Internet, or actively harmful to the
+ Internet and/or the Web (not merely aesthetically displeasing or
+ architecturally dubious). As stated in Section 2.1.1, the expert(s)
+ can withhold registration of names that are too general for the
+ proposed application.
+
+ The expert(s) will clearly identify any issues that cause a
+ registration to be refused. Advice about the semantics of a proposed
+ link relation type can be given, but if it does not block
+ registration, this should be explicitly stated.
+
+ When a request is approved, the expert(s) will inform IANA, and the
+ registration will be processed. The IESG is the final arbiter of any
+ objection.
+
+2.1.2. Extension Relation Types
+
+ Applications that don't wish to register a relation type can use an
+ extension relation type, which is a URI [RFC3986] that uniquely
+ identifies the relation type. Although the URI can point to a
+ resource that contains a definition of the semantics of the relation
+ type, clients SHOULD NOT automatically access that resource to avoid
+ overburdening its server.
+
+ The URI used for an extension relation type SHOULD be under the
+ control of the person or party defining it or be delegated to them.
+
+ When extension relation types are compared, they MUST be compared as
+ strings (after converting to URIs if serialised in a different
+ format) in a case-insensitive fashion, character by character.
+ Because of this, all-lowercase URIs SHOULD be used for extension
+ relations.
+
+ Note that while extension relation types are required to be URIs, a
+ serialisation of links can specify that they are expressed in another
+ form, as long as they can be converted to URIs.
+
+
+
+
+
+
+Nottingham Standards Track [Page 8]
+
+RFC 8288 Web Linking October 2017
+
+
+2.2. Target Attributes
+
+ 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 serialisations and MUST be compared in a case-
+ insensitive fashion.
+
+ Target attribute definitions SHOULD specify:
+
+ o The serialisation of their values into Unicode or a subset
+ thereof, to maximise their chances of portability across link
+ serialisations.
+ o 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.
+
+3. Link Serialisation in HTTP Headers
+
+ The Link header field provides a means for serialising one or more
+ links into HTTP headers.
+
+ The ABNF for the field value is:
+
+ 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; therefore, recipients MUST be
+ able to parse both forms. In other words, the following parameters
+ are equivalent:
+
+ x=y
+ x="y"
+
+
+
+Nottingham Standards Track [Page 9]
+
+RFC 8288 Web Linking October 2017
+
+
+ Previous definitions of the Link header did not equate the token and
+ quoted-string forms explicitly; the title parameter was always
+ quoted, and the hreflang parameter was always a token. Senders
+ wishing to maximize interoperability will send them in those 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 establishes the link-params "rel", "anchor", and
+ "rev" (which are part of the general link model), as well as
+ "hreflang", "media", "title", "title*", and "type" (which are target
+ attributes defined by the serialisation).
+
+3.1. Link Target
+
+ 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.
+
+3.2. Link Context
+
+ 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, and is 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.
+
+ The ABNF for the "anchor" parameter's value is:
+
+ 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.
+
+
+
+Nottingham Standards Track [Page 10]
+
+RFC 8288 Web Linking October 2017
+
+
+3.3. Relation Type
+
+ 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.
+
+ The ABNF for the rel and rev parameters' values is:
+
+ relation-type *( 1*SP relation-type )
+
+ where:
+
+ 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 a semicolon (";") or comma (",") (as
+ these characters are used as delimiters in the header field itself).
+
+3.4. Target Attributes
+
+ 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).
+
+3.4.1. Serialisation-Defined Attributes
+
+ The "hreflang", "media", "title", "title*", and "type" link-params
+ can be translated to serialisation-defined target attributes for the
+ link.
+
+
+
+
+
+Nottingham Standards Track [Page 11]
+
+RFC 8288 Web Linking October 2017
+
+
+ The "hreflang" attribute, when present, is a hint indicating what the
+ language of the result of dereferencing the link should be. Note
+ that this is only a hint; for example, it does not override the
+ Content-Language header field of a HTTP response obtained by actually
+ following the link. Multiple hreflang attributes on a single link-
+ value indicate that multiple languages are available from the
+ indicated resource.
+
+ The ABNF for the hreflang parameter's value is:
+
+ Language-Tag
+
+ The "media" attribute, when present, is used to indicate intended
+ destination medium or media for style information (see
+ [W3C.REC-html5-20141028], Section 4.2.4). Its value MUST be quoted
+ if it contains a semicolon (";") or comma (","). There MUST NOT be
+ more than one media attribute in a link-value; occurrences after the
+ first MUST be ignored by parsers.
+
+ The ABNF for the media parameter's value is:
+
+ media-query-list
+
+ The "title" attribute, when present, is used to label the destination
+ of a link such that it can be used as a human-readable identifier
+ (e.g., a menu entry) in the language indicated by the Content-
+ Language header field (if present). The title attribute MUST NOT
+ appear more than once in a given link; occurrences after the first
+ MUST be ignored by parsers.
+
+ The "title*" link-param can be used to encode this attribute in a
+ different character set and/or contain language information as per
+ [RFC8187]. The title* link-param MUST NOT appear more than once in a
+ given link-value; occurrences after the first MUST be ignored by
+ parsers. If the attribute does not contain language information, its
+ language is indicated by the Content-Language header field (when
+ present).
+
+ If both the title and title* link-params appear in a link,
+ applications SHOULD use the title* link-param's value for the title
+ attribute.
+
+ The "type" attribute, when present, is a hint indicating what the
+ media type of the result of dereferencing the link should be. Note
+ that this is only a hint; for example, it does not override the
+ Content-Type header field of a HTTP response obtained by actually
+
+
+
+
+
+Nottingham Standards Track [Page 12]
+
+RFC 8288 Web Linking October 2017
+
+
+ following the link. The type attribute MUST NOT appear more than
+ once in a given link-value; occurrences after the first MUST be
+ ignored by parsers.
+
+ The ABNF for the type parameter's value is:
+
+ type-name "/" subtype-name ; see Section 4.2 of [RFC6838]
+
+3.4.2. Extension Attributes
+
+ Other link-params are link-extensions and are to be considered as
+ target attributes.
+
+ Such target attributes MAY be defined to use the encoding in
+ [RFC8187] (e.g., "example" and "example*"). When both forms are
+ present, they SHOULD be considered to be the same target attribute;
+ applications SHOULD use the value of the name ending in "*" (after
+ [RFC8187] decoding) but MAY fall back to the other value if there is
+ an error in decoding it, or if they do not support decoding.
+
+3.5. Link Header Field Examples
+
+ For example:
+
+ 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".
+
+ This link:
+
+ 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 the encoding from RFC 8187 to
+ encode both non-ASCII characters and language information.
+
+
+
+Nottingham Standards Track [Page 13]
+
+RFC 8288 Web Linking October 2017
+
+
+ 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, both use the German
+ language ("de"), and the second link contains the Unicode code point
+ U+00E4 ("LATIN SMALL LETTER A WITH DIAERESIS").
+
+ Note that link-values can convey multiple links between the same link
+ target and link context; for example:
+
+ 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".
+
+ Finally, this header field:
+
+ Link: <https://example.org/>; rel="start",
+ <https://example.org/index>; rel="index"
+
+ is equivalent to these:
+
+ Link: <https://example.org/>; rel="start"
+ Link: <https://example.org/index>; rel="index"
+
+4. IANA Considerations
+
+4.1. Link HTTP Header Field Registration
+
+ This specification updates the "Message Headers" registry entry for
+ "Link" in HTTP [RFC3864] to refer to this document.
+
+ Header Field Name: Link
+ Protocol: http
+ Status: standard
+ Reference: RFC 8288
+
+4.2. Link Relation Type Registry
+
+ This specification updates the registration procedures for the "Link
+ Relation Types" registry; see Section 2.1.1.1. Also, all references
+ to RFC 5988 in that registry have been replaced with references to
+ this document.
+
+
+
+
+Nottingham Standards Track [Page 14]
+
+RFC 8288 Web Linking October 2017
+
+
+ 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) is allowed (as per Section 2.1.1.1) to define
+ additional fields to be collected in the registry.
+
+4.3. Link Relation Application Data Registry
+
+ Per this specification, IANA has removed the "Link Relation
+ Application Data" registry, as it has not been used, and future use
+ is not anticipated.
+
+5. Security Considerations
+
+ The content of the Link header field is not secure, private, or
+ integrity-guaranteed. Use of Transport Layer Security (TLS) with
+ HTTP [RFC2818] is currently the only end-to-end way to provide these
+ properties.
+
+ Link applications ought to consider the attack vectors opened by
+ automatically following, trusting, or otherwise using links gathered
+ from HTTP header fields.
+
+ For example, Link header fields that use the "anchor" parameter to
+ associate a link's context with another resource cannot be trusted
+ since they are effectively assertions by a third party that could be
+ incorrect or malicious. Applications can mitigate this risk by
+ specifying that such links should be discarded unless some
+ relationship between the resources is established (e.g., they share
+ the same authority).
+
+ Dereferencing links has a number of risks, depending on the
+ application in use. For example, the Referer header [RFC7231] can
+ expose information about the application's state (including private
+ information) in its value. Likewise, cookies [RFC6265] are another
+ mechanism that, if used, can become an attack vector. Applications
+ can mitigate these risks by carefully specifying how such mechanisms
+ should operate.
+
+ The Link header field makes extensive use of IRIs and URIs. See
+ [RFC3987], Section 8 for security considerations relating to IRIs.
+ See [RFC3986], Section 7 for security considerations relating to
+ URIs. See [RFC7230], Section 9 for security considerations relating
+ to HTTP header fields.
+
+
+
+
+
+
+Nottingham Standards Track [Page 15]
+
+RFC 8288 Web Linking October 2017
+
+
+6. Internationalisation Considerations
+
+ 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; 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 lowercase
+ ASCII letters.
+
+7. References
+
+7.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <https://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
+ Procedures for Message Header Fields", BCP 90, RFC 3864,
+ DOI 10.17487/RFC3864, September 2004,
+ <https://www.rfc-editor.org/info/rfc3864>.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+ Resource Identifier (URI): Generic Syntax", STD 66,
+ RFC 3986, DOI 10.17487/RFC3986, January 2005,
+ <https://www.rfc-editor.org/info/rfc3986>.
+
+ [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
+ Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987,
+ January 2005, <https://www.rfc-editor.org/info/rfc3987>.
+
+ [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234,
+ DOI 10.17487/RFC5234, January 2008,
+ <https://www.rfc-editor.org/info/rfc5234>.
+
+ [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
+ Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
+ September 2009, <https://www.rfc-editor.org/info/rfc5646>.
+
+
+
+Nottingham Standards Track [Page 16]
+
+RFC 8288 Web Linking October 2017
+
+
+ [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
+ Specifications and Registration Procedures", BCP 13,
+ RFC 6838, DOI 10.17487/RFC6838, January 2013,
+ <https://www.rfc-editor.org/info/rfc6838>.
+
+ [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
+ Protocol (HTTP/1.1): Message Syntax and Routing",
+ RFC 7230, DOI 10.17487/RFC7230, June 2014,
+ <https://www.rfc-editor.org/info/rfc7230>.
+
+ [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
+ Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
+ DOI 10.17487/RFC7231, June 2014,
+ <https://www.rfc-editor.org/info/rfc7231>.
+
+ [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
+ Writing an IANA Considerations Section in RFCs", BCP 26,
+ RFC 8126, DOI 10.17487/RFC8126, June 2017,
+ <https://www.rfc-editor.org/info/rfc8126>.
+
+ [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+ 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+ May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+ [RFC8187] Reschke, J., "Indicating Character Encoding and Language
+ for HTTP Header Field Parameters", RFC 8187,
+ DOI 10.17487/RFC8187, September 2017,
+ <https://www.rfc-editor.org/info/rfc8187>.
+
+ [W3C.REC-css3-mediaqueries-20120619]
+ Rivoal, F., "Media Queries", W3C Recommendation
+ REC-css3-mediaqueries-20120619, June 2012,
+ <http://www.w3.org/TR/2012/
+ REC-css3-mediaqueries-20120619>.
+
+7.2. Informative References
+
+ [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part Two: Media Types", RFC 2046,
+ DOI 10.17487/RFC2046, November 1996,
+ <https://www.rfc-editor.org/info/rfc2046>.
+
+ [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
+ DOI 10.17487/RFC2818, May 2000,
+ <https://www.rfc-editor.org/info/rfc2818>.
+
+
+
+
+
+
+Nottingham Standards Track [Page 17]
+
+RFC 8288 Web Linking October 2017
+
+
+ [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
+ Syndication Format", RFC 4287, DOI 10.17487/RFC4287,
+ December 2005, <https://www.rfc-editor.org/info/rfc4287>.
+
+ [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
+ DOI 10.17487/RFC6265, April 2011,
+ <https://www.rfc-editor.org/info/rfc6265>.
+
+ [W3C.REC-html5-20141028]
+ Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
+ Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", W3C
+ Recommendation REC-html5-20141028, October 2014,
+ <http://www.w3.org/TR/2014/REC-html5-20141028>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Nottingham Standards Track [Page 18]
+
+RFC 8288 Web Linking October 2017
+
+
+Appendix A. Notes on Other Link Serialisations
+
+ Header fields (Section 3) are only one serialisation of links; other
+ specifications have defined alternative serialisations.
+
+A.1. Link Serialisation in HTML
+
+ 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 coincide 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.
+
+A.2. Link Serialisation in Atom
+
+ 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.
+
+
+
+Nottingham Standards Track [Page 19]
+
+RFC 8288 Web Linking October 2017
+
+
+ Atom defines extension relation types in terms of IRIs. This
+ specification redefines 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.
+
+Appendix B. Algorithms for Parsing Link Header Fields
+
+ This appendix outlines a set of non-normative algorithms: for parsing
+ the Link header(s) out of a header set, for parsing a Link header
+ field value, and algorithms for parsing generic parts of the field
+ value.
+
+ These algorithms are more permissive than the ABNF defining the
+ syntax might suggest; the error handling embodied in them is a
+ reasonable approach, but not one that is required. As such they are
+ advisory only, and in cases where there is disagreement, the correct
+ behaviour is defined by the body of this specification.
+
+B.1. Parsing a Header Set for Links
+
+ 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.
+
+
+
+
+
+
+Nottingham Standards Track [Page 20]
+
+RFC 8288 Web Linking October 2017
+
+
+ 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.
+
+B.2. Parsing a Link Field Value
+
+ 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_uri 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 string 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_uri 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.
+
+
+
+
+
+
+Nottingham Standards Track [Page 21]
+
+RFC 8288 Web Linking October 2017
+
+
+ 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_uri, relation type of relation_type, context of
+ context_uri, and target attributes target_attributes.
+
+ 3. Return links.
+
+B.3. Parsing Parameters
+
+ This algorithm parses the parameters from a header field value.
+ Given input, an ASCII string, 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.
+
+
+
+Nottingham Standards Track [Page 22]
+
+RFC 8288 Web Linking October 2017
+
+
+ 5. Consume up to but not including the first BWS, "=", ";", or
+ "," character, or up to the 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 ";" or "," character, or up to the 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 [RFC8187].
+ 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.
+
+B.4. Parsing a Quoted String
+
+ This algorithm parses a quoted string, as per [RFC7230],
+ Section 3.2.6. Given input, an ASCII string, 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.
+
+
+
+Nottingham Standards Track [Page 23]
+
+RFC 8288 Web Linking October 2017
+
+
+Appendix C. Changes from RFC 5988
+
+ This specification has the following differences from its
+ predecessor, RFC 5988:
+
+ o The initial relation type registrations were removed, since
+ they've already been registered by RFC 5988.
+ o The introduction has been shortened.
+ o The "Link Relation Application Data" registry has been removed.
+ o Incorporated errata.
+ o Updated references.
+ o Link cardinality was clarified.
+ o Terminology was changed from "target IRI" and "context IRI" to
+ "link target" and "link context", respectively.
+ o Made assigning a URI to registered relation types serialisation
+ specific.
+ o Removed misleading statement that the Link header field is
+ semantically equivalent to HTML and Atom links.
+ o More carefully defined and used "link serialisations" and "link
+ applications."
+ o Clarified the cardinality of target attributes (generically and
+ for "type").
+ o Corrected the default link context for the Link header field, to
+ be dependent upon the identity of the representation (as per
+ RFC 7231).
+ o Defined a suggested parsing algorithm for the Link header.
+ o The value space of target attributes and their definition has been
+ specified.
+ o The ABNF has been updated to be compatible with [RFC7230]. In
+ particular, whitespace is now explicit.
+ o Some parameters on the HTTP header field can now appear as a
+ token.
+ o Parameters on the HTTP header can now be valueless.
+ o Handling of quoted strings is now defined by [RFC7230].
+ o The "type" header field parameter now needs to be quoted (as
+ "token" does not allow "/").
+
+Author's Address
+
+ Mark Nottingham
+
+ Email: mnot@mnot.net
+ URI: https://www.mnot.net/
+
+
+
+
+
+
+
+
+Nottingham Standards Track [Page 24]
+