idnits 2.17.1 draft-nottingham-rfc5988bis-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC5988, but the abstract doesn't seem to directly say this. It does mention RFC5988 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 25, 2016) is 2708 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-05) exists of draft-ietf-httpbis-rfc5987bis-03 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft November 25, 2016 4 Obsoletes: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: May 29, 2017 8 Web Linking 9 draft-nottingham-rfc5988bis-03 11 Abstract 13 This specification defines a way to indicate the relationships 14 between resources on the Web ("links") and the type of those 15 relationships ("link relation types"). 17 It also defines the serialisation of such links in HTTP headers with 18 the Link header field. 20 Note to Readers 22 This is a work-in-progress to revise RFC5988. 24 The issues list can be found at https://github.com/mnot/I-D/labels/ 25 rfc5988bis . 27 The most recent (often, unpublished) draft is at 28 https://mnot.github.io/I-D/rfc5988bis/ . 30 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 31 pages/rfc5988bis . 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on May 29, 2017. 50 Copyright Notice 52 Copyright (c) 2016 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 This document may contain material from IETF Documents or IETF 66 Contributions published or made publicly available before November 67 10, 2008. The person(s) controlling the copyright in some of this 68 material may not have granted the IETF Trust the right to allow 69 modifications of such material outside the IETF Standards Process. 70 Without obtaining an adequate license from the person(s) controlling 71 the copyright in such materials, this document may not be modified 72 outside the IETF Standards Process, and derivative works of it may 73 not be created outside the IETF Standards Process, except to format 74 it for publication as an RFC or to translate it into languages other 75 than English. 77 Table of Contents 79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 80 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 81 3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 82 4. Link Relation Types . . . . . . . . . . . . . . . . . . . . . 5 83 4.1. Registered Relation Types . . . . . . . . . . . . . . . . 5 84 4.1.1. Registering Link Relation Types . . . . . . . . . . . 6 85 4.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 . . . . . . . . . . . . . . . . . . . . . 12 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 . . . . . . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . 18 107 Appendix B. Algorithm for Parsing Link Headers . . . . . . . . . 18 108 Appendix C. Changes from RFC5988 . . . . . . . . . . . . . . . . 21 109 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 111 1. Introduction 113 This specification defines a way to indicate the relationships 114 between resources on the Web ("links") and the type of those 115 relationships ("link relation types"). 117 HTML [W3C.REC-html5-20141028] and Atom [RFC4287] both have well- 118 defined concepts of linking; this specification generalises this into 119 a framework that encompasses linking in these formats and 120 (potentially) elsewhere. 122 Furthermore, this specification formalises an HTTP header field for 123 conveying such links, having been originally defined in 124 Section 19.6.2.4 of [RFC2068], but removed from [RFC2616]. 126 2. Notational Conventions 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 130 document are to be interpreted as described in BCP 14, [RFC2119], as 131 scoped to those conformance targets. 133 This document uses the Augmented Backus-Naur Form (ABNF) notation of 134 [RFC7230], including the #rule, and explicitly includes the following 135 rules from it: quoted-string, token, SP (space), BWS (bad 136 whitespace), OWS (optional whitespace), RWS (required whitespace) 137 LOALPHA, DIGIT. 139 Additionally, the following rules are included from [RFC3986]: URI 140 and URI-Reference; from [RFC6838]: type-name and subtype-name; from 141 [W3C.CR-css3-mediaqueries-20090915]: media_query_list; 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 and MUST be compared character-by-character in a case-insensitive 230 fashion. They SHOULD be appropriate to the specificity of the 231 relation type; i.e., if the semantics are highly specific to a 232 particular application, the name should reflect that, so that more 233 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 HTTP 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, such as a XML QNames [W3C.REC-xml-names-20091208]) in a case- 323 insensitive fashion, character-by-character. Because of this, all- 324 lowercase URIs SHOULD be used for extension 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 set of key/value pairs that describe the 333 link or its target; for example, a media type hint. 335 This specification does not attempt to coordinate the name of target 336 attributes, their cardinality or use; they are defined both by 337 individual link relations and by link serialisations. 339 Serialisations SHOULD coordinate their target attributes to avoid 340 conflicts in semantics or syntax. Relation types MAY define 341 additional target attributes specific to them. 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 Their serialisation into Unicode or a subset thereof, to maximise 351 their chances of portability across link serialisations. 353 o The semantics and error handling of multiple occurrences of the 354 attribute on a given link. 356 This specification does define target attributes for use in the Link 357 HTTP header field in Section 6.4. 359 6. Link Serialisation in HTTP Headers 361 The Link header field provides a means for serialising one or more 362 links into HTTP headers. 364 The ABNF for the field value is given below: 366 Link = #link-value 367 link-value = "<" URI-Reference ">" *( OWS ";" OWS link-param ) 368 link-param = token BWS "=" BWS ( token / quoted-string ) 370 Note that any "link-param" can be generated with values using either 371 the "token" or the "quoted-string" syntax, and therefore recipients 372 MUST be able to parse both forms. Individual "link-param"s specify 373 their syntax in terms of the value after any necessary unquoting (as 374 per [RFC7230], Section 3.2.6). 376 This specification defines the link-params "rel", "anchor", "rev", 377 "hreflang", "media", "title", "title*", and "type"; see Section 6.2, 378 Section 6.3 and Section 6.4. 380 6.1. Link Target 382 Each link-value conveys one target IRI as a URI-Reference (after 383 conversion to one, if necessary; see [RFC3987], Section 3.1) inside 384 angle brackets ("<>"). If the URI-Reference is relative, parsers 385 MUST resolve it as per [RFC3986], Section 5. Note that any base IRI 386 from the message's content is not applied. 388 6.2. Link Context 390 By default, the context of a link conveyed in the Link header field 391 is identity of the representation it is associated with, as defined 392 in [RFC7231], Section 3.1.4.1, serialised as a URI. 394 When present, the anchor parameter overrides this with another URI, 395 such as a fragment of this resource, or a third resource (i.e., when 396 the anchor value is an absolute URI). If the anchor parameter's 397 value is a relative URI, parsers MUST resolve it as per [RFC3986], 398 Section 5. Note that any base URI from the body's content is not 399 applied. 401 The ABNF for the "anchor" parameter's value is: ~~~ abnf2616 URI- 402 Reference ~~~ 404 Consuming implementations can choose to ignore links with an anchor 405 parameter. For example, the application in use might not allow the 406 link context to be assigned to a different resource. In such cases, 407 the entire link is to be ignored; consuming implementations MUST NOT 408 process the link without applying the anchor. 410 Note that depending on HTTP status code and response headers, the 411 link context might be "anonymous" (i.e., no link context is 412 available). For instance, this is the case on a 404 response to a 413 GET request. 415 6.3. Relation Type 417 The relation type of a link conveyed in the Link header field is 418 conveyed in the "rel" parameter's value. The "rel" parameter MUST 419 NOT appear more than once in a given link-value; occurrences after 420 the first MUST be ignored by parsers. 422 The "rev" parameter has been used in the past to indicate that the 423 semantics of the relationship are in the reverse direction. That is, 424 a link from A to B with REL="X" expresses the same relationship as a 425 link from B to A with REV="X". "rev" is deprecated by this 426 specification because it often confuses authors and readers; in most 427 cases, using a separate relation type is preferable. 429 The ABNF for the "rel" and "rev" parameters' values is: ~~~ abnf2616 430 relation-type _( 1_SP relation-type ) ~~~ 432 where: 434 relation-type = reg-rel-type | ext-rel-type 435 reg-rel-type = LOALPHA *( LOALPHA | DIGIT | "." | "-" ) 436 ext-rel-type = URI 438 Note that extension relation types are REQUIRED to be absolute URIs 439 in Link headers, and MUST be quoted if they contain a semicolon (";") 440 or comma (",") (as these characters are used as delimiters in the 441 header field itself). 443 6.4. Target Attributes 445 The Link header field defines several target attributes specific to 446 this serialisation, and also allows extension target attributes. 447 Target attributes are serialised in the Link header field as 448 parameters (see [RFC7231], Section 3.1.1.1 for the definition of 449 their syntax). 451 6.4.1. Serialisation-Defined Attributes 453 The "hreflang", "media", "title", "title*", and "type" link-params 454 can be translated to serialisation-defined target attributes for the 455 link. 457 The "hreflang" attribute, when present, is a hint indicating what the 458 language of the result of dereferencing the link should be. Note 459 that this is only a hint; for example, it does not override the 460 Content-Language header field of a HTTP response obtained by actually 461 following the link. Multiple "hreflang" attributes on a single link- 462 value indicate that multiple languages are available from the 463 indicated resource. 465 The ABNF for the "hreflang" parameter's value is: ~~~ abnf2616 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: ~~~ abnf2616 476 media_query_list ~~~ 478 The "title" attribute, when present, is used to label the destination 479 of a link such that it can be used as a human-readable identifier 480 (e.g., a menu entry) in the language indicated by the Content- 481 Language header field (if present). The "title" attribute MUST NOT 482 appear more than once in a given link; occurrences after the first 483 MUST be ignored by parsers. 485 The "title*" link-param can be used to encode this attribute in a 486 different character set, and/or contain language information as per 487 [I-D.ietf-httpbis-rfc5987bis]. The "title*" link-param MUST NOT 488 appear more than once in a given link-value; occurrences after the 489 first MUST be ignored by parsers. If the attribute does not contain 490 language information, its language is indicated by the Content- 491 Language header field (when present). 493 If both the "title" and "title*" link-param appear in a link, 494 processors SHOULD use the "title*" link-param's value for the "title" 495 attribute. 497 The "type" attribute, when present, is a hint indicating what the 498 media type of the result of dereferencing the link should be. Note 499 that this is only a hint; for example, it does not override the 500 Content-Type header field of a HTTP response obtained by actually 501 following the link. The "type" attribute MUST NOT appear more than 502 once in a given link-value; occurrences after the first MUST be 503 ignored by parsers. 505 The ABNF for the "type" parameter's value is: ~~~ abnf2616 type-name 506 "/" subtype-name ~~~ 508 6.4.2. Extension Attributes 510 Other link-params are link-extensions, and are to be considered as 511 target attributes. 513 Such target attributes MAY be defined to use the encoding in 514 [I-D.ietf-httpbis-rfc5987bis] (e.g., "example" and "example_"). When 515 both forms are present, they SHOULD be considered to be the same 516 target attribute; processors SHOULD use the value of the name ending 517 in "_" (after [I-D.ietf-httpbis-rfc5987bis] decoding), but MAY fall 518 back to the other value if there is an error in decoding it, or if 519 they do not support decoding. 521 6.5. Examples 523 For example: 525 Link: ; rel="previous"; 526 title="previous chapter" 528 indicates that "chapter2" is previous to this resource in a logical 529 navigation path. 531 Similarly, 533 Link: ; rel="http://example.net/foo" 535 indicates that the root resource ("/") is related to this resource 536 with the extension relation type "http://example.net/foo". 538 The example below shows an instance of the Link header field encoding 539 multiple links, and also the use of RFC 5987 encoding to encode both 540 non-ASCII characters and language information. 542 Link: ; 543 rel="previous"; title*=UTF-8'de'letztes%20Kapitel, 544 ; 545 rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel 547 Here, both links have titles encoded in UTF-8, use the German 548 language ("de"), and the second link contains the Unicode code point 549 U+00E4 ("LATIN SMALL LETTER A WITH DIAERESIS"). 551 Note that link-values can convey multiple links between the same link 552 target and link context; for example: 554 Link: ; 555 rel="start http://example.net/relation/other" 557 Here, the link to "http://example.org/" has the registered relation 558 type "start" and the extension relation type 559 "http://example.net/relation/other". 561 7. IANA Considerations 563 In addition to the actions below, IANA should terminate the Link 564 Relation Application Data Registry, as it has not been used, and 565 future use is not anticipated. 567 7.1. Link HTTP Header Field Registration 569 This specification updates the Message Header registry entry for 570 "Link" in HTTP [RFC3864] to refer to this document. 572 Header field: Link 573 Applicable protocol: http 574 Status: standard 575 Author/change controller: 576 IETF (iesg@ietf.org) 577 Internet Engineering Task Force 578 Specification document(s): 579 [RFC&rfc.number;] 581 7.2. Link Relation Type Registry 583 This specification updates the registration procedures for the Link 584 Relation Type registry; see Section 4.1.1. The Expert(s) and IANA 585 will interact as outlined below. 587 IANA will direct any incoming requests regarding the registry to this 588 document and, if defined, the processes established by the Expert(s); 589 typically, this will mean referring them to the registry Web page. 591 The Expert(s) will provide registry data to IANA in an agreed form 592 (e.g. a specific XML format). IANA will publish: 594 o The raw registry data 596 o The registry data, transformed into HTML 598 o The registry data in any alternative formats provided by the 599 Expert(s) 601 Each published document will be at a URL agreed to by IANA and the 602 Expert(s), and IANA will set HTTP response headers on them as 603 (reasonably) requested by the Expert(s). 605 Additionally, the HTML generated by IANA will: 607 o Take directions from the Expert(s) as to the content of the HTML 608 page's introductory text 610 o Include a stable HTML fragment identifier for each registered 611 header field 613 All registry data documents MUST include Simplified BSD License text 614 as described in Section 4.e of the Trust Legal Provisions 615 (). 617 8. Security Considerations 619 The content of the Link header field is not secure, private or 620 integrity-guaranteed, and due caution should be exercised when using 621 it. Use of Transport Layer Security (TLS) with HTTP ([RFC2818] and 622 [RFC2817]) is currently the only end-to-end way to provide such 623 protection. 625 Link applications ought to consider the attack vectors opened by 626 automatically following, trusting, or otherwise using links gathered 627 from HTTP headers. In particular, Link header fields that use the 628 "anchor" parameter to associate a link's context with another 629 resource should be treated with due caution. 631 The Link header field makes extensive use of IRIs and URIs. See 632 [RFC3987] for security considerations relating to IRIs. See 633 [RFC3986] for security considerations relating to URIs. See 634 [RFC7230] for security considerations relating to HTTP headers. 636 9. Internationalisation Considerations 638 Link targets may need to be converted to URIs in order to express 639 them in serialisations that do not support IRIs. This includes the 640 Link HTTP header field. 642 Similarly, the anchor parameter of the Link header field does not 643 support IRIs, and therefore IRIs must be converted to URIs before 644 inclusion there. 646 Relation types are defined as URIs, not IRIs, to aid in their 647 comparison. It is not expected that they will be displayed to end 648 users. 650 Note that registered Relation Names are required to be lower-case 651 ASCII letters. 653 10. References 655 10.1. Normative References 657 [I-D.ietf-httpbis-rfc5987bis] 658 Reschke, J., "Indicating Character Encoding and Language 659 for HTTP Header Field Parameters", draft-ietf-httpbis- 660 rfc5987bis-03 (work in progress), July 2016. 662 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 663 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 664 RFC2119, March 1997, 665 . 667 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 668 Procedures for Message Header Fields", BCP 90, RFC 3864, 669 DOI 10.17487/RFC3864, September 2004, 670 . 672 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 673 Resource Identifier (URI): Generic Syntax", STD 66, RFC 674 3986, DOI 10.17487/RFC3986, January 2005, 675 . 677 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 678 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 679 January 2005, . 681 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 682 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 683 DOI 10.17487/RFC5226, May 2008, 684 . 686 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 687 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 688 September 2009, . 690 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 691 Specifications and Registration Procedures", BCP 13, RFC 692 6838, DOI 10.17487/RFC6838, January 2013, 693 . 695 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 696 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 697 7230, DOI 10.17487/RFC7230, June 2014, 698 . 700 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 701 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 702 10.17487/RFC7231, June 2014, 703 . 705 [W3C.CR-css3-mediaqueries-20090915] 706 Lie, H., Celik, T., Glazman, D., and A. Kesteren, "Media 707 Queries", World Wide Web Consortium CR CR-css3- 708 mediaqueries-20090915, September 2009, 709 . 711 10.2. Informative References 713 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. 714 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 715 RFC 2068, DOI 10.17487/RFC2068, January 1997, 716 . 718 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 719 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 720 Transfer Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/ 721 RFC2616, June 1999, 722 . 724 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 725 HTTP/1.1", RFC 2817, DOI 10.17487/RFC2817, May 2000, 726 . 728 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/ 729 RFC2818, May 2000, 730 . 732 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 733 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 734 December 2005, . 736 [W3C.REC-html-rdfa-20150317] 737 Sporny, M., "HTML+RDFa 1.1 - Second Edition", World Wide 738 Web Consortium Recommendation REC-html-rdfa-20150317, 739 March 2015, 740 . 742 [W3C.REC-html5-20141028] 743 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 744 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 745 World Wide Web Consortium Recommendation REC- 746 html5-20141028, October 2014, 747 . 749 [W3C.REC-xml-names-20091208] 750 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 751 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 752 Wide Web Consortium Recommendation REC-xml-names-20091208, 753 December 2009, 754 . 756 Appendix A. Notes on Other Link Serialisations 758 Header fields (Section 6) are only one serialisation of links; other 759 specifications have defined alternative serialisations. 761 A.1. Link Serialisation in HTML 763 HTML [W3C.REC-html5-20141028] motivated the original syntax of the 764 Link header field, and many of the design decisions in this document 765 are driven by a desire to stay compatible with it. 767 In HTML, the link element can be mapped to links as specified here by 768 using the "href" attribute for the target URI, and "rel" to convey 769 the relation type, as in the Link header field. The context of the 770 link is the URI associated with the entire HTML document. 772 All of the link relation types defined by HTML have been included in 773 the Link Relation Type registry, so they can be used without 774 modification. However, there are several potential ways to serialise 775 extension relation types into HTML, including: 777 o As absolute URIs, 779 o using the RDFa [W3C.REC-html-rdfa-20150317] convention of mapping 780 token prefixes to URIs (in a manner similar to XML name spaces). 782 Individual applications of linking will therefore need to define how 783 their extension links should be serialised into HTML. 785 Surveys of existing HTML content have shown that unregistered link 786 relation types that are not URIs are (perhaps inevitably) common. 787 Consuming HTML implementations ought not consider such unregistered 788 short links to be errors, but rather relation types with a local 789 scope (i.e., their meaning is specific and perhaps private to that 790 document). 792 HTML also defines several attributes on links that can be seen as 793 target attributes, including "media", "hreflang", "type" and "sizes". 795 Finally, the HTML specification gives a special meaning when the 796 "alternate" and "stylesheet" relation types coincide in the same 797 link. Such links ought to be serialised in the Link header field 798 using a single list of relation-types (e.g., rel="alternate 799 stylesheet") to preserve this relationship. 801 A.2. Link Serialisation in Atom 803 Atom [RFC4287] is a link serialisation that conveys links in the 804 atom:link element, with the "href" attribute indicating the link 805 target and the "rel" attribute containing the relation type. The 806 context of the link is either a feed locator or an entry ID, 807 depending on where it appears; generally, feed-level links are 808 obvious candidates for transmission as a Link header field. 810 When serialising an atom:link into a Link header field, it is 811 necessary to convert link targets (if used) to URIs. 813 Atom defines extension relation types in terms of IRIs. This 814 specification re-defines them as URIs, to simplify and reduce errors 815 in their comparison. 817 Atom allows registered link relation types to be serialised as 818 absolute URIs using a prefix, "http://www.iana.org/assignments/ 819 relation/". This prefix is specific to the Atom serialisation. 821 Furthermore, link relation types are always compared in a case- 822 sensitive fashion; therefore, registered link relation types SHOULD 823 be converted to their registered form (usually, lowercase) when 824 serialised in an Atom document. 826 Note also that while the Link header field allows multiple relations 827 to be serialised in a single link, atom:link does not. In this case, 828 a single link-value may map to several atom:link elements. 830 As with HTML, atom:link defines some attributes that are not 831 explicitly mirrored in the Link header field syntax, but they can 832 also be used as link-extensions to maintain fidelity. 834 Appendix B. Algorithm for Parsing Link Headers 836 Given a HTTP header field-value "field_value" as a string assuming 837 ASCII encoding, the following algorithm can be used to parse it into 838 the model described by this specification: 840 1. Let "links" be an empty list. 842 2. Create "link_strings" by splitting "field_value" on "," 843 characters, excepting "," characters within quoted strings as per 844 [RFC7230], Section 3.2.6, or which form part of link's URI- 845 Reference (i.e. between "<" and ">" characters where the "<" is 846 immediately preceded by OWS and either a "," character or the 847 beginning of the "field_value" string). 849 3. For each "link_string" in "link_strings": 851 1. Let "target_string" be the string between the first "<" and 852 first ">" characters in "link_string". If they do not 853 appear, or do not appear in that order, fail parsing. 855 2. Let "rest" be the remaining characters (if any) after the 856 first ">" character in "link_string". 858 3. Split "rest" into an array of strings "parameter_strings", 859 on the ";" character, excepting ";" characters within quoted 860 strings as per [RFC7230], Section 3.2.6. 862 4. Let "link_parameters" be an empty array. 864 5. For each item "parameter" in "parameter_strings": 866 1. Remove OWS from the beginning and end of "parameter". 868 2. Skip this item if "parameter" matches the empty string 869 (""). 871 3. Split "parameter" into "param_name" and "param_value" on 872 the first "=" character. If "parameter" does not 873 contain "=", let "param_name" be "parameter" and 874 "param_value" be null. 876 4. Remove OWS from the end of "param_name" and the 877 beginning of "param_value". 879 5. Case-normalise "param_name" to lowercase. 881 6. If the first and last characters of "param_value" are 882 both DQUOTE: 884 1. Remove the first and last characters of 885 "param_value". 887 2. Replace quoted-pairs within "param_value" with the 888 octet following the backslash, as per [RFC7230], 889 Section 3.2.6. 891 7. If the last character of "param_name" is an asterisk 892 ("*"), decode "param_value" according to 893 [I-D.ietf-httpbis-rfc5987bis]. Skip this item if an 894 unrecoverable error is encountered. 896 8. Append the tuple ("param_name", "param_value") to 897 "link_parameters". 899 6. Let "target" be the result of relatively resolving (as per 900 [RFC3986], Section 5.2) "target_string". Note that any base 901 URI carried in the payload body is NOT used. 903 7. Let "relations_string" be the second item of the first tuple 904 of "link_parameters" whose first item matches the string 905 "rel", or the empty string ("") if it is not present. 907 8. Split "relations_string" into an array of strings 908 "relation_types", on RWS (removing all whitespace in the 909 process). 911 9. Let "context_string" be the second item of the first tuple 912 of "link_parameters" whose first item matches the string 913 "anchor". If it is not present, "context_string" is the 914 identity of the representation carrying the Link header 915 [RFC7231], Section 3.1.4.1, serialised as a URI. Where the 916 identity is "anonymous" "context_string" is null. 918 10. Let "context" be the result of relatively resolving (as per 919 [RFC3986], Section 5.2) "context_string", unless 920 "context_string" is null in which case "context" is null. 921 Note that any base URI carried in the payload body is NOT 922 used. 924 11. Let "target_attributes" be an empty array. 926 12. For each tuple ("param_name", "param_value") of 927 "link_parameters": 929 1. If "param_name" matches "rel" or "anchor", skip this 930 tuple. 932 2. If "param_name" matches "media", "title", "title*" or 933 "type" and "target_attributes" already contains a tuple 934 whose first element matches the value of "param_name", 935 skip this tuple. 937 3. Append ("param_name", "param_value") to 938 "target_attributes". 940 13. Let "star_param_names" be the set of "param_name"s in the 941 ("param_name", "param_value") tuples of "link_parameters" 942 where the last character of "param_name" is an asterisk 943 ("*"). 945 14. For each "star_param_name" in "star_param_names": 947 1. Let "base_param_name" be "star_param_name" with the last 948 character removed. 950 2. If the implementation does not choose to support an 951 internationalised form of a parameter named 952 "base_param_name" for any reason (including, but not 953 limited to, it being prohibited by the parameter's 954 specification), remove all tuples from "link_parameters" 955 whose first member is "star_param_name" and skip to the 956 next "star_param_name". 958 3. Remove all tuples from "link_parameters" whose first 959 member is "base_param_name". 961 4. Change the first member of all tuples in 962 "link_parameters" whose first member is 963 "star_param_name" to "base_param_name". 965 15. For each "relation_type" in "relation_types": 967 1. Case-normalise "relation_type" to lowercase. 969 2. Append a link object to "links" with the target 970 "target", relation type of "relation_type", context of 971 "context", and target attributes "target_attributes". 973 4. Return "links". 975 Appendix C. Changes from RFC5988 977 This specification has the following differences from its 978 predecessor, RFC5988: 980 o The initial relation type registrations were removed, since 981 they've already been registered by 5988. 983 o The introduction has been shortened. 985 o The Link Relation Application Data Registry has been removed. 987 o Incorporated errata. 989 o Updated references. 991 o Link cardinality was clarified. 993 o Terminology was changed from "target IRI" and "context IRI" to 994 "link target" and "link context" respectively. 996 o Made assigning a URI to registered relation types serialisation- 997 specific. 999 o Removed misleading statement that the link header field is 1000 semantically equivalent to HTML and Atom links. 1002 o More carefully defined how the Experts and IANA should interact. 1004 o More carefully defined and used "link serialisations" and "link 1005 applications." 1007 o Clarified the cardinality of target attributes (generically and 1008 for "type"). 1010 o Corrected the default link context for the Link header field, to 1011 be dependent upon the identity of the representation (as per 1012 RFC7231). 1014 o Defined a suggested parsing algorithm for the Link header. 1016 o The value space of target attributes and their definition has been 1017 specified. 1019 o The ABNF has been updated to be compatible with [RFC7230]. In 1020 particular, whitespace is now explicit. 1022 o Some parameters on the HTTP header field can now appear as a 1023 token. 1025 o Handling of quoted strings is now defined by [RFC7230]. 1027 o The "type" header field parameter now needs to be quoted (as 1028 "token" does not allow "/"). 1030 Author's Address 1032 Mark Nottingham 1034 EMail: mnot@mnot.net 1035 URI: https://www.mnot.net/