idnits 2.17.1 draft-nottingham-rfc5988bis-05.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 (April 19, 2017) is 2561 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 April 19, 2017 4 Obsoletes: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: October 21, 2017 8 Web Linking 9 draft-nottingham-rfc5988bis-05 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 October 21, 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 2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 82 2.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 5 83 2.1.1. Registered Relation Types . . . . . . . . . . . . . . 5 84 2.1.2. Extension Relation Types . . . . . . . . . . . . . . 7 85 2.2. Target Attributes . . . . . . . . . . . . . . . . . . . . 7 86 3. Link Serialisation in HTTP Headers . . . . . . . . . . . . . 8 87 3.1. Link Target . . . . . . . . . . . . . . . . . . . . . . . 8 88 3.2. Link Context . . . . . . . . . . . . . . . . . . . . . . 9 89 3.3. Relation Type . . . . . . . . . . . . . . . . . . . . . . 9 90 3.4. Target Attributes . . . . . . . . . . . . . . . . . . . . 10 91 3.4.1. Serialisation-Defined Attributes . . . . . . . . . . 10 92 3.4.2. Extension Attributes . . . . . . . . . . . . . . . . 11 93 3.5. Link Header Field Examples . . . . . . . . . . . . . . . 11 94 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 95 4.1. Link HTTP Header Field Registration . . . . . . . . . . . 13 96 4.2. Link Relation Type Registry . . . . . . . . . . . . . . . 13 97 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 98 6. Internationalisation Considerations . . . . . . . . . . . . . 14 99 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 100 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 101 7.2. Informative References . . . . . . . . . . . . . . . . . 16 102 Appendix A. Notes on Other Link Serialisations . . . . . . . . . 17 103 A.1. Link Serialisation in HTML . . . . . . . . . . . . . . . 17 104 A.2. Link Serialisation in Atom . . . . . . . . . . . . . . . 17 105 Appendix B. Algorithm for Parsing Link Headers . . . . . . . . . 18 106 Appendix C. Changes from RFC5988 . . . . . . . . . . . . . . . . 21 107 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 109 1. Introduction 111 This specification defines a model for indicate the relationships 112 between resources on the Web ("links") and the type of those 113 relationships ("link relation types"). 115 HTML [W3C.REC-html5-20141028] and Atom [RFC4287] both have well- 116 defined concepts of linking; Section 2 generalises this into a 117 framework that encompasses linking in these formats and (potentially) 118 elsewhere. 120 Furthermore, Section 3 defines an HTTP header field for conveying 121 such links. 123 1.1. Notational Conventions 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 127 document are to be interpreted as described in BCP 14, [RFC2119], as 128 scoped to those conformance targets. 130 This document uses the Augmented Backus-Naur Form (ABNF) notation of 131 [RFC7230], including the #rule, and explicitly includes the following 132 rules from it: quoted-string, token, SP (space), BWS (bad 133 whitespace), OWS (optional whitespace), RWS (required whitespace) 134 LOALPHA, DIGIT. 136 Additionally, the following rules are included from [RFC3986]: URI 137 and URI-Reference; from [RFC6838]: type-name and subtype-name; from 138 [W3C.CR-css3-mediaqueries-20090915]: media_query_list; and from 139 [RFC5646]: Language-Tag. 141 2. Links 143 In this specification, a link is a typed connection between two 144 resources, and is comprised of: 146 o A _link context_, 148 o a _link relation type_ (Section 2.1), 150 o a _link target_, and 152 o optionally, _target attributes_ (Section 2.2). 154 A link can be viewed as a statement of the form "_link context_ has a 155 _link relation type_ resource at _link target_, which has _target 156 attributes_". 158 Link contexts and link targets are both IRIs [RFC3987]. However, in 159 the common case, the link context will also be a URI [RFC3986], 160 because many protocols (such as HTTP) do not support dereferencing 161 IRIs. Likewise, the link target will be sometimes be converted to a 162 URI (see [RFC3987], Section 3.1) in serialisations that do not 163 support IRIs (such as the Link header field defined in Section 3). 165 This specification does not place restrictions on the cardinality of 166 links; there can be multiple links to and from a particular target, 167 and multiple links of the same or different types between a given 168 context and target. Likewise, the relative ordering of links in any 169 particular serialisation, or between serialisations (e.g., the Link 170 header field and in-content links) is not specified or significant in 171 this specification; applications that wish to consider ordering 172 significant can do so. 174 Links are conveyed in _link serialisations_; they are the "bytes on 175 the wire", and can occur in various forms. For example, Atom 176 [RFC4287] and HTML [W3C.REC-html5-20141028] both defined 177 serialisations of links into their respective formats, and Section 3 178 defines how to serialise links in HTTP header fields. 180 This specification does not define a general syntax for links across 181 different serialisations, nor does it mandate a specific context for 182 any given link; it is expected that serialisations of links will 183 specify both aspects. 185 Finally, links are consumed by _link applications_. Generally, an 186 application will define the link relation type(s) it uses, along with 187 the serialisation(s) 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, whereas the application 190 "AtomPub" uses the "edit" and "edit-media" link relations. 192 2.1. Link Relation Types 194 In the simplest case, a link relation type identifies the semantics 195 of a link. For example, a link with the relation type "copyright" 196 indicates that the current link context has a copyright resource at 197 the link target. 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 link 202 target can be used as part of a defined protocol (in this case, a 203 service 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 2.1.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 2.1.1.1. 224 Registered relation type names MUST conform to the reg-rel-type rule 225 (see Section 3.3), and MUST be compared character-by-character in a 226 case-insensitive fashion. They SHOULD be appropriate to the 227 specificity of the relation type; i.e., if the semantics are highly 228 specific to a particular application, the name should reflect that, 229 so that more 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 are required 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 2.1.1.1. Registering Link Relation Types 248 The link relations registry is located at 249 https://www.iana.org/assignments/link-relations/ . Registration 250 requests can be made by following the instructions located there, or 251 by sending an e-mail to the "link-relations@ietf.org" mailing list. 253 Registration requests consist of at least the following information: 255 o *Relation Name*: The name of the relation type 257 o *Description*: A short English description of the type's 258 semantics. It SHOULD be stated in terms of the relationship 259 between the link context and link target. 261 o *Reference*: Reference to the document that specifies the link 262 relation type, preferably including a URI that can be used to 263 retrieve a copy of the document. An indication of the relevant 264 section(s) MAY also be included, but is not required. 266 The Expert(s) MAY define additional fields to be collected in the 267 registry. 269 General requirements for registered relation types are described in 270 Section 2.1.1. 272 Registrations MUST reference a freely available, stable 273 specification. 275 Note that relation types can be registered by third parties 276 (including the Expert(s)), if the Expert(s) determine that an 277 unregistered relation type is widely deployed and not likely to be 278 registered in a timely manner. 280 2.1.1.2. Registration Request Processing 282 Relation types are registered on the advice of a Designated Expert 283 (appointed by the IESG or their delegate), with a Specification 284 Required (using terminology from [RFC5226]). 286 The goal of the registry is to reflect common use of links on the 287 Internet. Therefore, the Expert(s) SHOULD be strongly biased towards 288 approving registrations, unless they are abusive, frivolous, not 289 likely to be used on the Internet, or actively harmful to the 290 Internet and/or the Web (not merely aesthetically displeasing, or 291 architecturally dubious). As stated in Section 2.1.1, the Experts 292 MAY withhold registration of names that are too general for the 293 proposed application. 295 The Expert(s) MUST clearly identify any issues which cause a 296 registration to be refused. Advice about the semantics of a proposed 297 link relation type can be given, but if it does not block 298 registration, this SHOULD be explicitly stated. 300 When a request is approved, the Expert(s) will inform IANA, and the 301 registration will be processed. The IESG is the final arbiter of any 302 objection. 304 2.1.2. Extension Relation Types 306 Applications that don't wish to register a relation type can use an 307 extension relation type, which is a URI [RFC3986] that uniquely 308 identifies the relation type. Although the URI can point to a 309 resource that contains a definition of the semantics of the relation 310 type, clients SHOULD NOT automatically access that resource to avoid 311 overburdening its server. 313 The URI used for an extension relation type SHOULD be under the 314 control of the person or party defining it, or be delegated to them. 316 When extension relation types are compared, they MUST be compared as 317 strings (after converting to URIs if serialised in a different 318 format) in a case-insensitive fashion, character-by-character. 319 Because of this, all-lowercase URIs SHOULD be used for extension 320 relations. 322 Note that while extension relation types are required to be URIs, a 323 serialisation of links can specify that they are expressed in another 324 form, as long as they can be converted to URIs. 326 2.2. Target Attributes 328 _Target attributes_ are a list of key/value pairs that describe the 329 link or its target; for example, a media type hint. 331 They can be defined both by individual link relation types and by 332 link serialisations. 334 This specification does not attempt to coordinate the name of target 335 attributes, their cardinality or use. Serialisations SHOULD 336 coordinate their target attributes to avoid conflicts in semantics or 337 syntax. 339 The names of target attributes SHOULD conform to the token rule, but 340 SHOULD NOT include any of the characters "%", "'" or "*", for 341 portability across serializations, and MUST be compared in a case- 342 insensitive fashion. 344 Target attribute definitions SHOULD specify: 346 o The serialisation of their values into Unicode or a subset 347 thereof, to maximise their chances of portability across link 348 serialisations. 350 o The semantics and error handling of multiple occurrences of the 351 target attribute on a given link. 353 This specification does define target attributes for use in the Link 354 HTTP header field in Section 3.4. 356 3. Link Serialisation in HTTP Headers 358 The Link header field provides a means for serialising one or more 359 links into HTTP headers. 361 The ABNF for the field value is: 363 Link = #link-value 364 link-value = "<" URI-Reference ">" *( OWS ";" OWS link-param ) 365 link-param = token BWS "=" BWS ( token / quoted-string ) 367 Note that any "link-param" can be generated with values using either 368 the "token" or the "quoted-string" syntax, and therefore recipients 369 MUST be able to parse both forms. Individual "link-param"s specify 370 their syntax in terms of the value after any necessary unquoting (as 371 per [RFC7230], Section 3.2.6). 373 This specification defines the link-params "rel", "anchor", "rev", 374 "hreflang", "media", "title", "title*", and "type"; see Section 3.2, 375 Section 3.3 and Section 3.4. 377 3.1. Link Target 379 Each link-value conveys one target IRI as a URI-Reference (after 380 conversion to one, if necessary; see [RFC3987], Section 3.1) inside 381 angle brackets ("<>"). If the URI-Reference is relative, parsers 382 MUST resolve it as per [RFC3986], Section 5. Note that any base IRI 383 from the message's content is not applied. 385 3.2. Link Context 387 By default, the context of a link conveyed in the Link header field 388 is identity of the representation it is associated with, as defined 389 in [RFC7231], Section 3.1.4.1, serialised as a URI. 391 When present, the anchor parameter overrides this with another URI, 392 such as a fragment of this resource, or a third resource (i.e., when 393 the anchor value is an absolute URI). If the anchor parameter's 394 value is a relative URI, parsers MUST resolve it as per [RFC3986], 395 Section 5. Note that any base URI from the body's content is not 396 applied. 398 The ABNF for the "anchor" parameter's value is: 400 URI-Reference 402 Consuming implementations can choose to ignore links with an anchor 403 parameter. For example, the application in use might not allow the 404 link context to be assigned to a different resource. In such cases, 405 the entire link is to be ignored; consuming implementations MUST NOT 406 process the link without applying the anchor. 408 Note that depending on HTTP status code and response headers, the 409 link context might be "anonymous" (i.e., no link context is 410 available). For example, this is the case on a 404 response to a GET 411 request. 413 3.3. Relation Type 415 The relation type of a link conveyed in the Link header field is 416 conveyed in the "rel" parameter's value. The "rel" parameter MUST 417 NOT appear more than once in a given link-value; occurrences after 418 the first MUST be ignored by parsers. 420 The "rev" parameter has been used in the past to indicate that the 421 semantics of the relationship are in the reverse direction. That is, 422 a link from A to B with REL="X" expresses the same relationship as a 423 link from B to A with REV="X". "rev" is deprecated by this 424 specification because it often confuses authors and readers; in most 425 cases, using a separate relation type is preferable. 427 The ABNF for the "rel" and "rev" parameters' values is: 429 relation-type *( 1*SP relation-type ) 431 where: 433 relation-type = reg-rel-type | ext-rel-type 434 reg-rel-type = LOALPHA *( LOALPHA | DIGIT | "." | "-" ) 435 ext-rel-type = URI 437 Note that extension relation types are REQUIRED to be absolute URIs 438 in Link headers, and MUST be quoted if they contain a semicolon (";") 439 or comma (",") (as these characters are used as delimiters in the 440 header field itself). 442 3.4. Target Attributes 444 The Link header field defines several target attributes specific to 445 this serialisation, and also allows extension target attributes. 446 Target attributes are serialised in the Link header field as 447 parameters (see [RFC7231], Section 3.1.1.1 for the definition of 448 their syntax). 450 3.4.1. Serialisation-Defined Attributes 452 The "hreflang", "media", "title", "title*", and "type" link-params 453 can be translated to serialisation-defined target attributes for the 454 link. 456 The "hreflang" attribute, when present, is a hint indicating what the 457 language of the result of dereferencing the link should be. Note 458 that this is only a hint; for example, it does not override the 459 Content-Language header field of a HTTP response obtained by actually 460 following the link. Multiple "hreflang" attributes on a single link- 461 value indicate that multiple languages are available from the 462 indicated resource. 464 The ABNF for the "hreflang" parameter's value is: 466 Language-Tag 468 The "media" attribute, when present, is used to indicate intended 469 destination medium or media for style information (see 470 [W3C.REC-html5-20141028], Section 4.2.4). Its value MUST be quoted 471 if it contains a semicolon (";") or comma (","). There MUST NOT be 472 more than one "media" attribute in a link-value; occurrences after 473 the first MUST be ignored by parsers. 475 The ABNF for the "media" parameter's value is: 477 media_query_list 479 The "title" attribute, when present, is used to label the destination 480 of a link such that it can be used as a human-readable identifier 481 (e.g., a menu entry) in the language indicated by the Content- 482 Language header field (if present). The "title" attribute MUST NOT 483 appear more than once in a given link; occurrences after the first 484 MUST be ignored by parsers. 486 The "title*" link-param can be used to encode this attribute in a 487 different character set, and/or contain language information as per 488 [I-D.ietf-httpbis-rfc5987bis]. The "title*" link-param MUST NOT 489 appear more than once in a given link-value; occurrences after the 490 first MUST be ignored by parsers. If the attribute does not contain 491 language information, its language is indicated by the Content- 492 Language header field (when present). 494 If both the "title" and "title*" link-param appear in a link, 495 processors SHOULD use the "title*" link-param's value for the "title" 496 attribute. 498 The "type" attribute, when present, is a hint indicating what the 499 media type of the result of dereferencing the link should be. Note 500 that this is only a hint; for example, it does not override the 501 Content-Type header field of a HTTP response obtained by actually 502 following the link. The "type" attribute MUST NOT appear more than 503 once in a given link-value; occurrences after the first MUST be 504 ignored by parsers. 506 The ABNF for the "type" parameter's value is: 508 type-name "/" subtype-name 510 3.4.2. Extension Attributes 512 Other link-params are link-extensions, and are to be considered as 513 target attributes. 515 Such target attributes MAY be defined to use the encoding in 516 [I-D.ietf-httpbis-rfc5987bis] (e.g., "example" and "example*"). When 517 both forms are present, they SHOULD be considered to be the same 518 target attribute; processors SHOULD use the value of the name ending 519 in "*" (after [I-D.ietf-httpbis-rfc5987bis] decoding), but MAY fall 520 back to the other value if there is an error in decoding it, or if 521 they do not support decoding. 523 3.5. Link Header Field Examples 525 For example: 527 Link: ; rel="previous"; 528 title="previous chapter" 530 indicates that "chapter2" is previous to this resource in a logical 531 navigation path. 533 Similarly, 535 Link: ; rel="http://example.net/foo" 537 indicates that the root resource ("/") is related to this resource 538 with the extension relation type "http://example.net/foo". 540 This link: 542 Link: ; rel="copyright"; anchor="#foo" 544 indicates that the linked copyright terms only apply to the portion 545 of the document indicated by the (media type-specific) fragment 546 identifier "foo". 548 The example below shows an instance of the Link header field encoding 549 multiple links, and also the use of RFC 5987 encoding to encode both 550 non-ASCII characters and language information. 552 Link: ; 553 rel="previous"; title*=UTF-8'de'letztes%20Kapitel, 554 ; 555 rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel 557 Here, both links have titles encoded in UTF-8, use the German 558 language ("de"), and the second link contains the Unicode code point 559 U+00E4 ("LATIN SMALL LETTER A WITH DIAERESIS"). 561 Note that link-values can convey multiple links between the same link 562 target and link context; for example: 564 Link: ; 565 rel="start http://example.net/relation/other" 567 Here, the link to "http://example.org/" has the registered relation 568 type "start" and the extension relation type 569 "http://example.net/relation/other". 571 4. IANA Considerations 573 In addition to the actions below, IANA should terminate the Link 574 Relation Application Data Registry, as it has not been used, and 575 future use is not anticipated. 577 4.1. Link HTTP Header Field Registration 579 This specification updates the Message Header registry entry for 580 "Link" in HTTP [RFC3864] to refer to this document. 582 Header field: Link 583 Applicable protocol: http 584 Status: standard 585 Author/change controller: 586 IETF (iesg@ietf.org) 587 Internet Engineering Task Force 588 Specification document(s): 589 [RFC&rfc.number;] 591 4.2. Link Relation Type Registry 593 This specification updates the registration procedures for the Link 594 Relation Type registry; see Section 2.1.1.1. The Expert(s) and IANA 595 are expected interact as outlined below. 597 The Expert(s) will provide registry data to IANA in a mutually-agreed 598 form (e.g. a specific XML format). IANA will publish: 600 o The raw registry data 602 o The registry data, transformed into HTML 604 o The registry data alternative formats provided by the Expert(s) 605 (if any) 607 If IANA's internal processes require making changes to registry data 608 and/or adding registry entries, IANA will inform the Expert(s) of 609 this in a mutually agreed way. 611 Each published document will be at a URL mutually agreed to by IANA 612 and the Expert(s), and IANA will set HTTP response headers on them as 613 (reasonably) requested by the Expert(s). 615 Additionally, the HTML generated by IANA will: 617 o Take directions from the Expert(s) as to the content of the HTML 618 page's introductory text 620 o Include a stable HTML fragment identifier for each registered link 621 relation 623 All registry data documents MUST include Simplified BSD License text 624 as described in Section 4.e of the Trust Legal Provisions 625 (). 627 IANA will direct any incoming requests regarding the registry to this 628 document and, if defined, the processes established by the Expert(s); 629 typically, this will mean referring them to the registry Web page. 631 5. Security Considerations 633 The content of the Link header field is not secure, private or 634 integrity-guaranteed, and due caution should be exercised when using 635 it. Use of Transport Layer Security (TLS) with HTTP ([RFC2818] and 636 [RFC2817]) is currently the only end-to-end way to provide such 637 protection. 639 Link applications ought to consider the attack vectors opened by 640 automatically following, trusting, or otherwise using links gathered 641 from HTTP headers. In particular, Link header fields that use the 642 "anchor" parameter to associate a link's context with another 643 resource are to be treated with due caution. 645 The Link header field makes extensive use of IRIs and URIs. See 646 [RFC3987] for security considerations relating to IRIs. See 647 [RFC3986] for security considerations relating to URIs. See 648 [RFC7230] for security considerations relating to HTTP headers. 650 6. Internationalisation Considerations 652 Link targets may need to be converted to URIs in order to express 653 them in serialisations that do not support IRIs. This includes the 654 Link HTTP header field. 656 Similarly, the anchor parameter of the Link header field does not 657 support IRIs, and therefore IRIs must be converted to URIs before 658 inclusion there. 660 Relation types are defined as URIs, not IRIs, to aid in their 661 comparison. It is not expected that they will be displayed to end 662 users. 664 Note that registered Relation Names are required to be lower-case 665 ASCII letters. 667 7. References 669 7.1. Normative References 671 [I-D.ietf-httpbis-rfc5987bis] 672 Reschke, J., "Indicating Character Encoding and Language 673 for HTTP Header Field Parameters", draft-ietf-httpbis- 674 rfc5987bis-05 (work in progress), February 2017. 676 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 677 Requirement Levels", BCP 14, RFC 2119, 678 DOI 10.17487/RFC2119, March 1997, 679 . 681 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 682 Procedures for Message Header Fields", BCP 90, RFC 3864, 683 DOI 10.17487/RFC3864, September 2004, 684 . 686 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 687 Resource Identifier (URI): Generic Syntax", STD 66, 688 RFC 3986, DOI 10.17487/RFC3986, January 2005, 689 . 691 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 692 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 693 January 2005, . 695 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 696 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 697 DOI 10.17487/RFC5226, May 2008, 698 . 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, 706 RFC 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", 711 RFC 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, 716 DOI 10.17487/RFC7231, June 2014, 717 . 719 [W3C.CR-css3-mediaqueries-20090915] 720 Lie, H., Celik, T., Glazman, D., and A. Kesteren, "Media 721 Queries", World Wide Web Consortium CR CR-css3- 722 mediaqueries-20090915, September 2009, 723 . 725 7.2. Informative References 727 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 728 HTTP/1.1", RFC 2817, DOI 10.17487/RFC2817, May 2000, 729 . 731 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 732 DOI 10.17487/RFC2818, May 2000, 733 . 735 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 736 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 737 December 2005, . 739 [W3C.REC-html5-20141028] 740 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 741 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 742 World Wide Web Consortium Recommendation REC- 743 html5-20141028, October 2014, 744 . 746 Appendix A. Notes on Other Link Serialisations 748 Header fields (Section 3) are only one serialisation of links; other 749 specifications have defined alternative serialisations. 751 A.1. Link Serialisation in HTML 753 HTML motivated the original syntax of the Link header field, and many 754 of the design decisions in this document are driven by a desire to 755 stay compatible with it. 757 In HTML, the link element can be mapped to links as specified here by 758 using the "href" attribute for the target URI, and "rel" to convey 759 the relation type, as in the Link header field. The context of the 760 link is the URI associated with the entire HTML document. HTML also 761 defines several attributes on links that can be seen as target 762 attributes, including "media", "hreflang", "type" and "sizes". 764 HTML5 ([W3C.REC-html5-20141028]) Section 4.8 defines modern HTML 765 links. That document links to the Microformats Wiki as a registry; 766 over time, the IANA registry ought to mirror its contents, and 767 ideally eventually replace it (although that depends on the HTML 768 community). 770 Surveys of existing HTML content have shown that unregistered link 771 relation types that are not URIs are (perhaps inevitably) common. 772 Consuming HTML implementations ought not consider such unregistered 773 short links to be errors, but rather relation types with a local 774 scope (i.e., their meaning is specific and perhaps private to that 775 document). 777 Finally, the HTML specification gives a special meaning when the 778 "alternate" relation types coincides with other relation types in the 779 same link. Such links ought to be serialised in the Link header 780 field using a single list of relation-types (e.g., rel="alternate 781 stylesheet") to preserve this relationship. 783 A.2. Link Serialisation in Atom 785 Atom [RFC4287] is a link serialisation that conveys links in the 786 atom:link element, with the "href" attribute indicating the link 787 target and the "rel" attribute containing the relation type. The 788 context of the link is either a feed locator or an entry ID, 789 depending on where it appears; generally, feed-level links are 790 obvious candidates for transmission as a Link header field. 792 When serialising an atom:link into a Link header field, it is 793 necessary to convert link targets (if used) to URIs. 795 Atom defines extension relation types in terms of IRIs. This 796 specification re-defines them as URIs, to simplify and reduce errors 797 in their comparison. 799 Atom allows registered link relation types to be serialised as 800 absolute URIs using a prefix, "http://www.iana.org/assignments/ 801 relation/". This prefix is specific to the Atom serialisation. 803 Furthermore, link relation types are always compared in a case- 804 sensitive fashion; therefore, registered link relation types SHOULD 805 be converted to their registered form (usually, lowercase) when 806 serialised in an Atom document. 808 Note also that while the Link header field allows multiple relations 809 to be serialised in a single link, atom:link does not. In this case, 810 a single link-value may map to several atom:link elements. 812 As with HTML, atom:link defines some attributes that are not 813 explicitly mirrored in the Link header field syntax, but they can 814 also be used as link-extensions to maintain fidelity. 816 Appendix B. Algorithm for Parsing Link Headers 818 Given a HTTP header field-value "field_value" as a string assuming 819 ASCII encoding, the following algorithm can be used to parse it into 820 the model described by this specification: 822 1. Let "links" be an empty list. 824 2. Create "link_strings" by splitting "field_value" on "," 825 characters, excepting "," characters within quoted strings as per 826 [RFC7230], Section 3.2.6, or which form part of link's URI- 827 Reference (i.e. between "<" and ">" characters where the "<" is 828 immediately preceded by OWS and either a "," character or the 829 beginning of the "field_value" string). 831 3. For each "link_string" in "link_strings": 833 1. Let "target_string" be the string between the first "<" and 834 first ">" characters in "link_string". If they do not 835 appear, or do not appear in that order, fail parsing. 837 2. Let "rest" be the remaining characters (if any) after the 838 first ">" character in "link_string". 840 3. Split "rest" into an array of strings "parameter_strings", 841 on the ";" character, excepting ";" characters within quoted 842 strings as per [RFC7230], Section 3.2.6. 844 4. Let "link_parameters" be an empty array. 846 5. For each item "parameter" in "parameter_strings": 848 1. Remove OWS from the beginning and end of "parameter". 850 2. Skip this item if "parameter" matches the empty string 851 (""). 853 3. Split "parameter" into "param_name" and "param_value" on 854 the first "=" character. If "parameter" does not 855 contain "=", let "param_name" be "parameter" and 856 "param_value" be null. 858 4. Remove OWS from the end of "param_name" and the 859 beginning of "param_value". 861 5. Case-normalise "param_name" to lowercase. 863 6. If the first and last characters of "param_value" are 864 both DQUOTE: 866 1. Remove the first and last characters of 867 "param_value". 869 2. Replace quoted-pairs within "param_value" with the 870 octet following the backslash, as per [RFC7230], 871 Section 3.2.6. 873 7. If the last character of "param_name" is an asterisk 874 ("*"), decode "param_value" according to 875 [I-D.ietf-httpbis-rfc5987bis]. Skip this item if an 876 unrecoverable error is encountered. 878 8. Append the tuple ("param_name", "param_value") to 879 "link_parameters". 881 6. Let "target" be the result of relatively resolving (as per 882 [RFC3986], Section 5.2) "target_string". Note that any base 883 URI carried in the payload body is NOT used. 885 7. Let "relations_string" be the second item of the first tuple 886 of "link_parameters" whose first item matches the string 887 "rel", or the empty string ("") if it is not present. 889 8. Split "relations_string" into an array of strings 890 "relation_types", on RWS (removing all whitespace in the 891 process). 893 9. Let "context_string" be the second item of the first tuple 894 of "link_parameters" whose first item matches the string 895 "anchor". If it is not present, "context_string" is the 896 identity of the representation carrying the Link header 897 [RFC7231], Section 3.1.4.1, serialised as a URI. Where the 898 identity is "anonymous" "context_string" is null. 900 10. Let "context" be the result of relatively resolving (as per 901 [RFC3986], Section 5.2) "context_string", unless 902 "context_string" is null in which case "context" is null. 903 Note that any base URI carried in the payload body is NOT 904 used. 906 11. Let "target_attributes" be an empty array. 908 12. For each tuple ("param_name", "param_value") of 909 "link_parameters": 911 1. If "param_name" matches "rel" or "anchor", skip this 912 tuple. 914 2. If "param_name" matches "media", "title", "title*" or 915 "type" and "target_attributes" already contains a tuple 916 whose first element matches the value of "param_name", 917 skip this tuple. 919 3. Append ("param_name", "param_value") to 920 "target_attributes". 922 13. Let "star_param_names" be the set of "param_name"s in the 923 ("param_name", "param_value") tuples of "link_parameters" 924 where the last character of "param_name" is an asterisk 925 ("*"). 927 14. For each "star_param_name" in "star_param_names": 929 1. Let "base_param_name" be "star_param_name" with the last 930 character removed. 932 2. If the implementation does not choose to support an 933 internationalised form of a parameter named 934 "base_param_name" for any reason (including, but not 935 limited to, it being prohibited by the parameter's 936 specification), remove all tuples from "link_parameters" 937 whose first member is "star_param_name" and skip to the 938 next "star_param_name". 940 3. Remove all tuples from "link_parameters" whose first 941 member is "base_param_name". 943 4. Change the first member of all tuples in 944 "link_parameters" whose first member is 945 "star_param_name" to "base_param_name". 947 15. For each "relation_type" in "relation_types": 949 1. Case-normalise "relation_type" to lowercase. 951 2. Append a link object to "links" with the target 952 "target", relation type of "relation_type", context of 953 "context", and target attributes "target_attributes". 955 4. Return "links". 957 Appendix C. Changes from RFC5988 959 This specification has the following differences from its 960 predecessor, RFC5988: 962 o The initial relation type registrations were removed, since 963 they've already been registered by 5988. 965 o The introduction has been shortened. 967 o The Link Relation Application Data Registry has been removed. 969 o Incorporated errata. 971 o Updated references. 973 o Link cardinality was clarified. 975 o Terminology was changed from "target IRI" and "context IRI" to 976 "link target" and "link context" respectively. 978 o Made assigning a URI to registered relation types serialisation- 979 specific. 981 o Removed misleading statement that the link header field is 982 semantically equivalent to HTML and Atom links. 984 o More carefully defined how the Experts and IANA should interact. 986 o More carefully defined and used "link serialisations" and "link 987 applications." 989 o Clarified the cardinality of target attributes (generically and 990 for "type"). 992 o Corrected the default link context for the Link header field, to 993 be dependent upon the identity of the representation (as per 994 RFC7231). 996 o Defined a suggested parsing algorithm for the Link header. 998 o The value space of target attributes and their definition has been 999 specified. 1001 o The ABNF has been updated to be compatible with [RFC7230]. In 1002 particular, whitespace is now explicit. 1004 o Some parameters on the HTTP header field can now appear as a 1005 token. 1007 o Handling of quoted strings is now defined by [RFC7230]. 1009 o The "type" header field parameter now needs to be quoted (as 1010 "token" does not allow "/"). 1012 Author's Address 1014 Mark Nottingham 1016 EMail: mnot@mnot.net 1017 URI: https://www.mnot.net/