idnits 2.17.1 draft-nottingham-rfc5988bis-04.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 (February 3, 2017) is 2638 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-04 ** 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 February 3, 2017 4 Obsoletes: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: August 7, 2017 8 Web Linking 9 draft-nottingham-rfc5988bis-04 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 August 7, 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 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.1.2. Registration Request Processing . . . . . . . . . . . 7 86 4.2. Extension Relation Types . . . . . . . . . . . . . . . . 7 87 5. Target Attributes . . . . . . . . . . . . . . . . . . . . . . 8 88 6. Link Serialisation in HTTP Headers . . . . . . . . . . . . . 8 89 6.1. Link Target . . . . . . . . . . . . . . . . . . . . . . . 9 90 6.2. Link Context . . . . . . . . . . . . . . . . . . . . . . 9 91 6.3. Relation Type . . . . . . . . . . . . . . . . . . . . . . 9 92 6.4. Target Attributes . . . . . . . . . . . . . . . . . . . . 10 93 6.4.1. Serialisation-Defined Attributes . . . . . . . . . . 10 94 6.4.2. Extension Attributes . . . . . . . . . . . . . . . . 11 95 6.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 12 96 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 97 7.1. Link HTTP Header Field Registration . . . . . . . . . . . 13 98 7.2. Link Relation Type Registry . . . . . . . . . . . . . . . 13 99 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 100 9. Internationalisation Considerations . . . . . . . . . . . . . 14 101 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 102 10.1. Normative References . . . . . . . . . . . . . . . . . . 15 103 10.2. Informative References . . . . . . . . . . . . . . . . . 16 104 Appendix A. Notes on Other Link Serialisations . . . . . . . . . 17 105 A.1. Link Serialisation in HTML . . . . . . . . . . . . . . . 17 106 A.2. Link Serialisation in Atom . . . . . . . . . . . . . . . 17 107 Appendix B. 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; and from 142 [RFC5646]: Language-Tag.. 144 3. Links 146 In this specification, a link is a typed connection between two 147 resources, and is comprised of: 149 o A _link context_, 151 o a _link relation type_ (Section 4), 153 o a _link target_, and 155 o optionally, _target attributes_ (Section 5). 157 A link can be viewed as a statement of the form "{link context} has a 158 {link relation type} resource at {link target}, which has {target 159 attributes}". 161 Link contexts and link targets are both IRIs [RFC3987]. However, in 162 the common case, the link context will also be a URI [RFC3986], 163 because many protocols (such as HTTP) do not support dereferencing 164 IRIs. Likewise, the link target will be sometimes be converted to a 165 URI (see [RFC3987], Section 3.1) in places that do not support IRIs 166 (such as the Link header field defined in Section 6). 168 This specification does not place restrictions on the cardinality of 169 links; there can be multiple links to and from a particular target, 170 and multiple links of the same or different types between a given 171 context and target. Likewise, the relative ordering of links in any 172 particular serialisation, or between serialisations (e.g., the Link 173 header field and in-content links) is not specified or significant in 174 this specification; applications that wish to consider ordering 175 significant can do so. 177 Links are conveyed in _link serialisations_; they are the "bytes on 178 the wire", and can occur in various forms. For example, Atom 179 [RFC4287] and HTML [W3C.REC-html5-20141028] both defined 180 serialisations of links into their respective formats, and Section 6 181 defines how to serialise links in HTTP header fields. 183 This specification does not define a general syntax for links across 184 different serialisations, nor does it mandate a specific context for 185 any given link; it is expected that serialisations of links will 186 specify both aspects. 188 Finally, links are consumed by _link applications_. Generally, an 189 application will define the link relation types it uses, along with 190 the serialisations that they might occur within. For example, the 191 application "Web browsing" looks for the "stylesheet" link relation 192 type in the HTML link serialisation, whereas the application 193 "AtomPub" uses the "edit" and "edit-media" link relations. 195 4. Link Relation Types 197 In the simplest case, a link relation type identifies the semantics 198 of a link. For example, a link with the relation type "copyright" 199 indicates that the resource identified by the link target is a 200 statement of the copyright terms applying to the current link 201 context. 203 Link relation types can also be used to indicate that the target 204 resource has particular attributes, or exhibits particular 205 behaviours; for example, a "service" link implies that the identified 206 resource is part of a defined protocol (in this case, a service 207 description). 209 Relation types are not to be confused with media types [RFC6838]; 210 they do not identify the format of the representation that results 211 when the link is dereferenced. Rather, they only describe how the 212 current context is related to another resource. 214 Relation types SHOULD NOT infer any additional semantics based upon 215 the presence or absence of another link relation type, or its own 216 cardinality of occurrence. An exception to this is the combination 217 of the "alternate" and "stylesheet" registered relation types, which 218 has special meaning in HTML for historical reasons. 220 There are two kinds of relation types: registered and extension. 222 4.1. Registered Relation Types 224 Well-defined relation types can be registered as tokens for 225 convenience and/or to promote reuse by other applications, using the 226 procedure in Section 4.1.1. 228 Registered relation type names MUST conform to the reg-rel-type rule 229 (see Section 6.3), and MUST be compared character-by-character in a 230 case-insensitive fashion. They SHOULD be appropriate to the 231 specificity of the relation type; i.e., if the semantics are highly 232 specific to a particular application, the name should reflect that, 233 so that more general names are available for less specific use. 235 Registered relation types MUST NOT constrain the media type of the 236 link context, and MUST NOT constrain the available representation 237 media types of the link target. However, they can specify the 238 behaviours and properties of the target resource (e.g., allowable 239 HTTP methods, request and response media types that must be 240 supported). 242 Historically, registered relation types have been identified with a 243 URI [RFC3986] by prefixing their names with an application-defined 244 base URI (e.g., see Appendix A.2). This practice is NOT RECOMMENDED, 245 because the resulting strings will not be considered equivalent to 246 the registered relation types by other processors. Applications that 247 do use such URIs internally MUST NOT use them in link serialisations 248 that do not explicitly accommodate them. 250 4.1.1. Registering Link Relation Types 252 Any party can request registration of a link relation type. 254 Registration requests can be sent to the "link-relations@ietf.org" 255 mailing list. The Expert(s) MAY establish alternate means of 256 requesting registrations, which SHOULD be linked to from the registry 257 page. 259 Registration requests consist of at least the following information: 261 o *Relation Name*: The name of the relation type 263 o *Description*: A short English description of the type's 264 semantics. It SHOULD be stated in terms of the relationship 265 between the link context and link target. 267 o *Reference*: Reference to the document that specifies the link 268 relation type, preferably including a URI that can be used to 269 retrieve a copy of the document. An indication of the relevant 270 section(s) MAY also be included, but is not required. 272 The Expert(s) MAY define additional fields to be collected in the 273 registry. 275 General requirements for registered relation types are described in 276 Section 4.1. 278 Registrations MUST reference a freely available, stable 279 specification. 281 Note that relation types can be registered by third parties 282 (including the Expert(s)), if the Expert(s) determine that an 283 unregistered relation type is widely deployed and not likely to be 284 registered in a timely manner. 286 4.1.2. Registration Request Processing 288 Relation types are registered on the advice of a Designated Expert 289 (appointed by the IESG or their delegate), with a Specification 290 Required (using terminology from [RFC5226]). 292 The goal of the registry is to reflect common use of links on the 293 Internet. Therefore, the Expert(s) SHOULD be strongly biased towards 294 approving registrations, unless they are abusive, frivolous, not 295 likely to be used on the Internet, or actively harmful to the 296 Internet and/or the Web (not merely aesthetically displeasing, or 297 architecturally dubious). 299 The Expert(s) MUST clearly identify any issues which cause a 300 registration to be refused. Advice about the syntax or semantics of 301 a proposed link relation type can be given, but if it does not block 302 registration, this SHOULD be explicitly stated. 304 When a request is approved, the Expert(s) will inform IANA, and the 305 registration will be processed. The IESG is the final arbiter of any 306 objection. 308 4.2. Extension Relation Types 310 Applications that don't wish to register a relation type can use an 311 extension relation type, which is a URI [RFC3986] that uniquely 312 identifies the relation type. Although the URI can point to a 313 resource that contains a definition of the semantics of the relation 314 type, clients SHOULD NOT automatically access that resource to avoid 315 overburdening its server. 317 The URI used for an extension relation type SHOULD be under the 318 control of the person or party defining it, or be delegated to them. 320 When extension relation types are compared, they MUST be compared as 321 strings (after converting to URIs if serialised in a different 322 format) in a case-insensitive fashion, character-by-character. 323 Because of this, all-lowercase URIs SHOULD be used for extension 324 relations. 326 Note that while extension relation types are required to be URIs, a 327 serialisation of links can specify that they are expressed in another 328 form, as long as they can be converted to URIs. 330 5. Target Attributes 332 _Target attributes_ are a list of key/value pairs that describe the 333 link or its target; for example, a media type hint. 335 They can be defined both by individual link relation types and by 336 link serialisations. 338 This specification does not attempt to coordinate the name of target 339 attributes, their cardinality or use. Serialisations SHOULD 340 coordinate their target attributes to avoid conflicts in semantics or 341 syntax. 343 The names of target attributes SHOULD conform to the token rule, but 344 SHOULD NOT include any of the characters "%", "'" or "*", for 345 portability across serializations, and MUST be compared in a case- 346 insensitive fashion. 348 Target attribute definitions SHOULD specify: 350 o The serialisation of their values into Unicode or a subset 351 thereof, to maximise their chances of portability across link 352 serialisations. 354 o The semantics and error handling of multiple occurrences of the 355 target attribute on a given link. 357 This specification does define target attributes for use in the Link 358 HTTP header field in Section 6.4. 360 6. Link Serialisation in HTTP Headers 362 The Link header field provides a means for serialising one or more 363 links into HTTP headers. 365 The ABNF for the field value is given below: 367 Link = #link-value 368 link-value = "<" URI-Reference ">" *( OWS ";" OWS link-param ) 369 link-param = token BWS "=" BWS ( token / quoted-string ) 371 Note that any "link-param" can be generated with values using either 372 the "token" or the "quoted-string" syntax, and therefore recipients 373 MUST be able to parse both forms. Individual "link-param"s specify 374 their syntax in terms of the value after any necessary unquoting (as 375 per [RFC7230], Section 3.2.6). 377 This specification defines the link-params "rel", "anchor", "rev", 378 "hreflang", "media", "title", "title*", and "type"; see Section 6.2, 379 Section 6.3 and Section 6.4. 381 6.1. Link Target 383 Each link-value conveys one target IRI as a URI-Reference (after 384 conversion to one, if necessary; see [RFC3987], Section 3.1) inside 385 angle brackets ("<>"). If the URI-Reference is relative, parsers 386 MUST resolve it as per [RFC3986], Section 5. Note that any base IRI 387 from the message's content is not applied. 389 6.2. Link Context 391 By default, the context of a link conveyed in the Link header field 392 is identity of the representation it is associated with, as defined 393 in [RFC7231], Section 3.1.4.1, serialised as a URI. 395 When present, the anchor parameter overrides this with another URI, 396 such as a fragment of this resource, or a third resource (i.e., when 397 the anchor value is an absolute URI). If the anchor parameter's 398 value is a relative URI, parsers MUST resolve it as per [RFC3986], 399 Section 5. Note that any base URI from the body's content is not 400 applied. 402 The ABNF for the "anchor" parameter's value is: 404 URI-Reference 406 Consuming implementations can choose to ignore links with an anchor 407 parameter. For example, the application in use might not allow the 408 link context to be assigned to a different resource. In such cases, 409 the entire link is to be ignored; consuming implementations MUST NOT 410 process the link without applying the anchor. 412 Note that depending on HTTP status code and response headers, the 413 link context might be "anonymous" (i.e., no link context is 414 available). For instance, this is the case on a 404 response to a 415 GET request. 417 6.3. Relation Type 419 The relation type of a link conveyed in the Link header field is 420 conveyed in the "rel" parameter's value. The "rel" parameter MUST 421 NOT appear more than once in a given link-value; occurrences after 422 the first MUST be ignored by parsers. 424 The "rev" parameter has been used in the past to indicate that the 425 semantics of the relationship are in the reverse direction. That is, 426 a link from A to B with REL="X" expresses the same relationship as a 427 link from B to A with REV="X". "rev" is deprecated by this 428 specification because it often confuses authors and readers; in most 429 cases, using a separate relation type is preferable. 431 The ABNF for the "rel" and "rev" parameters' values is: 433 relation-type *( 1*SP relation-type ) 435 where: 437 relation-type = reg-rel-type | ext-rel-type 438 reg-rel-type = LOALPHA *( LOALPHA | DIGIT | "." | "-" ) 439 ext-rel-type = URI 441 Note that extension relation types are REQUIRED to be absolute URIs 442 in Link headers, and MUST be quoted if they contain a semicolon (";") 443 or comma (",") (as these characters are used as delimiters in the 444 header field itself). 446 6.4. Target Attributes 448 The Link header field defines several target attributes specific to 449 this serialisation, and also allows extension target attributes. 450 Target attributes are serialised in the Link header field as 451 parameters (see [RFC7231], Section 3.1.1.1 for the definition of 452 their syntax). 454 6.4.1. Serialisation-Defined Attributes 456 The "hreflang", "media", "title", "title*", and "type" link-params 457 can be translated to serialisation-defined target attributes for the 458 link. 460 The "hreflang" attribute, when present, is a hint indicating what the 461 language of the result of dereferencing the link should be. Note 462 that this is only a hint; for example, it does not override the 463 Content-Language header field of a HTTP response obtained by actually 464 following the link. Multiple "hreflang" attributes on a single link- 465 value indicate that multiple languages are available from the 466 indicated resource. 468 The ABNF for the "hreflang" parameter's value is: 470 Language-Tag 472 The "media" attribute, when present, is used to indicate intended 473 destination medium or media for style information (see 474 [W3C.REC-html5-20141028], Section 4.2.4). Its value MUST be quoted 475 if it contains a semicolon (";") or comma (","). There MUST NOT be 476 more than one "media" attribute in a link-value; occurrences after 477 the first MUST be ignored by parsers. 479 The ABNF for the "media" parameter's value is: 481 media_query_list 483 The "title" attribute, when present, is used to label the destination 484 of a link such that it can be used as a human-readable identifier 485 (e.g., a menu entry) in the language indicated by the Content- 486 Language header field (if present). The "title" attribute MUST NOT 487 appear more than once in a given link; occurrences after the first 488 MUST be ignored by parsers. 490 The "title*" link-param can be used to encode this attribute in a 491 different character set, and/or contain language information as per 492 [I-D.ietf-httpbis-rfc5987bis]. The "title*" link-param MUST NOT 493 appear more than once in a given link-value; occurrences after the 494 first MUST be ignored by parsers. If the attribute does not contain 495 language information, its language is indicated by the Content- 496 Language header field (when present). 498 If both the "title" and "title*" link-param appear in a link, 499 processors SHOULD use the "title*" link-param's value for the "title" 500 attribute. 502 The "type" attribute, when present, is a hint indicating what the 503 media type of the result of dereferencing the link should be. Note 504 that this is only a hint; for example, it does not override the 505 Content-Type header field of a HTTP response obtained by actually 506 following the link. The "type" attribute MUST NOT appear more than 507 once in a given link-value; occurrences after the first MUST be 508 ignored by parsers. 510 The ABNF for the "type" parameter's value is: 512 type-name "/" subtype-name 514 6.4.2. Extension Attributes 516 Other link-params are link-extensions, and are to be considered as 517 target attributes. 519 Such target attributes MAY be defined to use the encoding in 520 [I-D.ietf-httpbis-rfc5987bis] (e.g., "example" and "example_"). When 521 both forms are present, they SHOULD be considered to be the same 522 target attribute; processors SHOULD use the value of the name ending 523 in "_" (after [I-D.ietf-httpbis-rfc5987bis] decoding), but MAY fall 524 back to the other value if there is an error in decoding it, or if 525 they do not support decoding. 527 6.5. Examples 529 For example: 531 Link: ; rel="previous"; 532 title="previous chapter" 534 indicates that "chapter2" is previous to this resource in a logical 535 navigation path. 537 Similarly, 539 Link: ; rel="http://example.net/foo" 541 indicates that the root resource ("/") is related to this resource 542 with the extension relation type "http://example.net/foo". 544 The example below shows an instance of the Link header field encoding 545 multiple links, and also the use of RFC 5987 encoding to encode both 546 non-ASCII characters and language information. 548 Link: ; 549 rel="previous"; title*=UTF-8'de'letztes%20Kapitel, 550 ; 551 rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel 553 Here, both links have titles encoded in UTF-8, use the German 554 language ("de"), and the second link contains the Unicode code point 555 U+00E4 ("LATIN SMALL LETTER A WITH DIAERESIS"). 557 Note that link-values can convey multiple links between the same link 558 target and link context; for example: 560 Link: ; 561 rel="start http://example.net/relation/other" 563 Here, the link to "http://example.org/" has the registered relation 564 type "start" and the extension relation type 565 "http://example.net/relation/other". 567 7. IANA Considerations 569 In addition to the actions below, IANA should terminate the Link 570 Relation Application Data Registry, as it has not been used, and 571 future use is not anticipated. 573 7.1. Link HTTP Header Field Registration 575 This specification updates the Message Header registry entry for 576 "Link" in HTTP [RFC3864] to refer to this document. 578 Header field: Link 579 Applicable protocol: http 580 Status: standard 581 Author/change controller: 582 IETF (iesg@ietf.org) 583 Internet Engineering Task Force 584 Specification document(s): 585 [RFC&rfc.number;] 587 7.2. Link Relation Type Registry 589 This specification updates the registration procedures for the Link 590 Relation Type registry; see Section 4.1.1. The Expert(s) and IANA 591 will interact as outlined below. 593 IANA will direct any incoming requests regarding the registry to this 594 document and, if defined, the processes established by the Expert(s); 595 typically, this will mean referring them to the registry Web page. 597 The Expert(s) will provide registry data to IANA in an agreed form 598 (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 in any alternative formats provided by the 605 Expert(s) 607 Each published document will be at a URL agreed to by IANA and the 608 Expert(s), and IANA will set HTTP response headers on them as 609 (reasonably) requested by the Expert(s). 611 Additionally, the HTML generated by IANA will: 613 o Take directions from the Expert(s) as to the content of the HTML 614 page's introductory text 616 o Include a stable HTML fragment identifier for each registered link 617 relation 619 All registry data documents MUST include Simplified BSD License text 620 as described in Section 4.e of the Trust Legal Provisions 621 (). 623 8. Security Considerations 625 The content of the Link header field is not secure, private or 626 integrity-guaranteed, and due caution should be exercised when using 627 it. Use of Transport Layer Security (TLS) with HTTP ([RFC2818] and 628 [RFC2817]) is currently the only end-to-end way to provide such 629 protection. 631 Link applications ought to consider the attack vectors opened by 632 automatically following, trusting, or otherwise using links gathered 633 from HTTP headers. In particular, Link header fields that use the 634 "anchor" parameter to associate a link's context with another 635 resource should be treated with due caution. 637 The Link header field makes extensive use of IRIs and URIs. See 638 [RFC3987] for security considerations relating to IRIs. See 639 [RFC3986] for security considerations relating to URIs. See 640 [RFC7230] for security considerations relating to HTTP headers. 642 9. Internationalisation Considerations 644 Link targets may need to be converted to URIs in order to express 645 them in serialisations that do not support IRIs. This includes the 646 Link HTTP header field. 648 Similarly, the anchor parameter of the Link header field does not 649 support IRIs, and therefore IRIs must be converted to URIs before 650 inclusion there. 652 Relation types are defined as URIs, not IRIs, to aid in their 653 comparison. It is not expected that they will be displayed to end 654 users. 656 Note that registered Relation Names are required to be lower-case 657 ASCII letters. 659 10. References 660 10.1. Normative References 662 [I-D.ietf-httpbis-rfc5987bis] 663 Reschke, J., "Indicating Character Encoding and Language 664 for HTTP Header Field Parameters", draft-ietf-httpbis- 665 rfc5987bis-04 (work in progress), November 2016. 667 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 668 Requirement Levels", BCP 14, RFC 2119, 669 DOI 10.17487/RFC2119, March 1997, 670 . 672 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 673 Procedures for Message Header Fields", BCP 90, RFC 3864, 674 DOI 10.17487/RFC3864, September 2004, 675 . 677 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 678 Resource Identifier (URI): Generic Syntax", STD 66, 679 RFC 3986, DOI 10.17487/RFC3986, January 2005, 680 . 682 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 683 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 684 January 2005, . 686 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 687 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 688 DOI 10.17487/RFC5226, May 2008, 689 . 691 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 692 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 693 September 2009, . 695 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 696 Specifications and Registration Procedures", BCP 13, 697 RFC 6838, DOI 10.17487/RFC6838, January 2013, 698 . 700 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 701 Protocol (HTTP/1.1): Message Syntax and Routing", 702 RFC 7230, DOI 10.17487/RFC7230, June 2014, 703 . 705 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 706 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 707 DOI 10.17487/RFC7231, June 2014, 708 . 710 [W3C.CR-css3-mediaqueries-20090915] 711 Lie, H., Celik, T., Glazman, D., and A. Kesteren, "Media 712 Queries", World Wide Web Consortium CR CR-css3- 713 mediaqueries-20090915, September 2009, 714 . 716 10.2. Informative References 718 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. 719 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 720 RFC 2068, DOI 10.17487/RFC2068, January 1997, 721 . 723 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 724 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 725 Transfer Protocol -- HTTP/1.1", RFC 2616, 726 DOI 10.17487/RFC2616, June 1999, 727 . 729 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 730 HTTP/1.1", RFC 2817, DOI 10.17487/RFC2817, May 2000, 731 . 733 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 734 DOI 10.17487/RFC2818, May 2000, 735 . 737 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 738 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 739 December 2005, . 741 [W3C.REC-html-rdfa-20150317] 742 Sporny, M., "HTML+RDFa 1.1 - Second Edition", World Wide 743 Web Consortium Recommendation REC-html-rdfa-20150317, 744 March 2015, 745 . 747 [W3C.REC-html5-20141028] 748 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 749 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 750 World Wide Web Consortium Recommendation REC- 751 html5-20141028, October 2014, 752 . 754 Appendix A. Notes on Other Link Serialisations 756 Header fields (Section 6) are only one serialisation of links; other 757 specifications have defined alternative serialisations. 759 A.1. Link Serialisation in HTML 761 HTML motivated the original syntax of the Link header field, and many 762 of the design decisions in this document are driven by a desire to 763 stay compatible with it. 765 In HTML, the link element can be mapped to links as specified here by 766 using the "href" attribute for the target URI, and "rel" to convey 767 the relation type, as in the Link header field. The context of the 768 link is the URI associated with the entire HTML document. HTML also 769 defines several attributes on links that can be seen as target 770 attributes, including "media", "hreflang", "type" and "sizes". 772 HTML5 ([W3C.REC-html5-20141028]) Section 4.8 defines modern HTML 773 links. That document links to the Microformats Wiki as a registry; 774 over time, the IANA registry ought to mirror its contents, and 775 ideally eventually replace it (although that depends on the HTML 776 community). 778 Surveys of existing HTML content have shown that unregistered link 779 relation types that are not URIs are (perhaps inevitably) common. 780 Consuming HTML implementations ought not consider such unregistered 781 short links to be errors, but rather relation types with a local 782 scope (i.e., their meaning is specific and perhaps private to that 783 document). 785 Finally, the HTML specification gives a special meaning when the 786 "alternate" relation types coincides with other relation types in the 787 same link. Such links ought to be serialised in the Link header 788 field using a single list of relation-types (e.g., rel="alternate 789 stylesheet") to preserve this relationship. 791 A.2. Link Serialisation in Atom 793 Atom [RFC4287] is a link serialisation that conveys links in the 794 atom:link element, with the "href" attribute indicating the link 795 target and the "rel" attribute containing the relation type. The 796 context of the link is either a feed locator or an entry ID, 797 depending on where it appears; generally, feed-level links are 798 obvious candidates for transmission as a Link header field. 800 When serialising an atom:link into a Link header field, it is 801 necessary to convert link targets (if used) to URIs. 803 Atom defines extension relation types in terms of IRIs. This 804 specification re-defines them as URIs, to simplify and reduce errors 805 in their comparison. 807 Atom allows registered link relation types to be serialised as 808 absolute URIs using a prefix, "http://www.iana.org/assignments/ 809 relation/". This prefix is specific to the Atom serialisation. 811 Furthermore, link relation types are always compared in a case- 812 sensitive fashion; therefore, registered link relation types SHOULD 813 be converted to their registered form (usually, lowercase) when 814 serialised in an Atom document. 816 Note also that while the Link header field allows multiple relations 817 to be serialised in a single link, atom:link does not. In this case, 818 a single link-value may map to several atom:link elements. 820 As with HTML, atom:link defines some attributes that are not 821 explicitly mirrored in the Link header field syntax, but they can 822 also be used as link-extensions to maintain fidelity. 824 Appendix B. Algorithm for Parsing Link Headers 826 Given a HTTP header field-value "field_value" as a string assuming 827 ASCII encoding, the following algorithm can be used to parse it into 828 the model described by this specification: 830 1. Let "links" be an empty list. 832 2. Create "link_strings" by splitting "field_value" on "," 833 characters, excepting "," characters within quoted strings as per 834 [RFC7230], Section 3.2.6, or which form part of link's URI- 835 Reference (i.e. between "<" and ">" characters where the "<" is 836 immediately preceded by OWS and either a "," character or the 837 beginning of the "field_value" string). 839 3. For each "link_string" in "link_strings": 841 1. Let "target_string" be the string between the first "<" and 842 first ">" characters in "link_string". If they do not 843 appear, or do not appear in that order, fail parsing. 845 2. Let "rest" be the remaining characters (if any) after the 846 first ">" character in "link_string". 848 3. Split "rest" into an array of strings "parameter_strings", 849 on the ";" character, excepting ";" characters within quoted 850 strings as per [RFC7230], Section 3.2.6. 852 4. Let "link_parameters" be an empty array. 854 5. For each item "parameter" in "parameter_strings": 856 1. Remove OWS from the beginning and end of "parameter". 858 2. Skip this item if "parameter" matches the empty string 859 (""). 861 3. Split "parameter" into "param_name" and "param_value" on 862 the first "=" character. If "parameter" does not 863 contain "=", let "param_name" be "parameter" and 864 "param_value" be null. 866 4. Remove OWS from the end of "param_name" and the 867 beginning of "param_value". 869 5. Case-normalise "param_name" to lowercase. 871 6. If the first and last characters of "param_value" are 872 both DQUOTE: 874 1. Remove the first and last characters of 875 "param_value". 877 2. Replace quoted-pairs within "param_value" with the 878 octet following the backslash, as per [RFC7230], 879 Section 3.2.6. 881 7. If the last character of "param_name" is an asterisk 882 ("*"), decode "param_value" according to 883 [I-D.ietf-httpbis-rfc5987bis]. Skip this item if an 884 unrecoverable error is encountered. 886 8. Append the tuple ("param_name", "param_value") to 887 "link_parameters". 889 6. Let "target" be the result of relatively resolving (as per 890 [RFC3986], Section 5.2) "target_string". Note that any base 891 URI carried in the payload body is NOT used. 893 7. Let "relations_string" be the second item of the first tuple 894 of "link_parameters" whose first item matches the string 895 "rel", or the empty string ("") if it is not present. 897 8. Split "relations_string" into an array of strings 898 "relation_types", on RWS (removing all whitespace in the 899 process). 901 9. Let "context_string" be the second item of the first tuple 902 of "link_parameters" whose first item matches the string 903 "anchor". If it is not present, "context_string" is the 904 identity of the representation carrying the Link header 905 [RFC7231], Section 3.1.4.1, serialised as a URI. Where the 906 identity is "anonymous" "context_string" is null. 908 10. Let "context" be the result of relatively resolving (as per 909 [RFC3986], Section 5.2) "context_string", unless 910 "context_string" is null in which case "context" is null. 911 Note that any base URI carried in the payload body is NOT 912 used. 914 11. Let "target_attributes" be an empty array. 916 12. For each tuple ("param_name", "param_value") of 917 "link_parameters": 919 1. If "param_name" matches "rel" or "anchor", skip this 920 tuple. 922 2. If "param_name" matches "media", "title", "title*" or 923 "type" and "target_attributes" already contains a tuple 924 whose first element matches the value of "param_name", 925 skip this tuple. 927 3. Append ("param_name", "param_value") to 928 "target_attributes". 930 13. Let "star_param_names" be the set of "param_name"s in the 931 ("param_name", "param_value") tuples of "link_parameters" 932 where the last character of "param_name" is an asterisk 933 ("*"). 935 14. For each "star_param_name" in "star_param_names": 937 1. Let "base_param_name" be "star_param_name" with the last 938 character removed. 940 2. If the implementation does not choose to support an 941 internationalised form of a parameter named 942 "base_param_name" for any reason (including, but not 943 limited to, it being prohibited by the parameter's 944 specification), remove all tuples from "link_parameters" 945 whose first member is "star_param_name" and skip to the 946 next "star_param_name". 948 3. Remove all tuples from "link_parameters" whose first 949 member is "base_param_name". 951 4. Change the first member of all tuples in 952 "link_parameters" whose first member is 953 "star_param_name" to "base_param_name". 955 15. For each "relation_type" in "relation_types": 957 1. Case-normalise "relation_type" to lowercase. 959 2. Append a link object to "links" with the target 960 "target", relation type of "relation_type", context of 961 "context", and target attributes "target_attributes". 963 4. Return "links". 965 Appendix C. Changes from RFC5988 967 This specification has the following differences from its 968 predecessor, RFC5988: 970 o The initial relation type registrations were removed, since 971 they've already been registered by 5988. 973 o The introduction has been shortened. 975 o The Link Relation Application Data Registry has been removed. 977 o Incorporated errata. 979 o Updated references. 981 o Link cardinality was clarified. 983 o Terminology was changed from "target IRI" and "context IRI" to 984 "link target" and "link context" respectively. 986 o Made assigning a URI to registered relation types serialisation- 987 specific. 989 o Removed misleading statement that the link header field is 990 semantically equivalent to HTML and Atom links. 992 o More carefully defined how the Experts and IANA should interact. 994 o More carefully defined and used "link serialisations" and "link 995 applications." 997 o Clarified the cardinality of target attributes (generically and 998 for "type"). 1000 o Corrected the default link context for the Link header field, to 1001 be dependent upon the identity of the representation (as per 1002 RFC7231). 1004 o Defined a suggested parsing algorithm for the Link header. 1006 o The value space of target attributes and their definition has been 1007 specified. 1009 o The ABNF has been updated to be compatible with [RFC7230]. In 1010 particular, whitespace is now explicit. 1012 o Some parameters on the HTTP header field can now appear as a 1013 token. 1015 o Handling of quoted strings is now defined by [RFC7230]. 1017 o The "type" header field parameter now needs to be quoted (as 1018 "token" does not allow "/"). 1020 Author's Address 1022 Mark Nottingham 1024 EMail: mnot@mnot.net 1025 URI: https://www.mnot.net/