idnits 2.17.1 draft-nottingham-rfc5988bis-06.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 (June 6, 2017) is 2509 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) ** 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 2818 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft June 6, 2017 4 Obsoletes: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: December 8, 2017 8 Web Linking 9 draft-nottingham-rfc5988bis-06 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 December 8, 2017. 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 . . . . . . . . . . . . . 15 101 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 102 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 103 7.2. Informative References . . . . . . . . . . . . . . . . . 17 104 Appendix A. Notes on Other Link Serialisations . . . . . . . . . 18 105 A.1. Link Serialisation in HTML . . . . . . . . . . . . . . . 18 106 A.2. Link Serialisation in Atom . . . . . . . . . . . . . . . 18 107 Appendix B. Algorithms for Parsing Link Header Fields . . . . . 19 108 B.1. Parsing a Header Set for Links . . . . . . . . . . . . . 19 109 B.2. Parsing a Link Field Value . . . . . . . . . . . . . . . 20 110 B.3. Parsing Parameters . . . . . . . . . . . . . . . . . . . 22 111 B.4. Parsing a Quoted String . . . . . . . . . . . . . . . . . 23 112 Appendix C. Changes from RFC5988 . . . . . . . . . . . . . . . . 24 113 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 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],[I-D.leiba-rfc2119-update] when, and only when, they 135 appear in all 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 on the advice of a Designated Expert 297 (appointed by the IESG or their delegate), with a Specification 298 Required (using terminology from Section 4.1 of [RFC5226]). 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 Experts 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. Individual "link-param"s specify 385 their syntax in terms of the value after any necessary unquoting (as 386 per [RFC7230], Section 3.2.6). 388 This specification defines the link-params "rel", "anchor", "rev", 389 "hreflang", "media", "title", "title*", and "type"; see Section 3.2, 390 Section 3.3 and Section 3.4. 392 3.1. Link Target 394 Each link-value conveys one target IRI as a URI-Reference (after 395 conversion to one, if necessary; see [RFC3987], Section 3.1) inside 396 angle brackets ("<>"). If the URI-Reference is relative, parsers 397 MUST resolve it as per [RFC3986], Section 5. Note that any base IRI 398 appearing in the message's content is not applied. 400 3.2. Link Context 402 By default, the context of a link conveyed in the Link header field 403 is the URL of the representation it is associated with, as defined in 404 [RFC7231], Section 3.1.4.1, serialised as a URI. 406 When present, the anchor parameter overrides this with another URI, 407 such as a fragment of this resource, or a third resource (i.e., when 408 the anchor value is an absolute URI). If the anchor parameter's 409 value is a relative URI, parsers MUST resolve it as per [RFC3986], 410 Section 5. Note that any base URI from the body's content is not 411 applied. 413 The ABNF for the "anchor" parameter's value is: 415 URI-Reference ; Section 4.1 of {{RFC3986}} 417 Link application can choose to ignore links with an anchor parameter. 418 For example, the application in use might not allow the link context 419 to be assigned to a different resource. In such cases, the entire 420 link is to be ignored; link applications MUST NOT process the link 421 without applying the anchor. 423 Note that depending on HTTP status code and response headers, the 424 link context might be "anonymous" (i.e., no link context is 425 available). For example, this is the case on a 404 response to a GET 426 request. 428 3.3. Relation Type 430 The relation type of a link conveyed in the Link header field is 431 conveyed in the "rel" parameter's value. The "rel" parameter MUST 432 NOT appear more than once in a given link-value; occurrences after 433 the first MUST be ignored by parsers. 435 The "rev" parameter has been used in the past to indicate that the 436 semantics of the relationship are in the reverse direction. That is, 437 a link from A to B with REL="X" expresses the same relationship as a 438 link from B to A with REV="X". "rev" is deprecated by this 439 specification because it often confuses authors and readers; in most 440 cases, using a separate relation type is preferable. 442 The ABNF for the "rel" and "rev" parameters' values is: 444 relation-type *( 1*SP relation-type ) 446 where: 448 relation-type = reg-rel-type / ext-rel-type 449 reg-rel-type = LOALPHA *( LOALPHA / DIGIT / "." / "-" ) 450 ext-rel-type = URI ; Section 3 of {{RFC3986}} 452 Note that extension relation types are REQUIRED to be absolute URIs 453 in Link header fields, and MUST be quoted when they contain 454 characters not allowed in tokens, such as semicolon (";") or comma 455 (",") (as these characters are used as delimiters in the header field 456 itself). 458 3.4. Target Attributes 460 The Link header field defines several target attributes specific to 461 this serialisation, and also allows extension target attributes. 462 Target attributes are serialised in the Link header field as 463 parameters (see [RFC7231], Section 3.1.1.1 for the definition of 464 their syntax). 466 3.4.1. Serialisation-Defined Attributes 468 The "hreflang", "media", "title", "title*", and "type" link-params 469 can be translated to serialisation-defined target attributes for the 470 link. 472 The "hreflang" attribute, when present, is a hint indicating what the 473 language of the result of dereferencing the link should be. Note 474 that this is only a hint; for example, it does not override the 475 Content-Language header field of a HTTP response obtained by actually 476 following the link. Multiple "hreflang" attributes on a single link- 477 value indicate that multiple languages are available from the 478 indicated resource. 480 The ABNF for the "hreflang" parameter's value is: 482 Language-Tag 484 The "media" attribute, when present, is used to indicate intended 485 destination medium or media for style information (see 486 [W3C.REC-html5-20141028], Section 4.2.4). Its value MUST be quoted 487 if it contains a semicolon (";") or comma (","). There MUST NOT be 488 more than one "media" attribute in a link-value; occurrences after 489 the first MUST be ignored by parsers. 491 The ABNF for the "media" parameter's value is: 493 media-query-list 495 The "title" attribute, when present, is used to label the destination 496 of a link such that it can be used as a human-readable identifier 497 (e.g., a menu entry) in the language indicated by the Content- 498 Language header field (if present). The "title" attribute MUST NOT 499 appear more than once in a given link; occurrences after the first 500 MUST be ignored by parsers. 502 The "title*" link-param can be used to encode this attribute in a 503 different character set, and/or contain language information as per 504 [I-D.ietf-httpbis-rfc5987bis]. The "title*" link-param MUST NOT 505 appear more than once in a given link-value; occurrences after the 506 first MUST be ignored by parsers. If the attribute does not contain 507 language information, its language is indicated by the Content- 508 Language header field (when present). 510 If both the "title" and "title*" link-param appear in a link, 511 applications SHOULD use the "title*" link-param's value for the 512 "title" attribute. 514 The "type" attribute, when present, is a hint indicating what the 515 media type of the result of dereferencing the link should be. Note 516 that this is only a hint; for example, it does not override the 517 Content-Type header field of a HTTP response obtained by actually 518 following the link. The "type" attribute MUST NOT appear more than 519 once in a given link-value; occurrences after the first MUST be 520 ignored by parsers. 522 The ABNF for the "type" parameter's value is: 524 type-name "/" subtype-name ; see {{RFC6838}}, Section 4.2 526 3.4.2. Extension Attributes 528 Other link-params are link-extensions, and are to be considered as 529 target attributes. 531 Such target attributes MAY be defined to use the encoding in 532 [I-D.ietf-httpbis-rfc5987bis] (e.g., "example" and "example*"). When 533 both forms are present, they SHOULD be considered to be the same 534 target attribute; applications SHOULD use the value of the name 535 ending in "*" (after [I-D.ietf-httpbis-rfc5987bis] decoding), but MAY 536 fall back to the other value if there is an error in decoding it, or 537 if they do not support decoding. 539 3.5. Link Header Field Examples 541 For example: 543 Link: ; rel="previous"; 544 title="previous chapter" 546 indicates that "chapter2" is previous to this resource in a logical 547 navigation path. 549 Similarly, 551 Link: ; rel="http://example.net/foo" 553 indicates that the root resource ("/") is related to this resource 554 with the extension relation type "http://example.net/foo". 556 This link: 558 Link: ; rel="copyright"; anchor="#foo" 560 indicates that the linked copyright terms only apply to the portion 561 of the document indicated by the (media type-specific) fragment 562 identifier "foo". 564 The example below shows an instance of the Link header field encoding 565 multiple links, and also the use of RFC 5987 encoding to encode both 566 non-ASCII characters and language information. 568 Link: ; 569 rel="previous"; title*=UTF-8'de'letztes%20Kapitel, 570 ; 571 rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel 573 Here, both links have titles encoded in UTF-8, use the German 574 language ("de"), and the second link contains the Unicode code point 575 U+00E4 ("LATIN SMALL LETTER A WITH DIAERESIS"). 577 Note that link-values can convey multiple links between the same link 578 target and link context; for example: 580 Link: ; 581 rel="start http://example.net/relation/other" 583 Here, the link to "http://example.org/" has the registered relation 584 type "start" and the extension relation type 585 "http://example.net/relation/other". 587 Finally, this header field: 589 Link: ; rel="start", 590 ; rel="index" 592 is equivalent to these: 594 Link: ; rel="start" 595 Link: ; rel="index" 597 4. IANA Considerations 599 4.1. Link HTTP Header Field Registration 601 This specification updates the Message Header registry entry for 602 "Link" in HTTP [RFC3864] to refer to this document. 604 Header field: Link 605 Applicable protocol: http 606 Status: standard 607 Author/change controller: 608 IETF (iesg@ietf.org) 609 Internet Engineering Task Force 610 Specification document(s): 611 [this document] 613 4.2. Link Relation Type Registry 615 This specification updates the registration procedures for the Link 616 Relation Type registry; see Section 2.1.1.1. The Expert(s) and IANA 617 are expected interact as outlined below. 619 The Expert(s) will provide registry data to IANA in a mutually-agreed 620 form (e.g. a specific XML format). IANA will publish: 622 o The raw registry data 624 o The registry data, transformed into HTML 626 o The registry data alternative formats provided by the Expert(s) 627 (if any) 629 If IANA's internal processes require making changes to registry data 630 and/or adding registry entries, IANA will inform the Expert(s) of 631 this in a mutually agreed way. 633 Each published document will be at a URL mutually agreed to by IANA 634 and the Expert(s), and IANA will set HTTP response headers on them as 635 (reasonably) requested by the Expert(s). 637 Additionally, the HTML generated by IANA will: 639 o Take directions from the Expert(s) as to the content of the HTML 640 page's introductory text 642 o Include a stable HTML fragment identifier for each registered link 643 relation 645 All registry data documents MUST include Simplified BSD License text 646 as described in Section 4.e of the Trust Legal Provisions 647 (). 649 IANA will direct any incoming requests regarding the registry to this 650 document and, if defined, the processes established by the Expert(s); 651 typically, this will mean referring them to the registry Web page. 653 Note that the Expert(s) are allowed (as per Section 2.1.1.1) to 654 define additional fields to be collected in the registry. 656 4.3. Link Relation Application Data Registry 658 This specification terminates the Link Relation Application Data 659 Registry, as it has not been used, and future use is not anticipated. 660 IANA is instructed to remove it. 662 5. Security Considerations 664 The content of the Link header field is not secure, private or 665 integrity-guaranteed. Use of Transport Layer Security (TLS) with 666 HTTP ([RFC2818]) is currently the only end-to-end way to provide 667 these properties. 669 Link applications ought to consider the attack vectors opened by 670 automatically following, trusting, or otherwise using links gathered 671 from HTTP header fields. In particular, Link header fields that use 672 the "anchor" parameter to associate a link's context with another 673 resource are to be treated with due caution. 675 The Link header field makes extensive use of IRIs and URIs. See 676 [RFC3987] Section 8 for security considerations relating to IRIs. 677 See [RFC3986] Section 7 for security considerations relating to URIs. 678 See [RFC7230] Section 9 for security considerations relating to HTTP 679 header fields. 681 6. Internationalisation Considerations 683 Link targets may need to be converted to URIs in order to express 684 them in serialisations that do not support IRIs. This includes the 685 Link HTTP header field. 687 Similarly, the anchor parameter of the Link header field does not 688 support IRIs, and therefore IRIs must be converted to URIs before 689 inclusion there. 691 Relation types are defined as URIs, not IRIs, to aid in their 692 comparison. It is not expected that they will be displayed to end 693 users. 695 Note that registered Relation Names are required to be lower-case 696 ASCII letters. 698 7. References 700 7.1. Normative References 702 [I-D.ietf-httpbis-rfc5987bis] 703 Reschke, J., "Indicating Character Encoding and Language 704 for HTTP Header Field Parameters", draft-ietf-httpbis- 705 rfc5987bis-05 (work in progress), February 2017. 707 [I-D.leiba-rfc2119-update] 708 Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 709 2119 Key Words", draft-leiba-rfc2119-update-02 (work in 710 progress), March 2017. 712 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 713 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 714 RFC2119, March 1997, 715 . 717 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 718 Procedures for Message Header Fields", BCP 90, RFC 3864, 719 DOI 10.17487/RFC3864, September 2004, 720 . 722 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 723 Resource Identifier (URI): Generic Syntax", STD 66, RFC 724 3986, DOI 10.17487/RFC3986, January 2005, 725 . 727 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 728 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 729 January 2005, . 731 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 732 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 733 DOI 10.17487/RFC5226, May 2008, 734 . 736 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 737 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 738 September 2009, . 740 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 741 Specifications and Registration Procedures", BCP 13, RFC 742 6838, DOI 10.17487/RFC6838, January 2013, 743 . 745 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 746 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 747 7230, DOI 10.17487/RFC7230, June 2014, 748 . 750 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 751 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 752 10.17487/RFC7231, June 2014, 753 . 755 [W3C.REC-css3-mediaqueries-20120619] 756 Rivoal, F., "Media Queries", World Wide Web Consortium 757 Recommendation REC-css3-mediaqueries-20120619, June 2012, 758 . 761 7.2. Informative References 763 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 764 Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 765 10.17487/RFC2046, November 1996, 766 . 768 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/ 769 RFC2818, May 2000, 770 . 772 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 773 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 774 December 2005, . 776 [W3C.REC-html5-20141028] 777 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 778 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 779 World Wide Web Consortium Recommendation REC- 780 html5-20141028, October 2014, 781 . 783 Appendix A. Notes on Other Link Serialisations 785 Header fields (Section 3) are only one serialisation of links; other 786 specifications have defined alternative serialisations. 788 A.1. Link Serialisation in HTML 790 HTML motivated the original syntax of the Link header field, and many 791 of the design decisions in this document are driven by a desire to 792 stay compatible with it. 794 In HTML, the link element can be mapped to links as specified here by 795 using the "href" attribute for the target URI, and "rel" to convey 796 the relation type, as in the Link header field. The context of the 797 link is the URI associated with the entire HTML document. HTML also 798 defines several attributes on links that can be seen as target 799 attributes, including "media", "hreflang", "type" and "sizes". 801 Section 4.8 of HTML5 ([W3C.REC-html5-20141028]) defines modern HTML 802 links. That document links to the Microformats Wiki as a registry; 803 over time, the IANA registry ought to mirror its contents, and 804 ideally eventually replace it (although that depends on the HTML 805 community). 807 Surveys of existing HTML content have shown that unregistered link 808 relation types that are not URIs are (perhaps inevitably) common. 809 Consuming HTML implementations ought not consider such unregistered 810 short links to be errors, but rather relation types with a local 811 scope (i.e., their meaning is specific and perhaps private to that 812 document). 814 Finally, the HTML specification gives a special meaning when the 815 "alternate" relation types coincides with other relation types in the 816 same link. Such links ought to be serialised in the Link header 817 field using a single list of relation-types (e.g., rel="alternate 818 stylesheet") to preserve this relationship. 820 A.2. Link Serialisation in Atom 822 Atom [RFC4287] is a link serialisation that conveys links in the 823 atom:link element, with the "href" attribute indicating the link 824 target and the "rel" attribute containing the relation type. The 825 context of the link is either a feed locator or an entry ID, 826 depending on where it appears; generally, feed-level links are 827 obvious candidates for transmission as a Link header field. 829 When serialising an atom:link into a Link header field, it is 830 necessary to convert link targets (if used) to URIs. 832 Atom defines extension relation types in terms of IRIs. This 833 specification re-defines them as URIs, to simplify and reduce errors 834 in their comparison. 836 Atom allows registered link relation types to be serialised as 837 absolute URIs using a prefix, "http://www.iana.org/assignments/ 838 relation/". This prefix is specific to the Atom serialisation. 840 Furthermore, link relation types are always compared in a case- 841 sensitive fashion; therefore, registered link relation types SHOULD 842 be converted to their registered form (usually, lowercase) when 843 serialised in an Atom document. 845 Note also that while the Link header field allows multiple relations 846 to be serialised in a single link, atom:link does not. In this case, 847 a single link-value may map to several atom:link elements. 849 As with HTML, atom:link defines some attributes that are not 850 explicitly mirrored in the Link header field syntax, but they can 851 also be used as link-extensions to maintain fidelity. 853 Appendix B. Algorithms for Parsing Link Header Fields 855 This appendix outlines a set of non-normative algorithms: for parsing 856 the Link header(s) out of a header set, parsing a link header field 857 value, and algorithms for parsing generic parts of the field value. 859 These algorithms are more permissive than the ABNF defining the 860 syntax might suggest; the error handling embodied in them is a 861 reasonable approach, but not one that is required. As such they are 862 advisory only, and in cases where there is disagreement, the correct 863 behaviour is defined by the body of this specification. 865 B.1. Parsing a Header Set for Links 867 This algorithm can be used to parse the Link header fields that a 868 HTTP header set contains. Given a "header_set" of (string 869 "field_name", string "field_value") pairs, assuming ASCII encoding, 870 it returns a list of link objects. 872 1. Let "field_values" be a list containing the members of 873 "header_set" whose "field_name" is a case-insensitive match for 874 "link". 876 2. Let "links" be an empty list. 878 3. For each "field_value" in "field_values": 880 1. Let "value_links" be the result of _Parsing A Link Field 881 Value_ (Appendix B.2) from "field_value". 883 2. Append each member of "value_links" to "links". 885 4. Return "links". 887 B.2. Parsing a Link Field Value 889 This algorithm parses zero or more comma-separated link-values from a 890 Link header field. Given a string "field_value", assuming ASCII 891 encoding, it returns a list of link objects. 893 1. Let "links" be an empty list. 895 2. While "field_value" has content: 897 1. Consume any leading OWS. 899 2. If the first character is not "<", return "links". 901 3. Discard the first character ("<"). 903 4. Consume up to but not including the first ">" character or 904 end of "field_value" and let the result be "target_string". 906 5. If the next character is not ">", return "links". 908 6. Discard the leading ">" character. 910 7. Let "link_parameters", be the result of _Parsing Parameters_ 911 (Appendix B.3) from "field_value" (consuming zero or more 912 characters of it). 914 8. Let "target" be the result of relatively resolving (as per 915 [RFC3986], Section 5.2) "target_string". Note that any base 916 URI carried in the payload body is NOT used. 918 9. Let "relations_string" be the second item of the first tuple 919 of "link_parameters" whose first item matches the string 920 "rel", or the empty string ("") if it is not present. 922 10. Split "relations_string" on RWS (removing it in the process) 923 into a list of strings "relation_types". 925 11. Let "context_string" be the second item of the first tuple 926 of "link_parameters" whose first item matches the string 927 "anchor". If it is not present, "context_string" is the URL 928 of the representation carrying the Link header [RFC7231], 929 Section 3.1.4.1, serialised as a URI. Where the URL is 930 anonymous, "context_string" is null. 932 12. Let "context" be the result of relatively resolving (as per 933 [RFC3986], Section 5.2) "context_string", unless 934 "context_string" is null in which case "context" is null. 935 Note that any base URI carried in the payload body is NOT 936 used. 938 13. Let "target_attributes" be an empty list. 940 14. For each tuple ("param_name", "param_value") of 941 "link_parameters": 943 1. If "param_name" matches "rel" or "anchor", skip this 944 tuple. 946 2. If "param_name" matches "media", "title", "title*" or 947 "type" and "target_attributes" already contains a tuple 948 whose first element matches the value of "param_name", 949 skip this tuple. 951 3. Append ("param_name", "param_value") to 952 "target_attributes". 954 15. Let "star_param_names" be the set of "param_name"s in the 955 ("param_name", "param_value") tuples of "link_parameters" 956 where the last character of "param_name" is an asterisk 957 ("*"). 959 16. For each "star_param_name" in "star_param_names": 961 1. Let "base_param_name" be "star_param_name" with the last 962 character removed. 964 2. If the implementation does not choose to support an 965 internationalised form of a parameter named 966 "base_param_name" for any reason (including, but not 967 limited to, it being prohibited by the parameter's 968 specification), remove all tuples from "link_parameters" 969 whose first member is "star_param_name" and skip to the 970 next "star_param_name". 972 3. Remove all tuples from "link_parameters" whose first 973 member is "base_param_name". 975 4. Change the first member of all tuples in 976 "link_parameters" whose first member is 977 "star_param_name" to "base_param_name". 979 17. For each "relation_type" in "relation_types": 981 1. Case-normalise "relation_type" to lowercase. 983 2. Append a link object to "links" with the target 984 "target", relation type of "relation_type", context of 985 "context", and target attributes "target_attributes". 987 3. Return "links". 989 B.3. Parsing Parameters 991 This algorithm parses the parameters from a header field value. 992 Given an ASCII string "input", it returns a list of (string 993 "parameter_name", string "parameter_value") tuples that it contains. 994 "input" is modified to remove the parsed parameters. 996 1. Let "parameters" be an empty list. 998 2. While "input" has content: 1000 1. Consume any leading OWS. 1002 2. If the first character is not ";", return "parameters". 1004 3. Discard the leading ";" character. 1006 4. Consume any leading OWS. 1008 5. Consume up to but not including the first BWS, "=", ";", "," 1009 character or end of "input" and let the result be 1010 "parameter_name". 1012 6. Consume any leading BWS. 1014 7. If the next character is "=": 1016 1. Discard the leading "=" character. 1018 2. Consume any leading BWS. 1020 3. If the next character is DQUOTE, let "parameter_value" 1021 be the result of _Parsing a Quoted String_ 1022 (Appendix B.4) from "input" (consuming zero or more 1023 characters of it). 1025 4. Else, consume the contents up to but not including the 1026 first ";", "," character or end of "input" and let the 1027 results be "parameter_value". 1029 5. If the last character of "parameter_name" is an asterisk 1030 ("*"), decode "parameter_value" according to 1031 [I-D.ietf-httpbis-rfc5987bis]. Continue processing 1032 "input" if an unrecoverable error is encountered. 1034 8. Else: 1036 1. Let "parameter_value" be an empty string. 1038 9. Case-normalise "parameter_name" to lowercase. 1040 10. Append ("parameter_name", "parameter_value") to 1041 "parameters". 1043 11. Consume any leading OWS. 1045 12. If the next character is "," or the end of "input", stop 1046 processing "input" and return "parameters". 1048 B.4. Parsing a Quoted String 1050 This algorithm parses a quoted string, as per [RFC7230], 1051 Section 3.2.6. Given an ASCII string "input", it returns an unquoted 1052 string. "input" is modified to remove the parsed string. 1054 1. Let "output" be an empty string. 1056 2. If the first character of "input" is not DQUOTE, return "output". 1058 3. Discard the first character. 1060 4. While "input" has content: 1062 1. If the first character is a backslash ("\"): 1064 1. Discard the first character. 1066 2. If there is no more "input", return "output". 1068 3. Else, consume the first character and append it to 1069 "output". 1071 2. Else, if the first character is DQUOTE, discard it and return 1072 "output". 1074 3. Else, consume the first character and append it to "output". 1076 5. Return "output". 1078 Appendix C. Changes from RFC5988 1080 This specification has the following differences from its 1081 predecessor, RFC5988: 1083 o The initial relation type registrations were removed, since 1084 they've already been registered by 5988. 1086 o The introduction has been shortened. 1088 o The Link Relation Application Data Registry has been removed. 1090 o Incorporated errata. 1092 o Updated references. 1094 o Link cardinality was clarified. 1096 o Terminology was changed from "target IRI" and "context IRI" to 1097 "link target" and "link context" respectively. 1099 o Made assigning a URI to registered relation types serialisation- 1100 specific. 1102 o Removed misleading statement that the link header field is 1103 semantically equivalent to HTML and Atom links. 1105 o More carefully defined how the Experts and IANA should interact. 1107 o More carefully defined and used "link serialisations" and "link 1108 applications." 1110 o Clarified the cardinality of target attributes (generically and 1111 for "type"). 1113 o Corrected the default link context for the Link header field, to 1114 be dependent upon the identity of the representation (as per 1115 RFC7231). 1117 o Defined a suggested parsing algorithm for the Link header. 1119 o The value space of target attributes and their definition has been 1120 specified. 1122 o The ABNF has been updated to be compatible with [RFC7230]. In 1123 particular, whitespace is now explicit. 1125 o Some parameters on the HTTP header field can now appear as a 1126 token. 1128 o Handling of quoted strings is now defined by [RFC7230]. 1130 o The "type" header field parameter now needs to be quoted (as 1131 "token" does not allow "/"). 1133 Author's Address 1135 Mark Nottingham 1137 EMail: mnot@mnot.net 1138 URI: https://www.mnot.net/