idnits 2.17.1 draft-nottingham-rfc5988bis-02.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 use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. == 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 (November 22, 2016) is 2706 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: A later version (-05) exists of draft-ietf-httpbis-rfc5987bis-03 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft November 22, 2016 4 Obsoletes: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: May 26, 2017 8 Web Linking 9 draft-nottingham-rfc5988bis-02 11 Abstract 13 This specification defines a way to indicate the relationships 14 between resources on the Web ("links") and the type of those 15 relationships ("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 May 26, 2017. 50 Copyright Notice 52 Copyright (c) 2016 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 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 81 3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 82 4. Link Relation Types . . . . . . . . . . . . . . . . . . . . . 5 83 4.1. Registered Relation Types . . . . . . . . . . . . . . . . 5 84 4.1.1. Registering Link Relation Types . . . . . . . . . . . 6 85 4.2. Extension Relation Types . . . . . . . . . . . . . . . . 7 86 5. Target Attributes . . . . . . . . . . . . . . . . . . . . . . 7 87 6. Link Serialisation in HTTP Headers . . . . . . . . . . . . . 8 88 6.1. Link Target . . . . . . . . . . . . . . . . . . . . . . . 8 89 6.2. Link Context . . . . . . . . . . . . . . . . . . . . . . 8 90 6.3. Relation Type . . . . . . . . . . . . . . . . . . . . . . 9 91 6.4. Target Attributes . . . . . . . . . . . . . . . . . . . . 9 92 6.4.1. Serialisation-Defined Attributes . . . . . . . . . . 10 93 6.4.2. Extension Attributes . . . . . . . . . . . . . . . . 11 94 6.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 11 95 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 96 7.1. Link HTTP Header Field Registration . . . . . . . . . . . 12 97 7.2. Link Relation Type Registry . . . . . . . . . . . . . . . 12 99 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 100 9. Internationalisation Considerations . . . . . . . . . . . . . 13 101 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 102 10.1. Normative References . . . . . . . . . . . . . . . . . . 14 103 10.2. Informative References . . . . . . . . . . . . . . . . . 15 104 Appendix A. Notes on Other Link Serialisations . . . . . . . . . 17 105 A.1. Link Serialisation in HTML . . . . . . . . . . . . . . . 17 106 A.2. Link Serialisation in Atom . . . . . . . . . . . . . . . 18 107 Appendix B. Algorithm for Parsing Link Headers . . . . . . . . . 18 108 Appendix C. Changes from RFC5988 . . . . . . . . . . . . . . . . 21 109 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 111 1. Introduction 113 This specification defines a way to indicate the relationships 114 between resources on the Web ("links") and the type of those 115 relationships ("link relation types"). 117 HTML [W3C.REC-html5-20141028] and Atom [RFC4287] both have well- 118 defined concepts of linking; this specification generalises this into 119 a framework that encompasses linking in these formats and 120 (potentially) elsewhere. 122 Furthermore, this specification formalises an HTTP header field for 123 conveying such links, having been originally defined in 124 Section 19.6.2.4 of [RFC2068], but removed from [RFC2616]. 126 2. Notational Conventions 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 130 document are to be interpreted as described in BCP 14, [RFC2119], as 131 scoped to those conformance targets. 133 This document uses the Augmented Backus-Naur Form (ABNF) notation of 134 [RFC7230], including the #rule, and explicitly includes the following 135 rules from it: quoted-string, token, SP (space), BWS (bad 136 whitespace), OWS (optional whitespace), RWS (required whitespace) 137 LOALPHA, DIGIT. 139 Additionally, the following rules are included from [RFC3986]: URI 140 and URI-Reference; from [RFC6838]: type-name and subtype-name; from 141 [W3C.CR-css3-mediaqueries-20090915]: media_query_list; from 142 [RFC5646]: Language-Tag; and from [I-D.ietf-httpbis-rfc5987bis], ext- 143 value and parmname. 145 3. Links 147 In this specification, a link is a typed connection between two 148 resources, and is comprised of: 150 o A _link context_, 152 o a _link relation type_ (Section 4), 154 o a _link target_, and 156 o optionally, _target attributes_ (Section 5). 158 A link can be viewed as a statement of the form "{link context} has a 159 {link relation type} resource at {link target}, which has {target 160 attributes}". 162 Link contexts and link targets are both IRIs [RFC3987]. However, in 163 the common case, the link context will also be a URI [RFC3986], 164 because many protocols (such as HTTP) do not support dereferencing 165 IRIs. Likewise, the link target will be sometimes be converted to a 166 URI (see [RFC3987], Section 3.1) in places that do not support IRIs 167 (such as the Link header field defined in Section 6). 169 This specification does not place restrictions on the cardinality of 170 links; there can be multiple links to and from a particular target, 171 and multiple links of the same or different types between a given 172 context and target. Likewise, the relative ordering of links in any 173 particular serialisation, or between serialisations (e.g., the Link 174 header field and in-content links) is not specified or significant in 175 this specification; applications that wish to consider ordering 176 significant can do so. 178 Links are conveyed in _link serialisations_; they are the "bytes on 179 the wire", and can occur in various forms. This specification does 180 not define a general syntax for links, nor does it mandate a specific 181 context for any given link; it is expected that serialisations of 182 links will specify both aspects. One such serialisation is 183 communication of links through HTTP headers, specified in Section 6. 185 Finally, links are consumed by _link applications_. Generally, an 186 application will define the link relation types it uses, along with 187 the serialisations that they might occur within. For example, the 188 application "Web browsing" looks for the "stylesheet" link relation 189 type in the HTML link serialisation. 191 4. Link Relation Types 193 In the simplest case, a link relation type identifies the semantics 194 of a link. For example, a link with the relation type "copyright" 195 indicates that the resource identified by the link target is a 196 statement of the copyright terms applying to the current link 197 context. 199 Link relation types can also be used to indicate that the target 200 resource has particular attributes, or exhibits particular 201 behaviours; for example, a "service" link implies that the identified 202 resource is part of a defined protocol (in this case, a service 203 description). 205 Relation types are not to be confused with media types [RFC6838]; 206 they do not identify the format of the representation that results 207 when the link is dereferenced. Rather, they only describe how the 208 current context is related to another resource. 210 Relation types SHOULD NOT infer any additional semantics based upon 211 the presence or absence of another link relation type, or its own 212 cardinality of occurrence. An exception to this is the combination 213 of the "alternate" and "stylesheet" registered relation types, which 214 has special meaning in HTML for historical reasons. 216 There are two kinds of relation types: registered and extension. 218 4.1. Registered Relation Types 220 Well-defined relation types can be registered as tokens for 221 convenience and/or to promote reuse by other applications, using the 222 procedure in Section 4.1.1. 224 Registered relation type names MUST conform to the reg-rel-type rule, 225 and MUST be compared character-by-character in a case-insensitive 226 fashion. They SHOULD be appropriate to the specificity of the 227 relation type; i.e., if the semantics are highly specific to a 228 particular application, the name should reflect that, so that more 229 general names are available for less specific use. 231 Registered relation types MUST NOT constrain the media type of the 232 link context, and MUST NOT constrain the available representation 233 media types of the link target. However, they can specify the 234 behaviours and properties of the target resource (e.g., allowable 235 HTTP methods, request and response media types that must be 236 supported). 238 Historically, registered relation types have been identified with a 239 URI [RFC3986] by prefixing their names with an application-defined 240 base URI (e.g., see Appendix A.2). This practice is NOT RECOMMENDED, 241 because the resulting strings will not be considered equivalent to 242 the registered relation types by other processors. Applications that 243 do use such URIs internally MUST NOT use them in link serialisations 244 that do not explicitly accommodate them. 246 4.1.1. Registering Link Relation Types 248 Relation types are registered on the advice of a Designated Expert 249 (appointed by the IESG or their delegate), with a Specification 250 Required (using terminology from [RFC5226]). 252 The Expert(s) will establish procedures for requesting registrations, 253 and make them available from the registry page. 255 Registration requests consist of at least the following information: 257 o Relation Name: 259 o Description: 261 o Reference: 263 The Expert(s) MAY define additional fields to be collected in the 264 registry. 266 General requirements for registered relation types are described in 267 Section 4.1. 269 See the registry for examples of the description field; generally, it 270 SHOULD identify the semantics in terms of the link's context and 271 target. 273 Registrations MUST reference a freely available, stable 274 specification. 276 Note that relation types can be registered by third parties, if the 277 Expert(s) determine that an unregistered relation type is widely 278 deployed and not likely to be registered in a timely manner. 280 Decisions (or lack thereof) made by the Expert(s) can be first 281 appealed to Application Area Directors (contactable using app- 282 ads@tools.ietf.org email address or directly by looking up their 283 email addresses on http://www.iesg.org/ website) and, if the 284 appellant is not satisfied with the response, to the full IESG (using 285 the iesg@iesg.org mailing list). 287 4.2. Extension Relation Types 289 Applications that don't wish to register a relation type can use an 290 extension relation type, which is a URI [RFC3986] that uniquely 291 identifies the relation type. Although the URI can point to a 292 resource that contains a definition of the semantics of the relation 293 type, clients SHOULD NOT automatically access that resource to avoid 294 overburdening its server. 296 The URI used for an extension relation type SHOULD be under the 297 control of the person or party defining it, or be delegated to them. 299 When extension relation types are compared, they MUST be compared as 300 strings (after converting to URIs if serialised in a different 301 format, such as a XML QNames [W3C.REC-xml-names-20091208]) in a case- 302 insensitive fashion, character-by-character. Because of this, all- 303 lowercase URIs SHOULD be used for extension relations. 305 Note that while extension relation types are required to be URIs, a 306 serialisation of links can specify that they are expressed in another 307 form, as long as they can be converted to URIs. 309 5. Target Attributes 311 _Target attributes_ are a set of key/value pairs that describe the 312 link or its target; for example, a media type hint. 314 This specification does not attempt to coordinate the name of target 315 attributes, their cardinality or use; they are defined both by 316 individual link relations and by link serialisations. 318 Serialisations SHOULD coordinate their target attributes to avoid 319 conflicts in semantics or syntax. Relation types MAY define 320 additional target attributes specific to them. 322 The names of target attributes SHOULD conform to the parmname rule 323 for portability across serializations, and MUST be compared in a 324 case-insensitive fashion. 326 Target attribute definitions SHOULD specify: 328 o Their serialisation into Unicode or a subset thereof, to maximise 329 their chances of portability across link serialisations. 331 o The semantics and error handling of multiple occurrences of the 332 attribute on a given link. 334 This specification does define target attributes for use in the Link 335 HTTP header field in Section 6.4. 337 6. Link Serialisation in HTTP Headers 339 The Link header field provides a means for serialising one or more 340 links into HTTP headers. 342 The ABNF for the field value is given below: 344 Link = #link-value 345 link-value = "<" URI-Reference ">" *( OWS ";" OWS link-param ) 346 link-param = token BWS "=" BWS ( token / quoted-string ) 348 Note that any "link-param" can be generated with values using either 349 the "token" or the "quoted-string" syntax, and therefore recipients 350 MUST be able to parse both forms. Individual "link-param"s specify 351 their syntax in terms of the value after any necessary unquoting (as 352 per [RFC7230], Section 3.2.6). 354 This specification defines the link-params "rel", "anchor", "rev", 355 "hreflang", "media", "title", "title*", and "type"; see Section 6.2, 356 Section 6.3 and Section 6.4. 358 6.1. Link Target 360 Each link-value conveys one target IRI as a URI-Reference (after 361 conversion to one, if necessary; see [RFC3987], Section 3.1) inside 362 angle brackets ("<>"). If the URI-Reference is relative, parsers 363 MUST resolve it as per [RFC3986], Section 5. Note that any base IRI 364 from the message's content is not applied. 366 6.2. Link Context 368 By default, the context of a link conveyed in the Link header field 369 is identity of the representation it is associated with, as defined 370 in [RFC7231], Section 3.1.4.1, serialised as a URI. 372 When present, the anchor parameter overrides this with another URI, 373 such as a fragment of this resource, or a third resource (i.e., when 374 the anchor value is an absolute URI). If the anchor parameter's 375 value is a relative URI, parsers MUST resolve it as per [RFC3986], 376 Section 5. Note that any base URI from the body's content is not 377 applied. 379 The ABNF for the "anchor" parameter's value is: ~~~ abnf2616 URI- 380 Reference ~~~ 381 Consuming implementations can choose to ignore links with an anchor 382 parameter. For example, the application in use might not allow the 383 link context to be assigned to a different resource. In such cases, 384 the entire link is to be ignored; consuming implementations MUST NOT 385 process the link without applying the anchor. 387 Note that depending on HTTP status code and response headers, the 388 link context might be "anonymous" (i.e., no link context is 389 available). For instance, this is the case on a 404 response to a 390 GET request. 392 6.3. Relation Type 394 The relation type of a link conveyed in the Link header field is 395 conveyed in the "rel" parameter's value. The "rel" parameter MUST 396 NOT appear more than once in a given link-value; occurrences after 397 the first MUST be ignored by parsers. 399 The "rev" parameter has been used in the past to indicate that the 400 semantics of the relationship are in the reverse direction. That is, 401 a link from A to B with REL="X" expresses the same relationship as a 402 link from B to A with REV="X". "rev" is deprecated by this 403 specification because it often confuses authors and readers; in most 404 cases, using a separate relation type is preferable. 406 The ABNF for the "rel" and "rev" parameters' values is: ~~~ abnf2616 407 relation-type _( 1_SP relation-type ) ~~~ 409 where: 411 relation-type = reg-rel-type | ext-rel-type 412 reg-rel-type = LOALPHA *( LOALPHA | DIGIT | "." | "-" ) 413 ext-rel-type = URI 415 Note that extension relation types are REQUIRED to be absolute URIs 416 in Link headers, and MUST be quoted if they contain a semicolon (";") 417 or comma (",") (as these characters are used as delimiters in the 418 header field itself). 420 6.4. Target Attributes 422 The Link header field defines several target attributes specific to 423 this serialisation, and also allows extension target attributes. 424 Target attributes are serialised in the Link header field as 425 parameters (see [RFC7231], Section 3.1.1.1 for the definition of 426 their syntax). 428 6.4.1. Serialisation-Defined Attributes 430 The "hreflang", "media", "title", "title*", and "type" link-params 431 can be translated to serialisation-defined target attributes for the 432 link. 434 The "hreflang" attribute, when present, is a hint indicating what the 435 language of the result of dereferencing the link should be. Note 436 that this is only a hint; for example, it does not override the 437 Content-Language header field of a HTTP response obtained by actually 438 following the link. Multiple "hreflang" attributes on a single link- 439 value indicate that multiple languages are available from the 440 indicated resource. 442 The ABNF for the "hreflang" parameter's value is: ~~~ abnf2616 443 Language-Tag ~~~ 445 The "media" attribute, when present, is used to indicate intended 446 destination medium or media for style information (see 447 [W3C.REC-html5-20141028], Section 4.2.4). Its value MUST be quoted 448 if it contains a semicolon (";") or comma (","). There MUST NOT be 449 more than one "media" attribute in a link-value; occurrences after 450 the first MUST be ignored by parsers. 452 The ABNF for the "media" parameter's value is: ~~~ abnf2616 453 media_query_list ~~~ 455 The "title" attribute, when present, is used to label the destination 456 of a link such that it can be used as a human-readable identifier 457 (e.g., a menu entry) in the language indicated by the Content- 458 Language header field (if present). The "title" attribute MUST NOT 459 appear more than once in a given link; occurrences after the first 460 MUST be ignored by parsers. 462 The "title*" link-param can be used to encode this attribute in a 463 different character set, and/or contain language information as per 464 [I-D.ietf-httpbis-rfc5987bis]. The "title*" link-param MUST NOT 465 appear more than once in a given link-value; occurrences after the 466 first MUST be ignored by parsers. If the attribute does not contain 467 language information, its language is indicated by the Content- 468 Language header field (when present). 470 If both the "title" and "title*" link-param appear in a link, 471 processors SHOULD use the "title*" link-param's value for the "title" 472 attribute. 474 The "type" attribute, when present, is a hint indicating what the 475 media type of the result of dereferencing the link should be. Note 476 that this is only a hint; for example, it does not override the 477 Content-Type header field of a HTTP response obtained by actually 478 following the link. The "type" attribute MUST NOT appear more than 479 once in a given link-value; occurrences after the first MUST be 480 ignored by parsers. 482 The ABNF for the "type" parameter's value is: ~~~ abnf2616 type-name 483 "/" subtype-name ~~~ 485 6.4.2. Extension Attributes 487 Other link-params are link-extensions, and are to be considered as 488 target attributes. 490 Such target attributes MAY be defined to use the encoding in 491 [I-D.ietf-httpbis-rfc5987bis] (e.g., "example" and "example_"). When 492 both forms are present, they SHOULD be considered to be the same 493 target attribute; processors SHOULD use the value of the name ending 494 in "_" (after [I-D.ietf-httpbis-rfc5987bis] decoding), but MAY fall 495 back to the other value if there is an error in decoding it, or if 496 they do not support decoding. 498 6.5. Examples 500 For example: 502 Link: ; rel="previous"; 503 title="previous chapter" 505 indicates that "chapter2" is previous to this resource in a logical 506 navigation path. 508 Similarly, 510 Link: ; rel="http://example.net/foo" 512 indicates that the root resource ("/") is related to this resource 513 with the extension relation type "http://example.net/foo". 515 The example below shows an instance of the Link header field encoding 516 multiple links, and also the use of RFC 5987 encoding to encode both 517 non-ASCII characters and language information. 519 Link: ; 520 rel="previous"; title*=UTF-8'de'letztes%20Kapitel, 521 ; 522 rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel 524 Here, both links have titles encoded in UTF-8, use the German 525 language ("de"), and the second link contains the Unicode code point 526 U+00E4 ("LATIN SMALL LETTER A WITH DIAERESIS"). 528 Note that link-values can convey multiple links between the same link 529 target and link context; for example: 531 Link: ; 532 rel="start http://example.net/relation/other" 534 Here, the link to "http://example.org/" has the registered relation 535 type "start" and the extension relation type 536 "http://example.net/relation/other". 538 7. IANA Considerations 540 In addition to the actions below, IANA should terminate the Link 541 Relation Application Data Registry, as it has not been used, and 542 future use is not anticipated. 544 7.1. Link HTTP Header Field Registration 546 This specification updates the Message Header registry entry for 547 "Link" in HTTP [RFC3864] to refer to this document. 549 Header field: Link 550 Applicable protocol: http 551 Status: standard 552 Author/change controller: 553 IETF (iesg@ietf.org) 554 Internet Engineering Task Force 555 Specification document(s): 556 [RFC&rfc.number;] 558 7.2. Link Relation Type Registry 560 This specification updates the registration procedures for the Link 561 Relation Type registry; see Section 4.1.1. The Expert(s) and IANA 562 will interact as outlined below. 564 IANA will direct any incoming requests regarding the registry to the 565 processes established by the Expert(s); typically, this will mean 566 referring them to the registry Web page. 568 The Expert(s) will provide registry data to IANA in an agreed form 569 (e.g. a specific XML format). IANA will publish: 571 o The raw registry data 572 o The registry data, transformed into HTML 574 o The registry data in any alternative formats provided by the 575 Expert(s) 577 Each published document will be at a URL agreed to by IANA and the 578 Expert(s), and IANA will set HTTP response headers on them as 579 (reasonably) requested by the Expert(s). 581 Additionally, the HTML generated by IANA will: 583 o Take directions from the Expert(s) as to the content of the HTML 584 page's introductory text and markup 586 o Include a stable HTML fragment identifier for each registered link 587 relation 589 All registry data documents MUST include Simplified BSD License text 590 as described in Section 4.e of the Trust Legal Provisions 591 (). 593 8. Security Considerations 595 The content of the Link header field is not secure, private or 596 integrity-guaranteed, and due caution should be exercised when using 597 it. Use of Transport Layer Security (TLS) with HTTP ([RFC2818] and 598 [RFC2817]) is currently the only end-to-end way to provide such 599 protection. 601 Link applications ought to consider the attack vectors opened by 602 automatically following, trusting, or otherwise using links gathered 603 from HTTP headers. In particular, Link header fields that use the 604 "anchor" parameter to associate a link's context with another 605 resource should be treated with due caution. 607 The Link header field makes extensive use of IRIs and URIs. See 608 [RFC3987] for security considerations relating to IRIs. See 609 [RFC3986] for security considerations relating to URIs. See 610 [RFC7230] for security considerations relating to HTTP headers. 612 9. Internationalisation Considerations 614 Link targets may need to be converted to URIs in order to express 615 them in serialisations that do not support IRIs. This includes the 616 Link HTTP header field. 618 Similarly, the anchor parameter of the Link header field does not 619 support IRIs, and therefore IRIs must be converted to URIs before 620 inclusion there. 622 Relation types are defined as URIs, not IRIs, to aid in their 623 comparison. It is not expected that they will be displayed to end 624 users. 626 Note that registered Relation Names are required to be lower-case 627 ASCII letters. 629 10. References 631 10.1. Normative References 633 [I-D.ietf-httpbis-rfc5987bis] 634 Reschke, J., "Indicating Character Encoding and Language 635 for HTTP Header Field Parameters", draft-ietf-httpbis- 636 rfc5987bis-03 (work in progress), July 2016. 638 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 639 Requirement Levels", BCP 14, RFC 2119, 640 DOI 10.17487/RFC2119, March 1997, 641 . 643 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 644 Procedures for Message Header Fields", BCP 90, RFC 3864, 645 DOI 10.17487/RFC3864, September 2004, 646 . 648 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 649 Resource Identifier (URI): Generic Syntax", STD 66, 650 RFC 3986, DOI 10.17487/RFC3986, January 2005, 651 . 653 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 654 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 655 January 2005, . 657 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 658 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 659 DOI 10.17487/RFC5226, May 2008, 660 . 662 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 663 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 664 September 2009, . 666 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 667 Specifications and Registration Procedures", BCP 13, 668 RFC 6838, DOI 10.17487/RFC6838, January 2013, 669 . 671 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 672 Protocol (HTTP/1.1): Message Syntax and Routing", 673 RFC 7230, DOI 10.17487/RFC7230, June 2014, 674 . 676 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 677 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 678 DOI 10.17487/RFC7231, June 2014, 679 . 681 [W3C.CR-css3-mediaqueries-20090915] 682 Lie, H., Celik, T., Glazman, D., and A. Kesteren, "Media 683 Queries", World Wide Web Consortium CR CR-css3- 684 mediaqueries-20090915, September 2009, 685 . 687 10.2. Informative References 689 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. 690 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 691 RFC 2068, DOI 10.17487/RFC2068, January 1997, 692 . 694 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 695 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 696 Transfer Protocol -- HTTP/1.1", RFC 2616, 697 DOI 10.17487/RFC2616, June 1999, 698 . 700 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 701 HTTP/1.1", RFC 2817, DOI 10.17487/RFC2817, May 2000, 702 . 704 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 705 DOI 10.17487/RFC2818, May 2000, 706 . 708 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 709 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 710 December 2005, . 712 [W3C.REC-html-rdfa-20150317] 713 Sporny, M., "HTML+RDFa 1.1 - Second Edition", World Wide 714 Web Consortium Recommendation REC-html-rdfa-20150317, 715 March 2015, 716 . 718 [W3C.REC-html5-20141028] 719 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 720 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 721 World Wide Web Consortium Recommendation REC- 722 html5-20141028, October 2014, 723 . 725 [W3C.REC-xml-names-20091208] 726 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 727 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 728 Wide Web Consortium Recommendation REC-xml-names-20091208, 729 December 2009, 730 . 732 Appendix A. Notes on Other Link Serialisations 734 Header fields (Section 6) are only one serialisation of links; other 735 specifications have defined alternative serialisations. 737 A.1. Link Serialisation in HTML 739 HTML [W3C.REC-html5-20141028] motivated the original syntax of the 740 Link header field, and many of the design decisions in this document 741 are driven by a desire to stay compatible with it. 743 In HTML, the link element can be mapped to links as specified here by 744 using the "href" attribute for the target URI, and "rel" to convey 745 the relation type, as in the Link header field. The context of the 746 link is the URI associated with the entire HTML document. 748 All of the link relation types defined by HTML have been included in 749 the Link Relation Type registry, so they can be used without 750 modification. However, there are several potential ways to serialise 751 extension relation types into HTML, including: 753 o As absolute URIs, 755 o using the RDFa [W3C.REC-html-rdfa-20150317] convention of mapping 756 token prefixes to URIs (in a manner similar to XML name spaces). 758 Individual applications of linking will therefore need to define how 759 their extension links should be serialised into HTML. 761 Surveys of existing HTML content have shown that unregistered link 762 relation types that are not URIs are (perhaps inevitably) common. 763 Consuming HTML implementations ought not consider such unregistered 764 short links to be errors, but rather relation types with a local 765 scope (i.e., their meaning is specific and perhaps private to that 766 document). 768 HTML also defines several attributes on links that can be seen as 769 target attributes, including "media", "hreflang", "type" and "sizes". 771 Finally, the HTML specification gives a special meaning when the 772 "alternate" and "stylesheet" relation types coincide in the same 773 link. Such links ought to be serialised in the Link header field 774 using a single list of relation-types (e.g., rel="alternate 775 stylesheet") to preserve this relationship. 777 A.2. Link Serialisation in Atom 779 Atom [RFC4287] is a link serialisation that conveys links in the 780 atom:link element, with the "href" attribute indicating the link 781 target and the "rel" attribute containing the relation type. The 782 context of the link is either a feed locator or an entry ID, 783 depending on where it appears; generally, feed-level links are 784 obvious candidates for transmission as a Link header field. 786 When serialising an atom:link into a Link header field, it is 787 necessary to convert link targets (if used) to URIs. 789 Atom defines extension relation types in terms of IRIs. This 790 specification re-defines them as URIs, to simplify and reduce errors 791 in their comparison. 793 Atom allows registered link relation types to be serialised as 794 absolute URIs using a prefix, "http://www.iana.org/assignments/ 795 relation/". This prefix is specific to the Atom serialisation. 797 Furthermore, link relation types are always compared in a case- 798 sensitive fashion; therefore, registered link relation types SHOULD 799 be converted to their registered form (usually, lowercase) when 800 serialised in an Atom document. 802 Note also that while the Link header field allows multiple relations 803 to be serialised in a single link, atom:link does not. In this case, 804 a single link-value may map to several atom:link elements. 806 As with HTML, atom:link defines some attributes that are not 807 explicitly mirrored in the Link header field syntax, but they can 808 also be used as link-extensions to maintain fidelity. 810 Appendix B. Algorithm for Parsing Link Headers 812 Given a HTTP header field-value "field_value" as a string assuming 813 ASCII encoding, the following algorithm can be used to parse it into 814 the model described by this specification: 816 1. Let "links" be an empty list. 818 2. Create "link_strings" by splitting "field_value" on "," 819 characters, excepting "," characters within quoted strings as per 820 [RFC7230], Section 3.2.6, or which form part of link's URI- 821 Reference (i.e. between "<" and ">" characters where the "<" is 822 immediately preceded by OWS and either a "," character or the 823 beginning of the "field_value" string). 825 3. For each "link_string" in "link_strings": 827 1. Let "target_string" be the string between the first "<" and 828 first ">" characters in "link_string". If they do not 829 appear, or do not appear in that order, fail parsing. 831 2. Let "rest" be the remaining characters (if any) after the 832 first ">" character in "link_string". 834 3. Split "rest" into an array of strings "parameter_strings", 835 on the ";" character, excepting ";" characters within quoted 836 strings as per [RFC7230], Section 3.2.6. 838 4. Let "link_parameters" be an empty array. 840 5. For each item "parameter" in "parameter_strings": 842 1. Remove OWS from the beginning and end of "parameter". 844 2. Skip this item if "parameter" matches the empty string 845 (""). 847 3. Split "parameter" into "param_name" and "param_value" on 848 the first "=" character. If "parameter" does not 849 contain "=", let "param_name" be "parameter" and 850 "param_value" be null. 852 4. Remove OWS from the end of "param_name" and the 853 beginning of "param_value". 855 5. Case-normalise "param_name" to lowercase. 857 6. If the first and last characters of "param_value" are 858 both DQUOTE: 860 1. Remove the first and last characters of 861 "param_value". 863 2. Replace quoted-pairs within "param_value" with the 864 octet following the backslash, as per [RFC7230], 865 Section 3.2.6. 867 7. If the last character of "param_name" is an asterisk 868 ("*"), decode "param_value" according to 869 [I-D.ietf-httpbis-rfc5987bis]. Skip this item if an 870 unrecoverable error is encountered. 872 8. Append the tuple ("param_name", "param_value") to 873 "link_parameters". 875 6. Let "target" be the result of relatively resolving (as per 876 [RFC3986], Section 5.2) "target_string". Note that any base 877 URI carried in the payload body is NOT used. 879 7. Let "relations_string" be the second item of the first tuple 880 of "link_parameters" whose first item matches the string 881 "rel", or the empty string ("") if it is not present. 883 8. Split "relations_string" into an array of strings 884 "relation_types", on RWS (removing all whitespace in the 885 process). 887 9. Let "context_string" be the second item of the first tuple 888 of "link_parameters" whose first item matches the string 889 "anchor". If it is not present, "context_string" is the 890 identity of the representation carrying the Link header 891 [RFC7231], Section 3.1.4.1, serialised as a URI. Where the 892 identity is "anonymous" "context_string" is null. 894 10. Let "context" be the result of relatively resolving (as per 895 [RFC3986], Section 5.2) "context_string", unless 896 "context_string" is null in which case "context" is null. 897 Note that any base URI carried in the payload body is NOT 898 used. 900 11. Let "target_attributes" be an empty array. 902 12. For each tuple ("param_name", "param_value") of 903 "link_parameters": 905 1. If "param_name" matches "rel" or "anchor", skip this 906 tuple. 908 2. If "param_name" matches "media", "title", "title*" or 909 "type" and "target_attributes" already contains a tuple 910 whose first element matches the value of "param_name", 911 skip this tuple. 913 3. Append ("param_name", "param_value") to 914 "target_attributes". 916 13. Let "star_param_names" be the set of "param_name"s in the 917 ("param_name", "param_value") tuples of "link_parameters" 918 where the last character of "param_name" is an asterisk 919 ("*"). 921 14. For each "star_param_name" in "star_param_names": 923 1. Let "base_param_name" be "star_param_name" with the last 924 character removed. 926 2. If the implementation does not choose to support an 927 internationalised form of a parameter named 928 "base_param_name" for any reason (including, but not 929 limited to, it being prohibited by the parameter's 930 specification), remove all tuples from "link_parameters" 931 whose first member is "star_param_name" and skip to the 932 next "star_param_name". 934 3. Remove all tuples from "link_parameters" whose first 935 member is "base_param_name". 937 4. Change the first member of all tuples in 938 "link_parameters" whose first member is 939 "star_param_name" to "base_param_name". 941 15. For each "relation_type" in "relation_types": 943 1. Case-normalise "relation_type" to lowercase. 945 2. Append a link object to "links" with the target 946 "target", relation type of "relation_type", context of 947 "context", and target attributes "target_attributes". 949 4. Return "links". 951 Appendix C. Changes from RFC5988 953 This specification has the following differences from its 954 predecessor, RFC5988: 956 o The initial relation type registrations were removed, since 957 they've already been registered by 5988. 959 o The introduction has been shortened. 961 o The Link Relation Application Data Registry has been removed. 963 o Incorporated errata. 965 o Updated references. 967 o Link cardinality was clarified. 969 o Terminology was changed from "target IRI" and "context IRI" to 970 "link target" and "link context" respectively. 972 o Made assigning a URI to registered relation types serialisation- 973 specific. 975 o Removed misleading statement that the link header field is 976 semantically equivalent to HTML and Atom links. 978 o More carefully defined how the Experts and IANA should interact. 980 o More carefully defined and used "link serialisations" and "link 981 applications." 983 o Clarified the cardinality of target attributes (generically and 984 for "type"). 986 o Corrected the default link context for the Link header field, to 987 be dependent upon the identity of the representation (as per 988 RFC7231). 990 o Defined a suggested parsing algorithm for the Link header. 992 o The value space of target attributes and their definition has been 993 specified. 995 o The ABNF has been updated to be compatible with [RFC7230]. In 996 particular, whitespace is now explicit. 998 o Some parameters on the HTTP header field can now appear as a 999 token. 1001 o Handling of quoted strings is now defined by [RFC7230]. 1003 o The "type" header field parameter now needs to be quoted (as 1004 "token" does not allow "/"). 1006 Author's Address 1008 Mark Nottingham 1010 EMail: mnot@mnot.net 1011 URI: https://www.mnot.net/