idnits 2.17.00 (12 Aug 2021) /tmp/idnits11595/draft-nottingham-rfc5988bis-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC5988, but the abstract doesn't seem to directly say this. It does mention RFC5988 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 11, 2017) is 1737 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: draft-ietf-httpbis-rfc5987bis has been published as RFC 8187 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft August 11, 2017 4 Obsoletes: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: February 12, 2018 8 Web Linking 9 draft-nottingham-rfc5988bis-08 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 _RFC EDITOR: please remove this section before publication_ 24 This is a work-in-progress to revise RFC5988. 26 The issues list can be found at https://github.com/mnot/I-D/labels/ 27 rfc5988bis. 29 The most recent (often, unpublished) draft is at 30 https://mnot.github.io/I-D/rfc5988bis/. 32 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 33 pages/rfc5988bis. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at http://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on February 12, 2018. 51 Copyright Notice 53 Copyright (c) 2017 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (http://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 This document may contain material from IETF Documents or IETF 67 Contributions published or made publicly available before November 68 10, 2008. The person(s) controlling the copyright in some of this 69 material may not have granted the IETF Trust the right to allow 70 modifications of such material outside the IETF Standards Process. 71 Without obtaining an adequate license from the person(s) controlling 72 the copyright in such materials, this document may not be modified 73 outside the IETF Standards Process, and derivative works of it may 74 not be created outside the IETF Standards Process, except to format 75 it for publication as an RFC or to translate it into languages other 76 than English. 78 Table of Contents 80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 81 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 82 1.2. Conformance and Error Handling . . . . . . . . . . . . . 4 83 2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 84 2.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 5 85 2.1.1. Registered Relation Types . . . . . . . . . . . . . . 5 86 2.1.2. Extension Relation Types . . . . . . . . . . . . . . 7 87 2.2. Target Attributes . . . . . . . . . . . . . . . . . . . . 8 88 3. Link Serialisation in HTTP Headers . . . . . . . . . . . . . 8 89 3.1. Link Target . . . . . . . . . . . . . . . . . . . . . . . 9 90 3.2. Link Context . . . . . . . . . . . . . . . . . . . . . . 9 91 3.3. Relation Type . . . . . . . . . . . . . . . . . . . . . . 10 92 3.4. Target Attributes . . . . . . . . . . . . . . . . . . . . 11 93 3.4.1. Serialisation-Defined Attributes . . . . . . . . . . 11 94 3.4.2. Extension Attributes . . . . . . . . . . . . . . . . 12 95 3.5. Link Header Field Examples . . . . . . . . . . . . . . . 12 96 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 97 4.1. Link HTTP Header Field Registration . . . . . . . . . . . 14 98 4.2. Link Relation Type Registry . . . . . . . . . . . . . . . 14 99 4.3. Link Relation Application Data Registry . . . . . . . . . 14 100 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 101 6. Internationalisation Considerations . . . . . . . . . . . . . 15 102 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 103 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 104 7.2. Informative References . . . . . . . . . . . . . . . . . 17 105 Appendix A. Notes on Other Link Serialisations . . . . . . . . . 18 106 A.1. Link Serialisation in HTML . . . . . . . . . . . . . . . 18 107 A.2. Link Serialisation in Atom . . . . . . . . . . . . . . . 18 108 Appendix B. Algorithms for Parsing Link Header Fields . . . . . 19 109 B.1. Parsing a Header Set for Links . . . . . . . . . . . . . 19 110 B.2. Parsing a Link Field Value . . . . . . . . . . . . . . . 20 111 B.3. Parsing Parameters . . . . . . . . . . . . . . . . . . . 22 112 B.4. Parsing a Quoted String . . . . . . . . . . . . . . . . . 23 113 Appendix C. Changes from RFC5988 . . . . . . . . . . . . . . . . 24 114 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 116 1. Introduction 118 This specification defines a model for the relationships between 119 resources on the Web ("links") and the type of those relationships 120 ("link relation types"). 122 HTML [W3C.REC-html5-20141028] and Atom [RFC4287] both have well- 123 defined concepts of linking; Section 2 generalises this into a 124 framework that encompasses linking in these formats and (potentially) 125 elsewhere. 127 Furthermore, Section 3 defines an HTTP header field for conveying 128 such links. 130 1.1. Notational Conventions 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 134 "OPTIONAL" in this document are to be interpreted as described in BCP 135 14 [RFC2119],[RFC8174] when, and only when, they appear in all 136 capitals, as shown here. 138 This document uses the Augmented Backus-Naur Form (ABNF) notation of 139 [RFC7230], including the #rule, and explicitly includes the following 140 rules from it: quoted-string, token, SP (space), BWS (bad 141 whitespace), OWS (optional whitespace), RWS (required whitespace) 142 LOALPHA, DIGIT. 144 Additionally, the following rules are included from [RFC3986]: URI 145 and URI-Reference; from [RFC6838]: type-name and subtype-name; from 146 [W3C.REC-css3-mediaqueries-20120619]: media-query-list; and from 147 [RFC5646]: Language-Tag. 149 1.2. Conformance and Error Handling 151 The requirements regarding conformance and error handling highlighted 152 in [RFC7230], Section 2.5 apply to this document. 154 2. Links 156 In this specification, a link is a typed connection between two 157 resources, and is comprised of: 159 o A _link context_, 161 o a _link relation type_ (Section 2.1), 163 o a _link target_, and 165 o optionally, _target attributes_ (Section 2.2). 167 A link can be viewed as a statement of the form "_link context_ has a 168 _link relation type_ resource at _link target_, which has _target 169 attributes_". 171 For example, https://www.example.com/ has a "canonical" resource at 172 https://example.com, which has a "type" of "text/html". 174 Link contexts and link targets are both IRIs [RFC3987]. However, in 175 the common case, the link context will also be a URI [RFC3986], 176 because many protocols (such as HTTP) do not support dereferencing 177 IRIs. Likewise, the link target will be sometimes be converted to a 178 URI (see [RFC3987], Section 3.1) in serialisations that do not 179 support IRIs (such as the Link header field defined in Section 3). 181 This specification does not place restrictions on the cardinality of 182 links; there can be multiple links to and from a particular target, 183 and multiple links of the same or different types between a given 184 context and target. Likewise, the relative ordering of links in any 185 particular serialisation, or between serialisations (e.g., the Link 186 header field and in-content links) is not specified or significant in 187 this specification; applications that wish to consider ordering 188 significant can do so. 190 Links are conveyed in _link serialisations_; they are the "bytes on 191 the wire", and can occur in various forms. For example, Atom 193 [RFC4287] and HTML [W3C.REC-html5-20141028] both defined 194 serialisations of links into their respective formats, and Section 3 195 defines how to serialise links in HTTP header fields. 197 This specification does not define a general syntax for links across 198 different serialisations, nor does it mandate a specific context for 199 any given link; it is expected that serialisations of links will 200 specify both aspects. 202 Finally, links are used by _link applications_. Generally, an 203 application will define the link relation type(s) it uses, along with 204 the serialisation(s) that they might occur within. For example, the 205 application "Web browsing" looks for the "stylesheet" link relation 206 type in the HTML link serialisation (and optionally in the Link 207 header field), whereas the application "AtomPub" uses the "edit" and 208 "edit-media" link relations in the Atom serialisation. 210 2.1. Link Relation Types 212 In the simplest case, a link relation type identifies the semantics 213 of a link. For example, a link with the relation type "copyright" 214 indicates that the current link context has a copyright resource at 215 the link target. 217 Link relation types can also be used to indicate that the target 218 resource has particular attributes, or exhibits particular 219 behaviours; for example, a "service" link implies that the link 220 target can be used as part of a defined protocol (in this case, a 221 service description). 223 Relation types are not to be confused with media types [RFC2046]; 224 they do not identify the format of the representation that results 225 when the link is dereferenced. Rather, they only describe how the 226 current context is related to another resource. 228 Relation types SHOULD NOT infer any additional semantics based upon 229 the presence or absence of another link relation type, or its own 230 cardinality of occurrence. An exception to this is the combination 231 of the "alternate" and "stylesheet" registered relation types, which 232 has special meaning in HTML for historical reasons. 234 There are two kinds of relation types: registered and extension. 236 2.1.1. Registered Relation Types 238 Well-defined relation types can be registered as tokens for 239 convenience and/or to promote reuse by other applications, using the 240 procedure in Section 2.1.1.1. 242 Registered relation type names MUST conform to the reg-rel-type rule 243 (see Section 3.3), and MUST be compared character-by-character in a 244 case-insensitive fashion. They SHOULD be appropriate to the 245 specificity of the relation type; i.e., if the semantics are highly 246 specific to a particular application, the name should reflect that, 247 so that more general names are available for less specific use. 249 Registered relation types MUST NOT constrain the media type of the 250 link context, and MUST NOT constrain the available representation 251 media types of the link target. However, they can specify the 252 behaviours and properties of the target resource (e.g., allowable 253 HTTP methods, request and response media types that are required be 254 supported). 256 Historically, registered relation types have been identified with a 257 URI [RFC3986] by prefixing their names with an application-defined 258 base URI (e.g., see Appendix A.2). This practice is NOT RECOMMENDED, 259 because the resulting strings will not be considered equivalent to 260 the registered relation types by other applications. Applications 261 that do use such URIs internally MUST NOT use them in link 262 serialisations that do not explicitly accommodate them. 264 2.1.1.1. Registering Link Relation Types 266 The link relations registry is located at 267 https://www.iana.org/assignments/link-relations/. Registration 268 requests can be made by following the instructions located there, or 269 by sending an e-mail to the "link-relations@ietf.org" mailing list. 271 Registration requests consist of at least the following information: 273 o *Relation Name*: The name of the relation type 275 o *Description*: A short English description of the type's 276 semantics. It SHOULD be stated in terms of the relationship 277 between the link context and link target. 279 o *Reference*: Reference to the document that specifies the link 280 relation type, preferably including a URI that can be used to 281 retrieve a copy of the document. An indication of the relevant 282 section(s) can also be included, but is not required. 284 The expert(s) can define additional fields to be collected in the 285 registry. 287 General requirements for registered relation types are described in 288 Section 2.1.1. 290 Registrations MUST reference a freely available, stable 291 specification. 293 Note that relation types can be registered by third parties 294 (including the expert(s)), if the expert(s) determine that an 295 unregistered relation type is widely deployed and not likely to be 296 registered in a timely manner otherwise. Such registrations still 297 are subject to the requirements defined, including the need to 298 reference a specification. 300 2.1.1.2. Registration Request Processing 302 Relation types are registered using the Specification Required policy 303 (see Section 4.6 of [RFC8126]), which implies review and approval by 304 a designated expert. 306 The goal of the registry is to reflect common use of links on the 307 Internet. Therefore, the expert(s) should be strongly biased towards 308 approving registrations, unless they are abusive, frivolous, not 309 likely to be used on the Internet, or actively harmful to the 310 Internet and/or the Web (not merely aesthetically displeasing, or 311 architecturally dubious). As stated in Section 2.1.1, the expert(s) 312 can withhold registration of names that are too general for the 313 proposed application. 315 The expert(s) will clearly identify any issues which cause a 316 registration to be refused. Advice about the semantics of a proposed 317 link relation type can be given, but if it does not block 318 registration, this should be explicitly stated. 320 When a request is approved, the expert(s) will inform IANA, and the 321 registration will be processed. The IESG is the final arbiter of any 322 objection. 324 2.1.2. Extension Relation Types 326 Applications that don't wish to register a relation type can use an 327 extension relation type, which is a URI [RFC3986] that uniquely 328 identifies the relation type. Although the URI can point to a 329 resource that contains a definition of the semantics of the relation 330 type, clients SHOULD NOT automatically access that resource to avoid 331 overburdening its server. 333 The URI used for an extension relation type SHOULD be under the 334 control of the person or party defining it, or be delegated to them. 336 When extension relation types are compared, they MUST be compared as 337 strings (after converting to URIs if serialised in a different 338 format) in a case-insensitive fashion, character-by-character. 339 Because of this, all-lowercase URIs SHOULD be used for extension 340 relations. 342 Note that while extension relation types are required to be URIs, a 343 serialisation of links can specify that they are expressed in another 344 form, as long as they can be converted to URIs. 346 2.2. Target Attributes 348 _Target attributes_ are a list of key/value pairs that describe the 349 link or its target; for example, a media type hint. 351 They can be defined both by individual link relation types and by 352 link serialisations. 354 This specification does not attempt to coordinate the name of target 355 attributes, their cardinality or use. Those creating and maintaining 356 serialisations SHOULD coordinate their target attributes to avoid 357 conflicts in semantics or syntax, and MAY define their own registries 358 of target attributes. 360 The names of target attributes SHOULD conform to the token rule, but 361 SHOULD NOT include any of the characters "%", "'" or "*", for 362 portability across serializations, and MUST be compared in a case- 363 insensitive fashion. 365 Target attribute definitions SHOULD specify: 367 o The serialisation of their values into Unicode or a subset 368 thereof, to maximise their chances of portability across link 369 serialisations. 371 o The semantics and error handling of multiple occurrences of the 372 target attribute on a given link. 374 This specification does define target attributes for use in the Link 375 HTTP header field in Section 3.4. 377 3. Link Serialisation in HTTP Headers 379 The Link header field provides a means for serialising one or more 380 links into HTTP headers. 382 The ABNF for the field value is: 384 Link = #link-value 385 link-value = "<" URI-Reference ">" *( OWS ";" OWS link-param ) 386 link-param = token BWS [ "=" BWS ( token / quoted-string ) ] 388 Note that any "link-param" can be generated with values using either 389 the "token" or the "quoted-string" syntax, and therefore recipients 390 MUST be able to parse both forms. In other words, the following 391 parameters are equivalent: 393 x=y 394 x="y" 396 Previous definitions of the Link header did not equate the token and 397 quoted-string forms explicitly; the "title" parameter was always 398 quoted, and the "hreflang" parameter was always a token. Senders 399 wishing to maximize interoperability will send them in those forms. 401 Individual "link-param"s specify their syntax in terms of the value 402 after any necessary unquoting (as per [RFC7230], Section 3.2.6). 404 This specification establishes the link-params "rel", "anchor", and 405 "rev" (which are part of the general link model), as well as 406 "hreflang", "media", "title", "title*", and "type" (which are target 407 attributes defined by the serialization. 409 3.1. Link Target 411 Each link-value conveys one target IRI as a URI-Reference (after 412 conversion to one, if necessary; see [RFC3987], Section 3.1) inside 413 angle brackets ("<>"). If the URI-Reference is relative, parsers 414 MUST resolve it as per [RFC3986], Section 5. Note that any base IRI 415 appearing in the message's content is not applied. 417 3.2. Link Context 419 By default, the context of a link conveyed in the Link header field 420 is the URL of the representation it is associated with, as defined in 421 [RFC7231], Section 3.1.4.1, serialised as a URI. 423 When present, the anchor parameter overrides this with another URI, 424 such as a fragment of this resource, or a third resource (i.e., when 425 the anchor value is an absolute URI). If the anchor parameter's 426 value is a relative URI, parsers MUST resolve it as per [RFC3986], 427 Section 5. Note that any base URI from the body's content is not 428 applied. 430 The ABNF for the "anchor" parameter's value is: 432 URI-Reference ; Section 4.1 of {{RFC3986}} 434 Link application can choose to ignore links with an anchor parameter. 435 For example, the application in use might not allow the link context 436 to be assigned to a different resource. In such cases, the entire 437 link is to be ignored; link applications MUST NOT process the link 438 without applying the anchor. 440 Note that depending on HTTP status code and response headers, the 441 link context might be "anonymous" (i.e., no link context is 442 available). For example, this is the case on a 404 response to a GET 443 request. 445 3.3. Relation Type 447 The relation type of a link conveyed in the Link header field is 448 conveyed in the "rel" parameter's value. The "rel" parameter MUST be 449 present but MUST NOT appear more than once in a given link-value; 450 occurrences after the first MUST be ignored by parsers. 452 The "rel" parameter can, however, contain multiple link relation 453 types. When this occurs, it establishes multiple links that share 454 the same context, target, and target attributes. 456 The "rev" parameter has been used in the past to indicate that the 457 semantics of the relationship are in the reverse direction. That is, 458 a link from A to B with REL="X" expresses the same relationship as a 459 link from B to A with REV="X". "rev" is deprecated by this 460 specification because it often confuses authors and readers; in most 461 cases, using a separate relation type is preferable. 463 The ABNF for the "rel" and "rev" parameters' values is: 465 relation-type *( 1*SP relation-type ) 467 where: 469 relation-type = reg-rel-type / ext-rel-type 470 reg-rel-type = LOALPHA *( LOALPHA / DIGIT / "." / "-" ) 471 ext-rel-type = URI ; Section 3 of {{RFC3986}} 473 Note that extension relation types are REQUIRED to be absolute URIs 474 in Link header fields, and MUST be quoted when they contain 475 characters not allowed in tokens, such as semicolon (";") or comma 476 (",") (as these characters are used as delimiters in the header field 477 itself). 479 3.4. Target Attributes 481 The Link header field defines several target attributes specific to 482 this serialisation, and also allows extension target attributes. 483 Target attributes are serialised in the Link header field as 484 parameters (see [RFC7231], Section 3.1.1.1 for the definition of 485 their syntax). 487 3.4.1. Serialisation-Defined Attributes 489 The "hreflang", "media", "title", "title*", and "type" link-params 490 can be translated to serialisation-defined target attributes for the 491 link. 493 The "hreflang" attribute, when present, is a hint indicating what the 494 language of the result of dereferencing the link should be. Note 495 that this is only a hint; for example, it does not override the 496 Content-Language header field of a HTTP response obtained by actually 497 following the link. Multiple "hreflang" attributes on a single link- 498 value indicate that multiple languages are available from the 499 indicated resource. 501 The ABNF for the "hreflang" parameter's value is: 503 Language-Tag 505 The "media" attribute, when present, is used to indicate intended 506 destination medium or media for style information (see 507 [W3C.REC-html5-20141028], Section 4.2.4). Its value MUST be quoted 508 if it contains a semicolon (";") or comma (","). There MUST NOT be 509 more than one "media" attribute in a link-value; occurrences after 510 the first MUST be ignored by parsers. 512 The ABNF for the "media" parameter's value is: 514 media-query-list 516 The "title" attribute, when present, is used to label the destination 517 of a link such that it can be used as a human-readable identifier 518 (e.g., a menu entry) in the language indicated by the Content- 519 Language header field (if present). The "title" attribute MUST NOT 520 appear more than once in a given link; occurrences after the first 521 MUST be ignored by parsers. 523 The "title*" link-param can be used to encode this attribute in a 524 different character set, and/or contain language information as per 525 [I-D.ietf-httpbis-rfc5987bis]. The "title*" link-param MUST NOT 526 appear more than once in a given link-value; occurrences after the 527 first MUST be ignored by parsers. If the attribute does not contain 528 language information, its language is indicated by the Content- 529 Language header field (when present). 531 If both the "title" and "title*" link-param appear in a link, 532 applications SHOULD use the "title*" link-param's value for the 533 "title" attribute. 535 The "type" attribute, when present, is a hint indicating what the 536 media type of the result of dereferencing the link should be. Note 537 that this is only a hint; for example, it does not override the 538 Content-Type header field of a HTTP response obtained by actually 539 following the link. The "type" attribute MUST NOT appear more than 540 once in a given link-value; occurrences after the first MUST be 541 ignored by parsers. 543 The ABNF for the "type" parameter's value is: 545 type-name "/" subtype-name ; see {{RFC6838}}, Section 4.2 547 3.4.2. Extension Attributes 549 Other link-params are link-extensions, and are to be considered as 550 target attributes. 552 Such target attributes MAY be defined to use the encoding in 553 [I-D.ietf-httpbis-rfc5987bis] (e.g., "example" and "example*"). When 554 both forms are present, they SHOULD be considered to be the same 555 target attribute; applications SHOULD use the value of the name 556 ending in "*" (after [I-D.ietf-httpbis-rfc5987bis] decoding), but MAY 557 fall back to the other value if there is an error in decoding it, or 558 if they do not support decoding. 560 3.5. Link Header Field Examples 562 For example: 564 Link: ; rel="previous"; 565 title="previous chapter" 567 indicates that "chapter2" is previous to this resource in a logical 568 navigation path. 570 Similarly, 572 Link: ; rel="http://example.net/foo" 573 indicates that the root resource ("/") is related to this resource 574 with the extension relation type "http://example.net/foo". 576 This link: 578 Link: ; rel="copyright"; anchor="#foo" 580 indicates that the linked copyright terms only apply to the portion 581 of the document indicated by the (media type-specific) fragment 582 identifier "foo". 584 The example below shows an instance of the Link header field encoding 585 multiple links, and also the use of RFC 5987 encoding to encode both 586 non-ASCII characters and language information. 588 Link: ; 589 rel="previous"; title*=UTF-8'de'letztes%20Kapitel, 590 ; 591 rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel 593 Here, both links have titles encoded in UTF-8, use the German 594 language ("de"), and the second link contains the Unicode code point 595 U+00E4 ("LATIN SMALL LETTER A WITH DIAERESIS"). 597 Note that link-values can convey multiple links between the same link 598 target and link context; for example: 600 Link: ; 601 rel="start http://example.net/relation/other" 603 Here, the link to "http://example.org/" has the registered relation 604 type "start" and the extension relation type 605 "http://example.net/relation/other". 607 Finally, this header field: 609 Link: ; rel="start", 610 ; rel="index" 612 is equivalent to these: 614 Link: ; rel="start" 615 Link: ; rel="index" 617 4. IANA Considerations 619 4.1. Link HTTP Header Field Registration 621 This specification updates the Message Header registry entry for 622 "Link" in HTTP [RFC3864] to refer to this document. 624 Header field: Link 625 Applicable protocol: http 626 Status: standard 627 Author/change controller: 628 IETF (iesg@ietf.org) 629 Internet Engineering Task Force 630 Specification document(s): 631 [this document] 633 4.2. Link Relation Type Registry 635 This specification updates the registration procedures for the Link 636 Relation Type registry; see Section 2.1.1.1. 638 IANA will direct any incoming requests regarding the registry to this 639 document and, if defined, the processes established by the expert(s); 640 typically, this will mean referring them to the registry Web page. 642 Note that the expert(s) are allowed (as per Section 2.1.1.1) to 643 define additional fields to be collected in the registry. 645 4.3. Link Relation Application Data Registry 647 This specification removes the Link Relation Application Data 648 Registry, as it has not been used, and future use is not anticipated. 649 IANA is instructed to remove it. 651 5. Security Considerations 653 The content of the Link header field is not secure, private or 654 integrity-guaranteed. Use of Transport Layer Security (TLS) with 655 HTTP ([RFC2818]) is currently the only end-to-end way to provide 656 these properties. 658 Link applications ought to consider the attack vectors opened by 659 automatically following, trusting, or otherwise using links gathered 660 from HTTP header fields. 662 For example, Link header fields that use the "anchor" parameter to 663 associate a link's context with another resource cannot be trusted 664 since they are effectively assertions by a third party that could be 665 incorrect or malicious. Applications can mitigate this risk by 666 specifying that such links should be discarded unless some 667 relationship between the resources is established (e.g., they share 668 the same authority). 670 Dereferencing links has a number of risks, depending on the 671 application in use. For example, the Referer header [RFC7231] can 672 expose information about the application's state (including private 673 information) in its value. Likewise, cookies [RFC6265] are another 674 mechanism that, if used, can become an attack vector. Applications 675 can mitigate these risks by carefully specifying how such mechanisms 676 should operate. 678 The Link header field makes extensive use of IRIs and URIs. See 679 [RFC3987] Section 8 for security considerations relating to IRIs. 680 See [RFC3986] Section 7 for security considerations relating to URIs. 681 See [RFC7230] Section 9 for security considerations relating to HTTP 682 header fields. 684 6. Internationalisation Considerations 686 Link targets may need to be converted to URIs in order to express 687 them in serialisations that do not support IRIs. This includes the 688 Link HTTP header field. 690 Similarly, the anchor parameter of the Link header field does not 691 support IRIs, and therefore IRIs must be converted to URIs before 692 inclusion there. 694 Relation types are defined as URIs, not IRIs, to aid in their 695 comparison. It is not expected that they will be displayed to end 696 users. 698 Note that registered Relation Names are required to be lower-case 699 ASCII letters. 701 7. References 703 7.1. Normative References 705 [I-D.ietf-httpbis-rfc5987bis] 706 Reschke, J., "Indicating Character Encoding and Language 707 for HTTP Header Field Parameters", draft-ietf-httpbis- 708 rfc5987bis-05 (work in progress), February 2017. 710 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 711 Requirement Levels", BCP 14, RFC 2119, 712 DOI 10.17487/RFC2119, March 1997, 713 . 715 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 716 Procedures for Message Header Fields", BCP 90, RFC 3864, 717 DOI 10.17487/RFC3864, September 2004, 718 . 720 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 721 Resource Identifier (URI): Generic Syntax", STD 66, 722 RFC 3986, DOI 10.17487/RFC3986, January 2005, 723 . 725 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 726 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 727 January 2005, . 729 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 730 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 731 September 2009, . 733 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 734 Specifications and Registration Procedures", BCP 13, 735 RFC 6838, DOI 10.17487/RFC6838, January 2013, 736 . 738 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 739 Protocol (HTTP/1.1): Message Syntax and Routing", 740 RFC 7230, DOI 10.17487/RFC7230, June 2014, 741 . 743 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 744 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 745 DOI 10.17487/RFC7231, June 2014, 746 . 748 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 749 Writing an IANA Considerations Section in RFCs", BCP 26, 750 RFC 8126, DOI 10.17487/RFC8126, June 2017, 751 . 753 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 754 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 755 May 2017, . 757 [W3C.REC-css3-mediaqueries-20120619] 758 Rivoal, F., "Media Queries", World Wide Web Consortium 759 Recommendation REC-css3-mediaqueries-20120619, June 2012, 760 . 763 7.2. Informative References 765 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 766 Extensions (MIME) Part Two: Media Types", RFC 2046, 767 DOI 10.17487/RFC2046, November 1996, 768 . 770 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 771 DOI 10.17487/RFC2818, May 2000, 772 . 774 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 775 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 776 December 2005, . 778 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 779 DOI 10.17487/RFC6265, April 2011, 780 . 782 [W3C.REC-html5-20141028] 783 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 784 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 785 World Wide Web Consortium Recommendation REC- 786 html5-20141028, October 2014, 787 . 789 Appendix A. Notes on Other Link Serialisations 791 Header fields (Section 3) are only one serialisation of links; other 792 specifications have defined alternative serialisations. 794 A.1. Link Serialisation in HTML 796 HTML motivated the original syntax of the Link header field, and many 797 of the design decisions in this document are driven by a desire to 798 stay compatible with it. 800 In HTML, the link element can be mapped to links as specified here by 801 using the "href" attribute for the target URI, and "rel" to convey 802 the relation type, as in the Link header field. The context of the 803 link is the URI associated with the entire HTML document. HTML also 804 defines several attributes on links that can be seen as target 805 attributes, including "media", "hreflang", "type" and "sizes". 807 Section 4.8 of HTML5 ([W3C.REC-html5-20141028]) defines modern HTML 808 links. That document links to the Microformats Wiki as a registry; 809 over time, the IANA registry ought to mirror its contents, and 810 ideally eventually replace it (although that depends on the HTML 811 community). 813 Surveys of existing HTML content have shown that unregistered link 814 relation types that are not URIs are (perhaps inevitably) common. 815 Consuming HTML implementations ought not consider such unregistered 816 short links to be errors, but rather relation types with a local 817 scope (i.e., their meaning is specific and perhaps private to that 818 document). 820 Finally, the HTML specification gives a special meaning when the 821 "alternate" relation types coincides with other relation types in the 822 same link. Such links ought to be serialised in the Link header 823 field using a single list of relation-types (e.g., rel="alternate 824 stylesheet") to preserve this relationship. 826 A.2. Link Serialisation in Atom 828 Atom [RFC4287] is a link serialisation that conveys links in the 829 atom:link element, with the "href" attribute indicating the link 830 target and the "rel" attribute containing the relation type. The 831 context of the link is either a feed locator or an entry ID, 832 depending on where it appears; generally, feed-level links are 833 obvious candidates for transmission as a Link header field. 835 When serialising an atom:link into a Link header field, it is 836 necessary to convert link targets (if used) to URIs. 838 Atom defines extension relation types in terms of IRIs. This 839 specification re-defines them as URIs, to simplify and reduce errors 840 in their comparison. 842 Atom allows registered link relation types to be serialised as 843 absolute URIs using a prefix, "http://www.iana.org/assignments/ 844 relation/". This prefix is specific to the Atom serialisation. 846 Furthermore, link relation types are always compared in a case- 847 sensitive fashion; therefore, registered link relation types SHOULD 848 be converted to their registered form (usually, lowercase) when 849 serialised in an Atom document. 851 Note also that while the Link header field allows multiple relations 852 to be serialised in a single link, atom:link does not. In this case, 853 a single link-value may map to several atom:link elements. 855 As with HTML, atom:link defines some attributes that are not 856 explicitly mirrored in the Link header field syntax, but they can 857 also be used as link-extensions to maintain fidelity. 859 Appendix B. Algorithms for Parsing Link Header Fields 861 This appendix outlines a set of non-normative algorithms: for parsing 862 the Link header(s) out of a header set, parsing a link header field 863 value, and algorithms for parsing generic parts of the field value. 865 These algorithms are more permissive than the ABNF defining the 866 syntax might suggest; the error handling embodied in them is a 867 reasonable approach, but not one that is required. As such they are 868 advisory only, and in cases where there is disagreement, the correct 869 behaviour is defined by the body of this specification. 871 B.1. Parsing a Header Set for Links 873 This algorithm can be used to parse the Link header fields that a 874 HTTP header set contains. Given a "header_set" of (string 875 "field_name", string "field_value") pairs, assuming ASCII encoding, 876 it returns a list of link objects. 878 1. Let "field_values" be a list containing the members of 879 "header_set" whose "field_name" is a case-insensitive match for 880 "link". 882 2. Let "links" be an empty list. 884 3. For each "field_value" in "field_values": 886 1. Let "value_links" be the result of _Parsing A Link Field 887 Value_ (Appendix B.2) from "field_value". 889 2. Append each member of "value_links" to "links". 891 4. Return "links". 893 B.2. Parsing a Link Field Value 895 This algorithm parses zero or more comma-separated link-values from a 896 Link header field. Given a string "field_value", assuming ASCII 897 encoding, it returns a list of link objects. 899 1. Let "links" be an empty list. 901 2. While "field_value" has content: 903 1. Consume any leading OWS. 905 2. If the first character is not "<", return "links". 907 3. Discard the first character ("<"). 909 4. Consume up to but not including the first ">" character or 910 end of "field_value" and let the result be "target_string". 912 5. If the next character is not ">", return "links". 914 6. Discard the leading ">" character. 916 7. Let "link_parameters", be the result of _Parsing Parameters_ 917 (Appendix B.3) from "field_value" (consuming zero or more 918 characters of it). 920 8. Let "target" be the result of relatively resolving (as per 921 [RFC3986], Section 5.2) "target_string". Note that any base 922 URI carried in the payload body is NOT used. 924 9. Let "relations_string" be the second item of the first tuple 925 of "link_parameters" whose first item matches the string 926 "rel", or the empty string ("") if it is not present. 928 10. Split "relations_string" on RWS (removing it in the process) 929 into a list of strings "relation_types". 931 11. Let "context_string" be the second item of the first tuple 932 of "link_parameters" whose first item matches the string 933 "anchor". If it is not present, "context_string" is the URL 934 of the representation carrying the Link header [RFC7231], 935 Section 3.1.4.1, serialised as a URI. Where the URL is 936 anonymous, "context_string" is null. 938 12. Let "context" be the result of relatively resolving (as per 939 [RFC3986], Section 5.2) "context_string", unless 940 "context_string" is null in which case "context" is null. 941 Note that any base URI carried in the payload body is NOT 942 used. 944 13. Let "target_attributes" be an empty list. 946 14. For each tuple ("param_name", "param_value") of 947 "link_parameters": 949 1. If "param_name" matches "rel" or "anchor", skip this 950 tuple. 952 2. If "param_name" matches "media", "title", "title*" or 953 "type" and "target_attributes" already contains a tuple 954 whose first element matches the value of "param_name", 955 skip this tuple. 957 3. Append ("param_name", "param_value") to 958 "target_attributes". 960 15. Let "star_param_names" be the set of "param_name"s in the 961 ("param_name", "param_value") tuples of "link_parameters" 962 where the last character of "param_name" is an asterisk 963 ("*"). 965 16. For each "star_param_name" in "star_param_names": 967 1. Let "base_param_name" be "star_param_name" with the last 968 character removed. 970 2. If the implementation does not choose to support an 971 internationalised form of a parameter named 972 "base_param_name" for any reason (including, but not 973 limited to, it being prohibited by the parameter's 974 specification), remove all tuples from "link_parameters" 975 whose first member is "star_param_name" and skip to the 976 next "star_param_name". 978 3. Remove all tuples from "link_parameters" whose first 979 member is "base_param_name". 981 4. Change the first member of all tuples in 982 "link_parameters" whose first member is 983 "star_param_name" to "base_param_name". 985 17. For each "relation_type" in "relation_types": 987 1. Case-normalise "relation_type" to lowercase. 989 2. Append a link object to "links" with the target 990 "target", relation type of "relation_type", context of 991 "context", and target attributes "target_attributes". 993 3. Return "links". 995 B.3. Parsing Parameters 997 This algorithm parses the parameters from a header field value. 998 Given an ASCII string "input", it returns a list of (string 999 "parameter_name", string "parameter_value") tuples that it contains. 1000 "input" is modified to remove the parsed parameters. 1002 1. Let "parameters" be an empty list. 1004 2. While "input" has content: 1006 1. Consume any leading OWS. 1008 2. If the first character is not ";", return "parameters". 1010 3. Discard the leading ";" character. 1012 4. Consume any leading OWS. 1014 5. Consume up to but not including the first BWS, "=", ";", "," 1015 character or end of "input" and let the result be 1016 "parameter_name". 1018 6. Consume any leading BWS. 1020 7. If the next character is "=": 1022 1. Discard the leading "=" character. 1024 2. Consume any leading BWS. 1026 3. If the next character is DQUOTE, let "parameter_value" 1027 be the result of _Parsing a Quoted String_ 1028 (Appendix B.4) from "input" (consuming zero or more 1029 characters of it). 1031 4. Else, consume the contents up to but not including the 1032 first ";", "," character or end of "input" and let the 1033 results be "parameter_value". 1035 5. If the last character of "parameter_name" is an asterisk 1036 ("*"), decode "parameter_value" according to 1037 [I-D.ietf-httpbis-rfc5987bis]. Continue processing 1038 "input" if an unrecoverable error is encountered. 1040 8. Else: 1042 1. Let "parameter_value" be an empty string. 1044 9. Case-normalise "parameter_name" to lowercase. 1046 10. Append ("parameter_name", "parameter_value") to 1047 "parameters". 1049 11. Consume any leading OWS. 1051 12. If the next character is "," or the end of "input", stop 1052 processing "input" and return "parameters". 1054 B.4. Parsing a Quoted String 1056 This algorithm parses a quoted string, as per [RFC7230], 1057 Section 3.2.6. Given an ASCII string "input", it returns an unquoted 1058 string. "input" is modified to remove the parsed string. 1060 1. Let "output" be an empty string. 1062 2. If the first character of "input" is not DQUOTE, return "output". 1064 3. Discard the first character. 1066 4. While "input" has content: 1068 1. If the first character is a backslash ("\"): 1070 1. Discard the first character. 1072 2. If there is no more "input", return "output". 1074 3. Else, consume the first character and append it to 1075 "output". 1077 2. Else, if the first character is DQUOTE, discard it and return 1078 "output". 1080 3. Else, consume the first character and append it to "output". 1082 5. Return "output". 1084 Appendix C. Changes from RFC5988 1086 This specification has the following differences from its 1087 predecessor, RFC5988: 1089 o The initial relation type registrations were removed, since 1090 they've already been registered by 5988. 1092 o The introduction has been shortened. 1094 o The Link Relation Application Data Registry has been removed. 1096 o Incorporated errata. 1098 o Updated references. 1100 o Link cardinality was clarified. 1102 o Terminology was changed from "target IRI" and "context IRI" to 1103 "link target" and "link context" respectively. 1105 o Made assigning a URI to registered relation types serialisation- 1106 specific. 1108 o Removed misleading statement that the link header field is 1109 semantically equivalent to HTML and Atom links. 1111 o More carefully defined and used "link serialisations" and "link 1112 applications." 1114 o Clarified the cardinality of target attributes (generically and 1115 for "type"). 1117 o Corrected the default link context for the Link header field, to 1118 be dependent upon the identity of the representation (as per 1119 RFC7231). 1121 o Defined a suggested parsing algorithm for the Link header. 1123 o The value space of target attributes and their definition has been 1124 specified. 1126 o The ABNF has been updated to be compatible with [RFC7230]. In 1127 particular, whitespace is now explicit. 1129 o Some parameters on the HTTP header field can now appear as a 1130 token. 1132 o Parameters on the HTTP header can now be value-less. 1134 o Handling of quoted strings is now defined by [RFC7230]. 1136 o The "type" header field parameter now needs to be quoted (as 1137 "token" does not allow "/"). 1139 Author's Address 1141 Mark Nottingham 1143 EMail: mnot@mnot.net 1144 URI: https://www.mnot.net/