idnits 2.17.1 draft-nottingham-link-template-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (1 September 2021) is 962 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 (-19) exists of draft-ietf-httpbis-semantics-18 -- Possible downref: Normative reference to a draft: ref. 'HTTP' ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) Summary: 1 error (**), 0 flaws (~~), 2 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 1 September 2021 4 Intended status: Standards Track 5 Expires: 5 March 2022 7 The Link-Template HTTP Header Field 8 draft-nottingham-link-template-03 10 Abstract 12 This specification defines the Link-Template HTTP header field, 13 providing a means for describing the structure of a link between two 14 resources, so that new links can be generated. 16 Note to Readers 18 The issues list can be found at https://github.com/mnot/I-D/labels/ 19 link-template (https://github.com/mnot/I-D/labels/link-template). 21 The most recent (often, unpublished) draft is at 22 https://mnot.github.io/I-D/link-template/ (https://mnot.github.io/I- 23 D/link-template/). 25 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 26 pages/link-template (https://github.com/mnot/I-D/commits/gh-pages/ 27 link-template). 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 5 March 2022. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 64 2. The Link-Template Header Field . . . . . . . . . . . . . . . 3 65 2.1. The 'var-base' parameter . . . . . . . . . . . . . . . . 3 66 3. Security Considerations . . . . . . . . . . . . . . . . . . . 4 67 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 68 5. Normative References . . . . . . . . . . . . . . . . . . . . 4 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5 71 1. Introduction 73 [URI-TEMPLATE] defines a syntax for templates that, when expanded 74 using a set of variables, results in a URI [URI]. 76 This specification defines a HTTP header field [HTTP] for conveying 77 templates for links in the headers of a HTTP message. It is 78 complimentary to the Link header field defined in Section 3 of 79 [WEB-LINKING], which carries links directly. 81 1.1. Notational Conventions 83 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 84 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 85 "OPTIONAL" in this document are to be interpreted as described in BCP 86 14 [RFC2119] [RFC8174] when, and only when, they appear in all 87 capitals, as shown here. 89 This document uses the Augmented BNF defined in [HTTP] to specify 90 valid protocol elements. Additionally, it uses the modified 91 "parameter" rule from [RFC5987] and the "URI-Template" rule from 92 [URI-TEMPLATE]. 94 2. The Link-Template Header Field 96 The Link-Template header field provides a means for serialising one 97 or more links into HTTP message metadata. It is semantically 98 equivalent to the Link header field defined in Section 3 of 99 [WEB-LINKING], except that it uses URI Templates [URI-TEMPLATE] to 100 convey the structure of links. 102 Link-Template = "Link-Template" ":" #templated-link 103 templated-link = "<" URI-Template ">" *( ";" parameter ) 105 For example: 107 Link-Template: ; rel="https://example.org/rel/user" 109 indicates that a resource with the relation type 110 "https://example.org/rel/user" can be found by interpolating the 111 "username" variable into the template given. 113 The target for the link (as defined in Section 2 of [WEB-LINKING]) is 114 the result of expanding the URI Template [URI-TEMPLATE] (being 115 converted to an absolute URI after expansion, if necessary). 117 The context, relation type and target attributes for the link are 118 determined as defined for the Link header field in Section 3 of 119 [WEB-LINKING]. 121 Parameters on a templated-link have identical semantics to those of a 122 Link header field. This includes (but is not limited to) the use of 123 the "rel" parameter to convey the relation type, the "anchor" 124 parameter to modify the context IRI, and so on. 126 Likewise, the requirements for parameters on templated-links are the 127 same as those for a Link header field; in particular, the "rel" 128 parameter MUST NOT appear more than once, and if it does, the 129 templated-link MUST be ignored by parsers. 131 This specification defines additional semantics for the "var-base" 132 parameter on templated-links; see below. 134 2.1. The 'var-base' parameter 136 When a templated-link has a 'var-base' parameter, its value conveys a 137 URI-reference that is used as a base URI for the variable names in 138 the URI template. This allows template variables to be globally 139 identified, rather than specific to the context of use. 141 Dereferencing the URI for a particular variable might lead to more 142 information about the syntax or semantics of that variable; 143 specification of particular formats for this information is out of 144 scope for this document. 146 To determine the URI for a given variable, the value given is used as 147 a base URI in reference resolution (as specified in [URI]). If the 148 resulting URI is still relative, the context of the link is used as 149 the base URI in a further resolution; see [WEB-LINKING]. 151 For example: 153 Link-Template: ; 154 rel="https://example.org/rel/widget"; 155 var-base="https://example.org/vars/" 157 indicates that a resource with the relation type 158 "https://example.org/rel/widget" can be found by interpolating the 159 "https://example.org/vars/widget_id" variable into the template 160 given. 162 If the current context of the message that the header appears within 163 is "https://example.org/", the same information could be conveyed by 164 this header field: 166 Link-Template: ; 167 rel="https://example.org/rel/widget"; 168 var-base="/vars/" 170 3. Security Considerations 172 The security consideration for the Link header field in [WEB-LINKING] 173 and those for URI Templates [URI-TEMPLATE] both apply. 175 4. IANA Considerations 177 This specification enters the "Link-Template" into the Hypertext 178 Transfer Protocol (HTTP) Field Name Registry. 180 Field Name: Link-Template 181 Status: permanent 182 Specification document: [this document] 184 5. Normative References 186 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 187 Semantics", Work in Progress, Internet-Draft, draft-ietf- 188 httpbis-semantics-18, 18 August 2021, 189 . 192 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 193 Requirement Levels", BCP 14, RFC 2119, 194 DOI 10.17487/RFC2119, March 1997, 195 . 197 [RFC5987] Reschke, J., "Character Set and Language Encoding for 198 Hypertext Transfer Protocol (HTTP) Header Field 199 Parameters", RFC 5987, DOI 10.17487/RFC5987, August 2010, 200 . 202 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 203 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 204 May 2017, . 206 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 207 Resource Identifier (URI): Generic Syntax", STD 66, 208 RFC 3986, DOI 10.17487/RFC3986, January 2005, 209 . 211 [URI-TEMPLATE] 212 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 213 and D. Orchard, "URI Template", RFC 6570, 214 DOI 10.17487/RFC6570, March 2012, 215 . 217 [WEB-LINKING] 218 Nottingham, M., "Web Linking", RFC 8288, 219 DOI 10.17487/RFC8288, October 2017, 220 . 222 Author's Address 224 Mark Nottingham 225 Prahran 226 VIC 227 Australia 229 Email: mnot@mnot.net 230 URI: https://www.mnot.net/