idnits 2.17.00 (12 Aug 2021) /tmp/idnits63279/draft-nottingham-rfc5988bis-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC5988, but the abstract doesn't seem to directly say this. It does mention RFC5988 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 18, 2017) is 1767 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: draft-ietf-httpbis-rfc5987bis has been published as RFC 8187 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft July 18, 2017 4 Obsoletes: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: January 19, 2018 8 Web Linking 9 draft-nottingham-rfc5988bis-07 11 Abstract 13 This specification defines a model for the relationships between 14 resources on the Web ("links") and the type of those relationships 15 ("link relation types"). 17 It also defines the serialisation of such links in HTTP headers with 18 the Link header field. 20 Note to Readers 22 This is a work-in-progress to revise RFC5988. 24 The issues list can be found at https://github.com/mnot/I-D/labels/ 25 rfc5988bis . 27 The most recent (often, unpublished) draft is at 28 https://mnot.github.io/I-D/rfc5988bis/ . 30 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 31 pages/rfc5988bis . 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on January 19, 2018. 50 Copyright Notice 52 Copyright (c) 2017 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 This document may contain material from IETF Documents or IETF 66 Contributions published or made publicly available before November 67 10, 2008. The person(s) controlling the copyright in some of this 68 material may not have granted the IETF Trust the right to allow 69 modifications of such material outside the IETF Standards Process. 70 Without obtaining an adequate license from the person(s) controlling 71 the copyright in such materials, this document may not be modified 72 outside the IETF Standards Process, and derivative works of it may 73 not be created outside the IETF Standards Process, except to format 74 it for publication as an RFC or to translate it into languages other 75 than English. 77 Table of Contents 79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 80 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 81 1.2. Conformance and Error Handling . . . . . . . . . . . . . 4 82 2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 83 2.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 5 84 2.1.1. Registered Relation Types . . . . . . . . . . . . . . 5 85 2.1.2. Extension Relation Types . . . . . . . . . . . . . . 7 86 2.2. Target Attributes . . . . . . . . . . . . . . . . . . . . 8 87 3. Link Serialisation in HTTP Headers . . . . . . . . . . . . . 8 88 3.1. Link Target . . . . . . . . . . . . . . . . . . . . . . . 9 89 3.2. Link Context . . . . . . . . . . . . . . . . . . . . . . 9 90 3.3. Relation Type . . . . . . . . . . . . . . . . . . . . . . 10 91 3.4. Target Attributes . . . . . . . . . . . . . . . . . . . . 10 92 3.4.1. Serialisation-Defined Attributes . . . . . . . . . . 10 93 3.4.2. Extension Attributes . . . . . . . . . . . . . . . . 12 94 3.5. Link Header Field Examples . . . . . . . . . . . . . . . 12 95 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 96 4.1. Link HTTP Header Field Registration . . . . . . . . . . . 13 97 4.2. Link Relation Type Registry . . . . . . . . . . . . . . . 13 98 4.3. Link Relation Application Data Registry . . . . . . . . . 14 99 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 100 6. Internationalisation Considerations . . . . . . . . . . . . . 14 101 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 102 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 103 7.2. Informative References . . . . . . . . . . . . . . . . . 16 104 Appendix A. Notes on Other Link Serialisations . . . . . . . . . 17 105 A.1. Link Serialisation in HTML . . . . . . . . . . . . . . . 17 106 A.2. Link Serialisation in Atom . . . . . . . . . . . . . . . 17 107 Appendix B. Algorithms for Parsing Link Header Fields . . . . . 18 108 B.1. Parsing a Header Set for Links . . . . . . . . . . . . . 18 109 B.2. Parsing a Link Field Value . . . . . . . . . . . . . . . 19 110 B.3. Parsing Parameters . . . . . . . . . . . . . . . . . . . 21 111 B.4. Parsing a Quoted String . . . . . . . . . . . . . . . . . 22 112 Appendix C. Changes from RFC5988 . . . . . . . . . . . . . . . . 23 113 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24 115 1. Introduction 117 This specification defines a model for the relationships between 118 resources on the Web ("links") and the type of those relationships 119 ("link relation types"). 121 HTML [W3C.REC-html5-20141028] and Atom [RFC4287] both have well- 122 defined concepts of linking; Section 2 generalises this into a 123 framework that encompasses linking in these formats and (potentially) 124 elsewhere. 126 Furthermore, Section 3 defines an HTTP header field for conveying 127 such links. 129 1.1. Notational Conventions 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 133 "OPTIONAL" in this document are to be interpreted as described in BCP 134 14 [RFC2119],[RFC8174] when, and only when, they appear in all 135 capitals, as shown here. 137 This document uses the Augmented Backus-Naur Form (ABNF) notation of 138 [RFC7230], including the #rule, and explicitly includes the following 139 rules from it: quoted-string, token, SP (space), BWS (bad 140 whitespace), OWS (optional whitespace), RWS (required whitespace) 141 LOALPHA, DIGIT. 143 Additionally, the following rules are included from [RFC3986]: URI 144 and URI-Reference; from [RFC6838]: type-name and subtype-name; from 146 [W3C.REC-css3-mediaqueries-20120619]: media-query-list; and from 147 [RFC5646]: Language-Tag. 149 1.2. Conformance and Error Handling 151 The requirements regarding conformance and error handling highlighted 152 in [RFC7230], Section 2.5 apply to this document. 154 2. Links 156 In this specification, a link is a typed connection between two 157 resources, and is comprised of: 159 o A _link context_, 161 o a _link relation type_ (Section 2.1), 163 o a _link target_, and 165 o optionally, _target attributes_ (Section 2.2). 167 A link can be viewed as a statement of the form "_link context_ has a 168 _link relation type_ resource at _link target_, which has _target 169 attributes_". 171 Link contexts and link targets are both IRIs [RFC3987]. However, in 172 the common case, the link context will also be a URI [RFC3986], 173 because many protocols (such as HTTP) do not support dereferencing 174 IRIs. Likewise, the link target will be sometimes be converted to a 175 URI (see [RFC3987], Section 3.1) in serialisations that do not 176 support IRIs (such as the Link header field defined in Section 3). 178 This specification does not place restrictions on the cardinality of 179 links; there can be multiple links to and from a particular target, 180 and multiple links of the same or different types between a given 181 context and target. Likewise, the relative ordering of links in any 182 particular serialisation, or between serialisations (e.g., the Link 183 header field and in-content links) is not specified or significant in 184 this specification; applications that wish to consider ordering 185 significant can do so. 187 Links are conveyed in _link serialisations_; they are the "bytes on 188 the wire", and can occur in various forms. For example, Atom 189 [RFC4287] and HTML [W3C.REC-html5-20141028] both defined 190 serialisations of links into their respective formats, and Section 3 191 defines how to serialise links in HTTP header fields. 193 This specification does not define a general syntax for links across 194 different serialisations, nor does it mandate a specific context for 195 any given link; it is expected that serialisations of links will 196 specify both aspects. 198 Finally, links are used by _link applications_. Generally, an 199 application will define the link relation type(s) it uses, along with 200 the serialisation(s) that they might occur within. For example, the 201 application "Web browsing" looks for the "stylesheet" link relation 202 type in the HTML link serialisation (and optionally in the Link 203 header field), whereas the application "AtomPub" uses the "edit" and 204 "edit-media" link relations in the Atom serialisation. 206 2.1. Link Relation Types 208 In the simplest case, a link relation type identifies the semantics 209 of a link. For example, a link with the relation type "copyright" 210 indicates that the current link context has a copyright resource at 211 the link target. 213 Link relation types can also be used to indicate that the target 214 resource has particular attributes, or exhibits particular 215 behaviours; for example, a "service" link implies that the link 216 target can be used as part of a defined protocol (in this case, a 217 service description). 219 Relation types are not to be confused with media types [RFC2046]; 220 they do not identify the format of the representation that results 221 when the link is dereferenced. Rather, they only describe how the 222 current context is related to another resource. 224 Relation types SHOULD NOT infer any additional semantics based upon 225 the presence or absence of another link relation type, or its own 226 cardinality of occurrence. An exception to this is the combination 227 of the "alternate" and "stylesheet" registered relation types, which 228 has special meaning in HTML for historical reasons. 230 There are two kinds of relation types: registered and extension. 232 2.1.1. Registered Relation Types 234 Well-defined relation types can be registered as tokens for 235 convenience and/or to promote reuse by other applications, using the 236 procedure in Section 2.1.1.1. 238 Registered relation type names MUST conform to the reg-rel-type rule 239 (see Section 3.3), and MUST be compared character-by-character in a 240 case-insensitive fashion. They SHOULD be appropriate to the 241 specificity of the relation type; i.e., if the semantics are highly 242 specific to a particular application, the name should reflect that, 243 so that more general names are available for less specific use. 245 Registered relation types MUST NOT constrain the media type of the 246 link context, and MUST NOT constrain the available representation 247 media types of the link target. However, they can specify the 248 behaviours and properties of the target resource (e.g., allowable 249 HTTP methods, request and response media types that are required be 250 supported). 252 Historically, registered relation types have been identified with a 253 URI [RFC3986] by prefixing their names with an application-defined 254 base URI (e.g., see Appendix A.2). This practice is NOT RECOMMENDED, 255 because the resulting strings will not be considered equivalent to 256 the registered relation types by other applications. Applications 257 that do use such URIs internally MUST NOT use them in link 258 serialisations that do not explicitly accommodate them. 260 2.1.1.1. Registering Link Relation Types 262 The link relations registry is located at 263 https://www.iana.org/assignments/link-relations/ . Registration 264 requests can be made by following the instructions located there, or 265 by sending an e-mail to the "link-relations@ietf.org" mailing list. 267 Registration requests consist of at least the following information: 269 o *Relation Name*: The name of the relation type 271 o *Description*: A short English description of the type's 272 semantics. It SHOULD be stated in terms of the relationship 273 between the link context and link target. 275 o *Reference*: Reference to the document that specifies the link 276 relation type, preferably including a URI that can be used to 277 retrieve a copy of the document. An indication of the relevant 278 section(s) can also be included, but is not required. 280 The expert(s) MAY define additional fields to be collected in the 281 registry. 283 General requirements for registered relation types are described in 284 Section 2.1.1. 286 Registrations MUST reference a freely available, stable 287 specification. 289 Note that relation types can be registered by third parties 290 (including the expert(s)), if the expert(s) determine that an 291 unregistered relation type is widely deployed and not likely to be 292 registered in a timely manner otherwise. 294 2.1.1.2. Registration Request Processing 296 Relation types are registered using the Specification Required policy 297 (see Section 4.6 of [RFC8126]), which implies review and approval by 298 a designated expert. 300 The goal of the registry is to reflect common use of links on the 301 Internet. Therefore, the expert(s) SHOULD be strongly biased towards 302 approving registrations, unless they are abusive, frivolous, not 303 likely to be used on the Internet, or actively harmful to the 304 Internet and/or the Web (not merely aesthetically displeasing, or 305 architecturally dubious). As stated in Section 2.1.1, the expert(s) 306 MAY withhold registration of names that are too general for the 307 proposed application. 309 The expert(s) MUST clearly identify any issues which cause a 310 registration to be refused. Advice about the semantics of a proposed 311 link relation type can be given, but if it does not block 312 registration, this SHOULD be explicitly stated. 314 When a request is approved, the expert(s) will inform IANA, and the 315 registration will be processed. The IESG is the final arbiter of any 316 objection. 318 2.1.2. Extension Relation Types 320 Applications that don't wish to register a relation type can use an 321 extension relation type, which is a URI [RFC3986] that uniquely 322 identifies the relation type. Although the URI can point to a 323 resource that contains a definition of the semantics of the relation 324 type, clients SHOULD NOT automatically access that resource to avoid 325 overburdening its server. 327 The URI used for an extension relation type SHOULD be under the 328 control of the person or party defining it, or be delegated to them. 330 When extension relation types are compared, they MUST be compared as 331 strings (after converting to URIs if serialised in a different 332 format) in a case-insensitive fashion, character-by-character. 333 Because of this, all-lowercase URIs SHOULD be used for extension 334 relations. 336 Note that while extension relation types are required to be URIs, a 337 serialisation of links can specify that they are expressed in another 338 form, as long as they can be converted to URIs. 340 2.2. Target Attributes 342 _Target attributes_ are a list of key/value pairs that describe the 343 link or its target; for example, a media type hint. 345 They can be defined both by individual link relation types and by 346 link serialisations. 348 This specification does not attempt to coordinate the name of target 349 attributes, their cardinality or use. Those creating and maintaining 350 serialisations SHOULD coordinate their target attributes to avoid 351 conflicts in semantics or syntax, and MAY define their own registries 352 of target attributes. 354 The names of target attributes SHOULD conform to the token rule, but 355 SHOULD NOT include any of the characters "%", "'" or "*", for 356 portability across serializations, and MUST be compared in a case- 357 insensitive fashion. 359 Target attribute definitions SHOULD specify: 361 o The serialisation of their values into Unicode or a subset 362 thereof, to maximise their chances of portability across link 363 serialisations. 365 o The semantics and error handling of multiple occurrences of the 366 target attribute on a given link. 368 This specification does define target attributes for use in the Link 369 HTTP header field in Section 3.4. 371 3. Link Serialisation in HTTP Headers 373 The Link header field provides a means for serialising one or more 374 links into HTTP headers. 376 The ABNF for the field value is: 378 Link = #link-value 379 link-value = "<" URI-Reference ">" *( OWS ";" OWS link-param ) 380 link-param = token BWS [ "=" BWS ( token / quoted-string ) ] 382 Note that any "link-param" can be generated with values using either 383 the "token" or the "quoted-string" syntax, and therefore recipients 384 MUST be able to parse both forms. In other words, the following 385 parameters are equivalent: 387 x=y 388 x="y" 390 Individual "link-param"s specify their syntax in terms of the value 391 after any necessary unquoting (as per [RFC7230], Section 3.2.6). 393 This specification defines the link-params "rel", "anchor", "rev", 394 "hreflang", "media", "title", "title*", and "type"; see Section 3.2, 395 Section 3.3 and Section 3.4. 397 3.1. Link Target 399 Each link-value conveys one target IRI as a URI-Reference (after 400 conversion to one, if necessary; see [RFC3987], Section 3.1) inside 401 angle brackets ("<>"). If the URI-Reference is relative, parsers 402 MUST resolve it as per [RFC3986], Section 5. Note that any base IRI 403 appearing in the message's content is not applied. 405 3.2. Link Context 407 By default, the context of a link conveyed in the Link header field 408 is the URL of the representation it is associated with, as defined in 409 [RFC7231], Section 3.1.4.1, serialised as a URI. 411 When present, the anchor parameter overrides this with another URI, 412 such as a fragment of this resource, or a third resource (i.e., when 413 the anchor value is an absolute URI). If the anchor parameter's 414 value is a relative URI, parsers MUST resolve it as per [RFC3986], 415 Section 5. Note that any base URI from the body's content is not 416 applied. 418 The ABNF for the "anchor" parameter's value is: 420 URI-Reference ; Section 4.1 of {{RFC3986}} 422 Link application can choose to ignore links with an anchor parameter. 423 For example, the application in use might not allow the link context 424 to be assigned to a different resource. In such cases, the entire 425 link is to be ignored; link applications MUST NOT process the link 426 without applying the anchor. 428 Note that depending on HTTP status code and response headers, the 429 link context might be "anonymous" (i.e., no link context is 430 available). For example, this is the case on a 404 response to a GET 431 request. 433 3.3. Relation Type 435 The relation type of a link conveyed in the Link header field is 436 conveyed in the "rel" parameter's value. The "rel" parameter MUST 437 NOT appear more than once in a given link-value; occurrences after 438 the first MUST be ignored by parsers. 440 The "rev" parameter has been used in the past to indicate that the 441 semantics of the relationship are in the reverse direction. That is, 442 a link from A to B with REL="X" expresses the same relationship as a 443 link from B to A with REV="X". "rev" is deprecated by this 444 specification because it often confuses authors and readers; in most 445 cases, using a separate relation type is preferable. 447 The ABNF for the "rel" and "rev" parameters' values is: 449 relation-type *( 1*SP relation-type ) 451 where: 453 relation-type = reg-rel-type / ext-rel-type 454 reg-rel-type = LOALPHA *( LOALPHA / DIGIT / "." / "-" ) 455 ext-rel-type = URI ; Section 3 of {{RFC3986}} 457 Note that extension relation types are REQUIRED to be absolute URIs 458 in Link header fields, and MUST be quoted when they contain 459 characters not allowed in tokens, such as semicolon (";") or comma 460 (",") (as these characters are used as delimiters in the header field 461 itself). 463 3.4. Target Attributes 465 The Link header field defines several target attributes specific to 466 this serialisation, and also allows extension target attributes. 467 Target attributes are serialised in the Link header field as 468 parameters (see [RFC7231], Section 3.1.1.1 for the definition of 469 their syntax). 471 3.4.1. Serialisation-Defined Attributes 473 The "hreflang", "media", "title", "title*", and "type" link-params 474 can be translated to serialisation-defined target attributes for the 475 link. 477 The "hreflang" attribute, when present, is a hint indicating what the 478 language of the result of dereferencing the link should be. Note 479 that this is only a hint; for example, it does not override the 480 Content-Language header field of a HTTP response obtained by actually 481 following the link. Multiple "hreflang" attributes on a single link- 482 value indicate that multiple languages are available from the 483 indicated resource. 485 The ABNF for the "hreflang" parameter's value is: 487 Language-Tag 489 The "media" attribute, when present, is used to indicate intended 490 destination medium or media for style information (see 491 [W3C.REC-html5-20141028], Section 4.2.4). Its value MUST be quoted 492 if it contains a semicolon (";") or comma (","). There MUST NOT be 493 more than one "media" attribute in a link-value; occurrences after 494 the first MUST be ignored by parsers. 496 The ABNF for the "media" parameter's value is: 498 media-query-list 500 The "title" attribute, when present, is used to label the destination 501 of a link such that it can be used as a human-readable identifier 502 (e.g., a menu entry) in the language indicated by the Content- 503 Language header field (if present). The "title" attribute MUST NOT 504 appear more than once in a given link; occurrences after the first 505 MUST be ignored by parsers. 507 The "title*" link-param can be used to encode this attribute in a 508 different character set, and/or contain language information as per 509 [I-D.ietf-httpbis-rfc5987bis]. The "title*" link-param MUST NOT 510 appear more than once in a given link-value; occurrences after the 511 first MUST be ignored by parsers. If the attribute does not contain 512 language information, its language is indicated by the Content- 513 Language header field (when present). 515 If both the "title" and "title*" link-param appear in a link, 516 applications SHOULD use the "title*" link-param's value for the 517 "title" attribute. 519 The "type" attribute, when present, is a hint indicating what the 520 media type of the result of dereferencing the link should be. Note 521 that this is only a hint; for example, it does not override the 522 Content-Type header field of a HTTP response obtained by actually 523 following the link. The "type" attribute MUST NOT appear more than 524 once in a given link-value; occurrences after the first MUST be 525 ignored by parsers. 527 The ABNF for the "type" parameter's value is: 529 type-name "/" subtype-name ; see {{RFC6838}}, Section 4.2 531 3.4.2. Extension Attributes 533 Other link-params are link-extensions, and are to be considered as 534 target attributes. 536 Such target attributes MAY be defined to use the encoding in 537 [I-D.ietf-httpbis-rfc5987bis] (e.g., "example" and "example*"). When 538 both forms are present, they SHOULD be considered to be the same 539 target attribute; applications SHOULD use the value of the name 540 ending in "*" (after [I-D.ietf-httpbis-rfc5987bis] decoding), but MAY 541 fall back to the other value if there is an error in decoding it, or 542 if they do not support decoding. 544 3.5. Link Header Field Examples 546 For example: 548 Link: ; rel="previous"; 549 title="previous chapter" 551 indicates that "chapter2" is previous to this resource in a logical 552 navigation path. 554 Similarly, 556 Link: ; rel="http://example.net/foo" 558 indicates that the root resource ("/") is related to this resource 559 with the extension relation type "http://example.net/foo". 561 This link: 563 Link: ; rel="copyright"; anchor="#foo" 565 indicates that the linked copyright terms only apply to the portion 566 of the document indicated by the (media type-specific) fragment 567 identifier "foo". 569 The example below shows an instance of the Link header field encoding 570 multiple links, and also the use of RFC 5987 encoding to encode both 571 non-ASCII characters and language information. 573 Link: ; 574 rel="previous"; title*=UTF-8'de'letztes%20Kapitel, 575 ; 576 rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel 578 Here, both links have titles encoded in UTF-8, use the German 579 language ("de"), and the second link contains the Unicode code point 580 U+00E4 ("LATIN SMALL LETTER A WITH DIAERESIS"). 582 Note that link-values can convey multiple links between the same link 583 target and link context; for example: 585 Link: ; 586 rel="start http://example.net/relation/other" 588 Here, the link to "http://example.org/" has the registered relation 589 type "start" and the extension relation type 590 "http://example.net/relation/other". 592 Finally, this header field: 594 Link: ; rel="start", 595 ; rel="index" 597 is equivalent to these: 599 Link: ; rel="start" 600 Link: ; rel="index" 602 4. IANA Considerations 604 4.1. Link HTTP Header Field Registration 606 This specification updates the Message Header registry entry for 607 "Link" in HTTP [RFC3864] to refer to this document. 609 Header field: Link 610 Applicable protocol: http 611 Status: standard 612 Author/change controller: 613 IETF (iesg@ietf.org) 614 Internet Engineering Task Force 615 Specification document(s): 616 [this document] 618 4.2. Link Relation Type Registry 620 This specification updates the registration procedures for the Link 621 Relation Type registry; see Section 2.1.1.1. 623 IANA will direct any incoming requests regarding the registry to this 624 document and, if defined, the processes established by the expert(s); 625 typically, this will mean referring them to the registry Web page. 627 Note that the expert(s) are allowed (as per Section 2.1.1.1) to 628 define additional fields to be collected in the registry. 630 4.3. Link Relation Application Data Registry 632 This specification removes the Link Relation Application Data 633 Registry, as it has not been used, and future use is not anticipated. 634 IANA is instructed to remove it. 636 5. Security Considerations 638 The content of the Link header field is not secure, private or 639 integrity-guaranteed. Use of Transport Layer Security (TLS) with 640 HTTP ([RFC2818]) is currently the only end-to-end way to provide 641 these properties. 643 Link applications ought to consider the attack vectors opened by 644 automatically following, trusting, or otherwise using links gathered 645 from HTTP header fields. In particular, Link header fields that use 646 the "anchor" parameter to associate a link's context with another 647 resource are to be treated with due caution. 649 The Link header field makes extensive use of IRIs and URIs. See 650 [RFC3987] Section 8 for security considerations relating to IRIs. 651 See [RFC3986] Section 7 for security considerations relating to URIs. 652 See [RFC7230] Section 9 for security considerations relating to HTTP 653 header fields. 655 6. Internationalisation Considerations 657 Link targets may need to be converted to URIs in order to express 658 them in serialisations that do not support IRIs. This includes the 659 Link HTTP header field. 661 Similarly, the anchor parameter of the Link header field does not 662 support IRIs, and therefore IRIs must be converted to URIs before 663 inclusion there. 665 Relation types are defined as URIs, not IRIs, to aid in their 666 comparison. It is not expected that they will be displayed to end 667 users. 669 Note that registered Relation Names are required to be lower-case 670 ASCII letters. 672 7. References 674 7.1. Normative References 676 [I-D.ietf-httpbis-rfc5987bis] 677 Reschke, J., "Indicating Character Encoding and Language 678 for HTTP Header Field Parameters", draft-ietf-httpbis- 679 rfc5987bis-05 (work in progress), February 2017. 681 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 682 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 683 RFC2119, March 1997, 684 . 686 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 687 Procedures for Message Header Fields", BCP 90, RFC 3864, 688 DOI 10.17487/RFC3864, September 2004, 689 . 691 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 692 Resource Identifier (URI): Generic Syntax", STD 66, RFC 693 3986, DOI 10.17487/RFC3986, January 2005, 694 . 696 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 697 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 698 January 2005, . 700 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 701 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 702 September 2009, . 704 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 705 Specifications and Registration Procedures", BCP 13, RFC 706 6838, DOI 10.17487/RFC6838, January 2013, 707 . 709 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 710 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 711 7230, DOI 10.17487/RFC7230, June 2014, 712 . 714 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 715 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 716 10.17487/RFC7231, June 2014, 717 . 719 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 720 Writing an IANA Considerations Section in RFCs", BCP 26, 721 RFC 8126, DOI 10.17487/RFC8126, June 2017, 722 . 724 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 725 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 726 May 2017, . 728 [W3C.REC-css3-mediaqueries-20120619] 729 Rivoal, F., "Media Queries", World Wide Web Consortium 730 Recommendation REC-css3-mediaqueries-20120619, June 2012, 731 . 734 7.2. Informative References 736 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 737 Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 738 10.17487/RFC2046, November 1996, 739 . 741 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/ 742 RFC2818, May 2000, 743 . 745 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 746 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 747 December 2005, . 749 [W3C.REC-html5-20141028] 750 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 751 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 752 World Wide Web Consortium Recommendation REC- 753 html5-20141028, October 2014, 754 . 756 Appendix A. Notes on Other Link Serialisations 758 Header fields (Section 3) are only one serialisation of links; other 759 specifications have defined alternative serialisations. 761 A.1. Link Serialisation in HTML 763 HTML motivated the original syntax of the Link header field, and many 764 of the design decisions in this document are driven by a desire to 765 stay compatible with it. 767 In HTML, the link element can be mapped to links as specified here by 768 using the "href" attribute for the target URI, and "rel" to convey 769 the relation type, as in the Link header field. The context of the 770 link is the URI associated with the entire HTML document. HTML also 771 defines several attributes on links that can be seen as target 772 attributes, including "media", "hreflang", "type" and "sizes". 774 Section 4.8 of HTML5 ([W3C.REC-html5-20141028]) defines modern HTML 775 links. That document links to the Microformats Wiki as a registry; 776 over time, the IANA registry ought to mirror its contents, and 777 ideally eventually replace it (although that depends on the HTML 778 community). 780 Surveys of existing HTML content have shown that unregistered link 781 relation types that are not URIs are (perhaps inevitably) common. 782 Consuming HTML implementations ought not consider such unregistered 783 short links to be errors, but rather relation types with a local 784 scope (i.e., their meaning is specific and perhaps private to that 785 document). 787 Finally, the HTML specification gives a special meaning when the 788 "alternate" relation types coincides with other relation types in the 789 same link. Such links ought to be serialised in the Link header 790 field using a single list of relation-types (e.g., rel="alternate 791 stylesheet") to preserve this relationship. 793 A.2. Link Serialisation in Atom 795 Atom [RFC4287] is a link serialisation that conveys links in the 796 atom:link element, with the "href" attribute indicating the link 797 target and the "rel" attribute containing the relation type. The 798 context of the link is either a feed locator or an entry ID, 799 depending on where it appears; generally, feed-level links are 800 obvious candidates for transmission as a Link header field. 802 When serialising an atom:link into a Link header field, it is 803 necessary to convert link targets (if used) to URIs. 805 Atom defines extension relation types in terms of IRIs. This 806 specification re-defines them as URIs, to simplify and reduce errors 807 in their comparison. 809 Atom allows registered link relation types to be serialised as 810 absolute URIs using a prefix, "http://www.iana.org/assignments/ 811 relation/". This prefix is specific to the Atom serialisation. 813 Furthermore, link relation types are always compared in a case- 814 sensitive fashion; therefore, registered link relation types SHOULD 815 be converted to their registered form (usually, lowercase) when 816 serialised in an Atom document. 818 Note also that while the Link header field allows multiple relations 819 to be serialised in a single link, atom:link does not. In this case, 820 a single link-value may map to several atom:link elements. 822 As with HTML, atom:link defines some attributes that are not 823 explicitly mirrored in the Link header field syntax, but they can 824 also be used as link-extensions to maintain fidelity. 826 Appendix B. Algorithms for Parsing Link Header Fields 828 This appendix outlines a set of non-normative algorithms: for parsing 829 the Link header(s) out of a header set, parsing a link header field 830 value, and algorithms for parsing generic parts of the field value. 832 These algorithms are more permissive than the ABNF defining the 833 syntax might suggest; the error handling embodied in them is a 834 reasonable approach, but not one that is required. As such they are 835 advisory only, and in cases where there is disagreement, the correct 836 behaviour is defined by the body of this specification. 838 B.1. Parsing a Header Set for Links 840 This algorithm can be used to parse the Link header fields that a 841 HTTP header set contains. Given a "header_set" of (string 842 "field_name", string "field_value") pairs, assuming ASCII encoding, 843 it returns a list of link objects. 845 1. Let "field_values" be a list containing the members of 846 "header_set" whose "field_name" is a case-insensitive match for 847 "link". 849 2. Let "links" be an empty list. 851 3. For each "field_value" in "field_values": 853 1. Let "value_links" be the result of _Parsing A Link Field 854 Value_ (Appendix B.2) from "field_value". 856 2. Append each member of "value_links" to "links". 858 4. Return "links". 860 B.2. Parsing a Link Field Value 862 This algorithm parses zero or more comma-separated link-values from a 863 Link header field. Given a string "field_value", assuming ASCII 864 encoding, it returns a list of link objects. 866 1. Let "links" be an empty list. 868 2. While "field_value" has content: 870 1. Consume any leading OWS. 872 2. If the first character is not "<", return "links". 874 3. Discard the first character ("<"). 876 4. Consume up to but not including the first ">" character or 877 end of "field_value" and let the result be "target_string". 879 5. If the next character is not ">", return "links". 881 6. Discard the leading ">" character. 883 7. Let "link_parameters", be the result of _Parsing Parameters_ 884 (Appendix B.3) from "field_value" (consuming zero or more 885 characters of it). 887 8. Let "target" be the result of relatively resolving (as per 888 [RFC3986], Section 5.2) "target_string". Note that any base 889 URI carried in the payload body is NOT used. 891 9. Let "relations_string" be the second item of the first tuple 892 of "link_parameters" whose first item matches the string 893 "rel", or the empty string ("") if it is not present. 895 10. Split "relations_string" on RWS (removing it in the process) 896 into a list of strings "relation_types". 898 11. Let "context_string" be the second item of the first tuple 899 of "link_parameters" whose first item matches the string 900 "anchor". If it is not present, "context_string" is the URL 901 of the representation carrying the Link header [RFC7231], 902 Section 3.1.4.1, serialised as a URI. Where the URL is 903 anonymous, "context_string" is null. 905 12. Let "context" be the result of relatively resolving (as per 906 [RFC3986], Section 5.2) "context_string", unless 907 "context_string" is null in which case "context" is null. 908 Note that any base URI carried in the payload body is NOT 909 used. 911 13. Let "target_attributes" be an empty list. 913 14. For each tuple ("param_name", "param_value") of 914 "link_parameters": 916 1. If "param_name" matches "rel" or "anchor", skip this 917 tuple. 919 2. If "param_name" matches "media", "title", "title*" or 920 "type" and "target_attributes" already contains a tuple 921 whose first element matches the value of "param_name", 922 skip this tuple. 924 3. Append ("param_name", "param_value") to 925 "target_attributes". 927 15. Let "star_param_names" be the set of "param_name"s in the 928 ("param_name", "param_value") tuples of "link_parameters" 929 where the last character of "param_name" is an asterisk 930 ("*"). 932 16. For each "star_param_name" in "star_param_names": 934 1. Let "base_param_name" be "star_param_name" with the last 935 character removed. 937 2. If the implementation does not choose to support an 938 internationalised form of a parameter named 939 "base_param_name" for any reason (including, but not 940 limited to, it being prohibited by the parameter's 941 specification), remove all tuples from "link_parameters" 942 whose first member is "star_param_name" and skip to the 943 next "star_param_name". 945 3. Remove all tuples from "link_parameters" whose first 946 member is "base_param_name". 948 4. Change the first member of all tuples in 949 "link_parameters" whose first member is 950 "star_param_name" to "base_param_name". 952 17. For each "relation_type" in "relation_types": 954 1. Case-normalise "relation_type" to lowercase. 956 2. Append a link object to "links" with the target 957 "target", relation type of "relation_type", context of 958 "context", and target attributes "target_attributes". 960 3. Return "links". 962 B.3. Parsing Parameters 964 This algorithm parses the parameters from a header field value. 965 Given an ASCII string "input", it returns a list of (string 966 "parameter_name", string "parameter_value") tuples that it contains. 967 "input" is modified to remove the parsed parameters. 969 1. Let "parameters" be an empty list. 971 2. While "input" has content: 973 1. Consume any leading OWS. 975 2. If the first character is not ";", return "parameters". 977 3. Discard the leading ";" character. 979 4. Consume any leading OWS. 981 5. Consume up to but not including the first BWS, "=", ";", "," 982 character or end of "input" and let the result be 983 "parameter_name". 985 6. Consume any leading BWS. 987 7. If the next character is "=": 989 1. Discard the leading "=" character. 991 2. Consume any leading BWS. 993 3. If the next character is DQUOTE, let "parameter_value" 994 be the result of _Parsing a Quoted String_ 995 (Appendix B.4) from "input" (consuming zero or more 996 characters of it). 998 4. Else, consume the contents up to but not including the 999 first ";", "," character or end of "input" and let the 1000 results be "parameter_value". 1002 5. If the last character of "parameter_name" is an asterisk 1003 ("*"), decode "parameter_value" according to 1004 [I-D.ietf-httpbis-rfc5987bis]. Continue processing 1005 "input" if an unrecoverable error is encountered. 1007 8. Else: 1009 1. Let "parameter_value" be an empty string. 1011 9. Case-normalise "parameter_name" to lowercase. 1013 10. Append ("parameter_name", "parameter_value") to 1014 "parameters". 1016 11. Consume any leading OWS. 1018 12. If the next character is "," or the end of "input", stop 1019 processing "input" and return "parameters". 1021 B.4. Parsing a Quoted String 1023 This algorithm parses a quoted string, as per [RFC7230], 1024 Section 3.2.6. Given an ASCII string "input", it returns an unquoted 1025 string. "input" is modified to remove the parsed string. 1027 1. Let "output" be an empty string. 1029 2. If the first character of "input" is not DQUOTE, return "output". 1031 3. Discard the first character. 1033 4. While "input" has content: 1035 1. If the first character is a backslash ("\"): 1037 1. Discard the first character. 1039 2. If there is no more "input", return "output". 1041 3. Else, consume the first character and append it to 1042 "output". 1044 2. Else, if the first character is DQUOTE, discard it and return 1045 "output". 1047 3. Else, consume the first character and append it to "output". 1049 5. Return "output". 1051 Appendix C. Changes from RFC5988 1053 This specification has the following differences from its 1054 predecessor, RFC5988: 1056 o The initial relation type registrations were removed, since 1057 they've already been registered by 5988. 1059 o The introduction has been shortened. 1061 o The Link Relation Application Data Registry has been removed. 1063 o Incorporated errata. 1065 o Updated references. 1067 o Link cardinality was clarified. 1069 o Terminology was changed from "target IRI" and "context IRI" to 1070 "link target" and "link context" respectively. 1072 o Made assigning a URI to registered relation types serialisation- 1073 specific. 1075 o Removed misleading statement that the link header field is 1076 semantically equivalent to HTML and Atom links. 1078 o More carefully defined and used "link serialisations" and "link 1079 applications." 1081 o Clarified the cardinality of target attributes (generically and 1082 for "type"). 1084 o Corrected the default link context for the Link header field, to 1085 be dependent upon the identity of the representation (as per 1086 RFC7231). 1088 o Defined a suggested parsing algorithm for the Link header. 1090 o The value space of target attributes and their definition has been 1091 specified. 1093 o The ABNF has been updated to be compatible with [RFC7230]. In 1094 particular, whitespace is now explicit. 1096 o Some parameters on the HTTP header field can now appear as a 1097 token. 1099 o Parameters on the HTTP header can now be value-less. 1101 o Handling of quoted strings is now defined by [RFC7230]. 1103 o The "type" header field parameter now needs to be quoted (as 1104 "token" does not allow "/"). 1106 Author's Address 1108 Mark Nottingham 1110 EMail: mnot@mnot.net 1111 URI: https://www.mnot.net/