idnits 2.17.1 draft-ietf-httpbis-header-structure-10.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 5 characters in excess of 72. ** The abstract seems to contain references ([2], [3], [4], [5], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 17, 2019) is 1835 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 1364 -- Looks like a reference, but probably isn't: '2' on line 1366 -- Looks like a reference, but probably isn't: '3' on line 1368 -- Looks like a reference, but probably isn't: '4' on line 1370 -- Looks like a reference, but probably isn't: '5' on line 1372 == Missing Reference: 'RFCxxxx' is mentioned on line 253, but not defined == Missing Reference: 'RFC3986' is mentioned on line 271, but not defined -- Looks like a reference, but probably isn't: '6' on line 1374 -- Looks like a reference, but probably isn't: '7' on line 1455 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft Fastly 4 Intended status: Standards Track P-H. Kamp 5 Expires: October 19, 2019 The Varnish Cache Project 6 April 17, 2019 8 Structured Headers for HTTP 9 draft-ietf-httpbis-header-structure-10 11 Abstract 13 This document describes a set of data types and algorithms associated 14 with them that are intended to make it easier and safer to define and 15 handle HTTP header fields. It is intended for use by new 16 specifications of HTTP header fields as well as revisions of existing 17 header field specifications when doing so does not cause 18 interoperability issues. 20 Note to Readers 22 _RFC EDITOR: please remove this section before publication_ 24 Discussion of this draft takes place on the HTTP working group 25 mailing list (ietf-http-wg@w3.org), which is archived at 26 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 28 Working Group information can be found at https://httpwg.github.io/ 29 [2]; source code and issues list for this draft can be found at 30 https://github.com/httpwg/http-extensions/labels/header-structure 31 [3]. 33 Tests for implementations are collected at https://github.com/httpwg/ 34 structured-header-tests [4]. 36 Implementations are tracked at https://github.com/httpwg/wiki/wiki/ 37 Structured-Headers [5]. 39 Status of This Memo 41 This Internet-Draft is submitted in full conformance with the 42 provisions of BCP 78 and BCP 79. 44 Internet-Drafts are working documents of the Internet Engineering 45 Task Force (IETF). Note that other groups may also distribute 46 working documents as Internet-Drafts. The list of current Internet- 47 Drafts is at https://datatracker.ietf.org/drafts/current/. 49 Internet-Drafts are draft documents valid for a maximum of six months 50 and may be updated, replaced, or obsoleted by other documents at any 51 time. It is inappropriate to use Internet-Drafts as reference 52 material or to cite them other than as "work in progress." 54 This Internet-Draft will expire on October 19, 2019. 56 Copyright Notice 58 Copyright (c) 2019 IETF Trust and the persons identified as the 59 document authors. All rights reserved. 61 This document is subject to BCP 78 and the IETF Trust's Legal 62 Provisions Relating to IETF Documents 63 (https://trustee.ietf.org/license-info) in effect on the date of 64 publication of this document. Please review these documents 65 carefully, as they describe your rights and restrictions with respect 66 to this document. Code Components extracted from this document must 67 include Simplified BSD License text as described in Section 4.e of 68 the Trust Legal Provisions and are provided without warranty as 69 described in the Simplified BSD License. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 74 1.1. Intentionally Strict Processing . . . . . . . . . . . . . 4 75 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4 76 2. Defining New Structured Headers . . . . . . . . . . . . . . . 5 77 3. Structured Header Data Types . . . . . . . . . . . . . . . . 7 78 3.1. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 7 79 3.2. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 7 80 3.3. Lists of Lists . . . . . . . . . . . . . . . . . . . . . 8 81 3.4. Parameterised Lists . . . . . . . . . . . . . . . . . . . 8 82 3.5. Items . . . . . . . . . . . . . . . . . . . . . . . . . . 9 83 3.6. Integers . . . . . . . . . . . . . . . . . . . . . . . . 9 84 3.7. Floats . . . . . . . . . . . . . . . . . . . . . . . . . 9 85 3.8. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 10 86 3.9. Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 11 87 3.10. Byte Sequences . . . . . . . . . . . . . . . . . . . . . 11 88 3.11. Booleans . . . . . . . . . . . . . . . . . . . . . . . . 11 89 4. Structured Headers in HTTP/1 . . . . . . . . . . . . . . . . 12 90 4.1. Serialising Structured Headers into HTTP/1 . . . . . . . 12 91 4.2. Parsing HTTP/1 Header Fields into Structured Headers . . 18 92 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 93 6. Security Considerations . . . . . . . . . . . . . . . . . . . 28 94 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 95 7.1. Normative References . . . . . . . . . . . . . . . . . . 28 96 7.2. Informative References . . . . . . . . . . . . . . . . . 29 97 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 29 98 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 30 99 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 30 100 B.1. Why not JSON? . . . . . . . . . . . . . . . . . . . . . . 30 101 B.2. Structured Headers don't "fit" my data. . . . . . . . . . 30 102 B.3. What should generic Structured Headers implementations 103 expose? . . . . . . . . . . . . . . . . . . . . . . . . . 31 104 Appendix C. Changes . . . . . . . . . . . . . . . . . . . . . . 31 105 C.1. Since draft-ietf-httpbis-header-structure-09 . . . . . . 31 106 C.2. Since draft-ietf-httpbis-header-structure-08 . . . . . . 32 107 C.3. Since draft-ietf-httpbis-header-structure-07 . . . . . . 32 108 C.4. Since draft-ietf-httpbis-header-structure-06 . . . . . . 33 109 C.5. Since draft-ietf-httpbis-header-structure-05 . . . . . . 33 110 C.6. Since draft-ietf-httpbis-header-structure-04 . . . . . . 33 111 C.7. Since draft-ietf-httpbis-header-structure-03 . . . . . . 33 112 C.8. Since draft-ietf-httpbis-header-structure-02 . . . . . . 33 113 C.9. Since draft-ietf-httpbis-header-structure-01 . . . . . . 34 114 C.10. Since draft-ietf-httpbis-header-structure-00 . . . . . . 34 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 117 1. Introduction 119 Specifying the syntax of new HTTP header fields is an onerous task; 120 even with the guidance in [RFC7231], Section 8.3.1, there are many 121 decisions - and pitfalls - for a prospective HTTP header field 122 author. 124 Once a header field is defined, bespoke parsers and serialisers often 125 need to be written, because each header has slightly different 126 handling of what looks like common syntax. 128 This document introduces a set of common data structures for use in 129 HTTP header field values to address these problems. In particular, 130 it defines a generic, abstract model for header field values, along 131 with a concrete serialisation for expressing that model in HTTP/1 132 [RFC7230] header fields. 134 HTTP headers that are defined as "Structured Headers" use the types 135 defined in this specification to define their syntax and basic 136 handling rules, thereby simplifying both their definition by 137 specification writers and handling by implementations. 139 Additionally, future versions of HTTP can define alternative 140 serialisations of the abstract model of these structures, allowing 141 headers that use it to be transmitted more efficiently without being 142 redefined. 144 Note that it is not a goal of this document to redefine the syntax of 145 existing HTTP headers; the mechanisms described herein are only 146 intended to be used with headers that explicitly opt into them. 148 To specify a header field that is a Structured Header, see Section 2. 150 Section 3 defines a number of abstract data types that can be used in 151 Structured Headers. 153 Those abstract types can be serialised into and parsed from textual 154 headers - such as those used in HTTP/1 - using the algorithms 155 described in Section 4. 157 1.1. Intentionally Strict Processing 159 This specification intentionally defines strict parsing and 160 serialisation behaviours using step-by-step algorithms; the only 161 error handling defined is to fail the operation altogether. 163 This is designed to encourage faithful implementation and therefore 164 good interoperability. Therefore, implementations that try to be 165 "helpful" by being more tolerant of input are doing a disservice to 166 the overall community, since it will encourage other implementations 167 to implement similar (but likely subtly different) workarounds. 169 In other words, strict processing is an intentional feature of this 170 specification; it allows non-conformant input to be discovered and 171 corrected early, and avoids both interoperability and security issues 172 that might otherwise result. 174 Note that as a result of this strictness, if a header field is 175 appended to by multiple parties (e.g., intermediaries, or different 176 components in the sender), it could be that an error in one party's 177 value causes the entire header field to fail parsing. 179 1.2. Notational Conventions 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 183 "OPTIONAL" in this document are to be interpreted as described in BCP 184 14 [RFC2119] [RFC8174] when, and only when, they appear in all 185 capitals, as shown here. 187 This document uses the Augmented Backus-Naur Form (ABNF) notation of 188 [RFC5234], including the VCHAR, SP, DIGIT, ALPHA and DQUOTE rules 189 from that document. It also includes the OWS rule from [RFC7230]. 191 This document uses algorithms to specify parsing and serialisation 192 behaviours, and ABNF to illustrate expected syntax in HTTP/1-style 193 header fields. 195 For parsing from HTTP/1 header fields, implementations MUST follow 196 the algorithms, but MAY vary in implementation so as the behaviours 197 are indistinguishable from specified behaviour. If there is 198 disagreement between the parsing algorithms and ABNF, the specified 199 algorithms take precedence. In some places, the algorithms are 200 "greedy" with whitespace, but this should not affect conformance. 202 For serialisation to HTTP/1 header fields, the ABNF illustrates the 203 range of acceptable wire representations with as much fidelity as 204 possible, and the algorithms define the recommended way to produce 205 them. Implementations MAY vary from the specified behaviour so long 206 as the output still matches the ABNF. 208 2. Defining New Structured Headers 210 To define a HTTP header as a structured header, its specification 211 needs to: 213 o Reference this specification. Recipients and generators of the 214 header need to know that the requirements of this document are in 215 effect. 217 o Specify the header field's allowed syntax for values, in terms of 218 the types described in Section 3, along with their associated 219 semantics. Syntax definitions are encouraged to use the ABNF 220 rules beginning with "sh-" defined in this specification. 222 o Specify any additional constraints upon the syntax of the 223 structured used, as well as the consequences when those 224 constraints are violated. When Structured Headers parsing fails, 225 the header is discarded (see Section 4.2); in most situations, 226 header-specific constraints should do likewise. 228 Note that a header field definition cannot relax the requirements of 229 a structure or its processing because doing so would preclude 230 handling by generic software; they can only add additional 231 constraints. Likewise, header field definitions should use 232 Structured Headers for the entire header field value, not a portion 233 thereof. 235 For example: 237 # Foo-Example Header 239 The Foo-Example HTTP header field conveys information about how 240 much Foo the message has. 242 Foo-Example is a Structured Header [RFCxxxx]. Its value MUST be a 243 dictionary ([RFCxxxx], Section Y.Y). Its ABNF is: 245 Foo-Example = sh-dictionary 247 The dictionary MUST contain: 249 * Exactly one member whose key is "foo", and whose value is an 250 integer ([RFCxxxx], Section Y.Y), indicating the number of foos 251 in the message. 252 * Exactly one member whose key is "barUrls", and whose value is a 253 string ([RFCxxxx], Section Y.Y), conveying the Bar URLs for the 254 message. See below for processing requirements. 256 If the parsed header field does not contain both, it MUST be 257 ignored. 259 "foo" MUST be between 0 and 10, inclusive; other values MUST cause 260 the header to be ignored. 262 "barUrls" contains a space-separated list of URI-references 263 ([RFC3986], Section 4.1): 265 barURLs = URI-reference *( 1*SP URI-reference ) 267 If a member of barURLs is not a valid URI-reference, it MUST cause 268 that value to be ignored. 270 If a member of barURLs is a relative reference ([RFC3986], 271 Section 4.2), it MUST be resolved ([RFC3986], Section 5) before 272 being used. 274 This specification defines minimums for the length or number of 275 various structures supported by Structured Headers implementations. 276 It does not specify maximum sizes in most cases, but header authors 277 should be aware that HTTP implementations do impose various limits on 278 the size of individual header fields, the total number of fields, 279 and/or the size of the entire header block. 281 3. Structured Header Data Types 283 This section defines the abstract value types that can be composed 284 into Structured Headers. The ABNF provided represents the on-wire 285 format in HTTP/1. 287 3.1. Dictionaries 289 Dictionaries are ordered maps of key-value pairs, where the keys are 290 short, textual strings and the values are items (Section 3.5). There 291 can be one or more members, and keys are required to be unique. 293 Implementations MUST provide access to dictionaries both by index and 294 by key. Specifications MAY use either means of accessing the 295 members. 297 The ABNF for dictionaries in HTTP/1 headers is: 299 sh-dictionary = dict-member *( OWS "," OWS dict-member ) 300 dict-member = member-name "=" member-value 301 member-name = key 302 member-value = sh-item 303 key = lcalpha *( lcalpha / DIGIT / "_" / "-" ) 304 lcalpha = %x61-7A ; a-z 306 In HTTP/1, keys and values are separated by "=" (without whitespace), 307 and key/value pairs are separated by a comma with optional 308 whitespace. For example: 310 Example-DictHeader: en="Applepie", da=*w4ZibGV0w6ZydGU=* 312 Typically, a header field specification will define the semantics of 313 individual keys, as well as whether their presence is required or 314 optional. Recipients MUST ignore keys that are undefined or unknown, 315 unless the header field's specification specifically disallows them. 317 Parsers MUST support dictionaries containing at least 1024 key/value 318 pairs, and dictionary keys with at least 64 characters. 320 3.2. Lists 322 Lists are arrays of items (Section 3.5) with one or more members. 324 The ABNF for lists in HTTP/1 headers is: 326 sh-list = list-member *( OWS "," OWS list-member ) 327 list-member = sh-item 328 In HTTP/1, each member is separated by a comma and optional 329 whitespace. For example, a header field whose value is defined as a 330 list of strings could look like: 332 Example-StrListHeader: "foo", "bar", "It was the best of times." 334 Header specifications can constrain the types of individual values if 335 necessary. 337 Parsers MUST support lists containing at least 1024 members. 339 3.3. Lists of Lists 341 Lists of Lists are arrays of arrays containing items (Section 3.5). 343 The ABNF for lists of lists in HTTP/1 headers is: 345 sh-listlist = inner-list *( OWS "," OWS inner-list ) 346 inner-list = list-member *( OWS ";" OWS list-member ) 348 In HTTP/1, each inner-list is separated by a comma and optional 349 whitespace, and members of the inner-list are separated by semicolons 350 and optional whitespace. For example, a header field whose value is 351 defined as a list of lists of strings could look like: 353 Example-StrListListHeader: "foo";"bar", "baz", "bat"; "one" 355 Header specifications can constrain the types of individual inner- 356 list values if necessary. 358 Parsers MUST support lists of lists containing at least 1024 members, 359 and inner-lists containing at least 256 members. 361 3.4. Parameterised Lists 363 Parameterised Lists are arrays of parameterised identifiers, with one 364 or more members. 366 A parameterised identifier is a primary identifier (a Section 3.9}) 367 with associated parameters, an ordered map of key-value pairs where 368 the keys are short, textual strings and the values are items 369 (Section 3.5). There can be zero or more parameters, and keys are 370 required to be unique. 372 The ABNF for parameterised lists in HTTP/1 headers is: 374 sh-param-list = param-item *( OWS "," OWS param-item ) 375 param-item = primary-id *parameter 376 primary-id = sh-token 377 parameter = OWS ";" OWS param-name [ "=" param-value ] 378 param-name = key 379 param-value = sh-item 381 In HTTP/1, each param-id is separated by a comma and optional 382 whitespace (as in Lists), and the parameters are separated by 383 semicolons. For example: 385 Example-ParamListHeader: abc_123;a=1;b=2; cdef_456, ghi;q="9";r="w" 387 Parsers MUST support parameterised lists containing at least 1024 388 members, support members with at least 256 parameters, and support 389 parameter keys with at least 64 characters. 391 3.5. Items 393 An item is can be a integer (Section 3.6), float (Section 3.7), 394 string (Section 3.8), token (Section 3.9), byte sequence 395 (Section 3.10), or Boolean (Section 3.11). 397 The ABNF for items in HTTP/1 headers is: 399 sh-item = sh-integer / sh-float / sh-string / sh-token / sh-binary 400 / sh-boolean 402 3.6. Integers 404 Integers have a range of -999,999,999,999,999 to 999,999,999,999,999 405 inclusive (i.e., up to fifteen digits, signed). 407 The ABNF for integers in HTTP/1 headers is: 409 sh-integer = ["-"] 1*15DIGIT 411 For example: 413 Example-IntegerHeader: 42 415 3.7. Floats 417 Floats are integers with a fractional part, that can be stored as 418 IEEE 754 double precision numbers (binary64) ([IEEE754]). 420 The ABNF for floats in HTTP/1 headers is: 422 sh-float = ["-"] ( 423 DIGIT "." 1*14DIGIT / 424 2DIGIT "." 1*13DIGIT / 425 3DIGIT "." 1*12DIGIT / 426 4DIGIT "." 1*11DIGIT / 427 5DIGIT "." 1*10DIGIT / 428 6DIGIT "." 1*9DIGIT / 429 7DIGIT "." 1*8DIGIT / 430 8DIGIT "." 1*7DIGIT / 431 9DIGIT "." 1*6DIGIT / 432 10DIGIT "." 1*5DIGIT / 433 11DIGIT "." 1*4DIGIT / 434 12DIGIT "." 1*3DIGIT / 435 13DIGIT "." 1*2DIGIT / 436 14DIGIT "." 1DIGIT ) 438 For example, a header whose value is defined as a float could look 439 like: 441 Example-FloatHeader: 4.5 443 3.8. Strings 445 Strings are zero or more printable ASCII [RFC0020] characters (i.e., 446 the range 0x20 to 0x7E). Note that this excludes tabs, newlines, 447 carriage returns, etc. 449 The ABNF for strings in HTTP/1 headers is: 451 sh-string = DQUOTE *(chr) DQUOTE 452 chr = unescaped / escaped 453 unescaped = %x20-21 / %x23-5B / %x5D-7E 454 escaped = "\" ( DQUOTE / "\" ) 456 In HTTP/1 headers, strings are delimited with double quotes, using a 457 backslash ("\") to escape double quotes and backslashes. For 458 example: 460 Example-StringHeader: "hello world" 462 Note that strings only use DQUOTE as a delimiter; single quotes do 463 not delimit strings. Furthermore, only DQUOTE and "\" can be 464 escaped; other sequences MUST cause parsing to fail. 466 Unicode is not directly supported in this document, because it causes 467 a number of interoperability issues, and - with few exceptions - 468 header values do not require it. 470 When it is necessary for a field value to convey non-ASCII string 471 content, a byte sequence (Section 3.10) SHOULD be specified, along 472 with a character encoding (preferably UTF-8). 474 Parsers MUST support strings with at least 1024 characters. 476 3.9. Tokens 478 Tokens are short textual words; their abstract model is identical to 479 their expression in the textual HTTP serialisation. 481 The ABNF for tokens in HTTP/1 headers is: 483 sh-token = ALPHA *( ALPHA / DIGIT / "_" / "-" / "." / ":" / "%" / "*" / "/" ) 485 Parsers MUST support tokens with at least 512 characters. 487 Note that a Structured Header token is not the same as the "token" 488 ABNF rule defined in [RFC7230]. 490 3.10. Byte Sequences 492 Byte sequences can be conveyed in Structured Headers. 494 The ABNF for a byte sequence in HTTP/1 headers is: 496 sh-binary = "*" *(base64) "*" 497 base64 = ALPHA / DIGIT / "+" / "/" / "=" 499 In HTTP/1 headers, a byte sequence is delimited with asterisks and 500 encoded using base64 ([RFC4648], Section 4). For example: 502 Example-BinaryHdr: *cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==* 504 Parsers MUST support byte sequences with at least 16384 octets after 505 decoding. 507 3.11. Booleans 509 Boolean values can be conveyed in Structured Headers. 511 The ABNF for a Boolean in HTTP/1 headers is: 513 sh-boolean = "?" boolean 514 boolean = "0" / "1" 516 In HTTP/1 headers, a boolean is indicated with a leading "?" 517 character. For example: 519 Example-BoolHdr: ?1 521 4. Structured Headers in HTTP/1 523 This section defines how to serialise and parse Structured Headers in 524 HTTP/1 textual header fields, and protocols compatible with them 525 (e.g., in HTTP/2 [RFC7540] before HPACK [RFC7541] is applied). 527 4.1. Serialising Structured Headers into HTTP/1 529 Given a structured defined in this specification: 531 1. If the structure is a dictionary, return the result of 532 Serialising a Dictionary (Section 4.1.1). 534 2. If the structure is a parameterised list, return the result of 535 Serialising a Parameterised List (Section 4.1.4). 537 3. If the structure is a list of lists, return the result of 538 Serialising a List of Lists ({ser-listlist}). 540 4. If the structure is a list, return the result of Serialising a 541 List Section 4.1.2. 543 5. If the structure is an item, return the result of Serialising an 544 Item (Section 4.1.5). 546 6. Otherwise, fail serialisation. 548 4.1.1. Serialising a Dictionary 550 Given a dictionary as input_dictionary: 552 1. Let output be an empty string. 554 2. For each member mem of input_dictionary: 556 1. Let name be the result of applying Serialising an Key 557 (Section 4.1.1.1) to mem's member-name. 559 2. Append name to output. 561 3. Append "=" to output. 563 4. Let value be the result of applying Serialising an Item 564 (Section 4.1.5) to mem's member-value. 566 5. Append value to output. 568 6. If more members remain in input_dictionary: 570 1. Append a COMMA to output. 572 2. Append a single WS to output. 574 3. Return output. 576 4.1.1.1. Serialising a Key 578 Given a key as input_key: 580 1. If input_key is not a sequence of characters, or contains 581 characters not allowed in the ABNF for key, fail serialisation. 583 2. Let output be an empty string. 585 3. Append input_key to output, using ASCII encoding [RFC0020]. 587 4. Return output. 589 4.1.2. Serialising a List 591 Given a list as input_list: 593 1. Let output be an empty string. 595 2. For each member mem of input_list: 597 1. Let value be the result of applying Serialising an Item 598 (Section 4.1.5) to mem. 600 2. Append value to output. 602 3. If more members remain in input_list: 604 1. Append a COMMA to output. 606 2. Append a single WS to output. 608 3. Return output. 610 4.1.3. Serialising a List of Lists 612 Given a list of lists of items as input_list: 614 1. Let output be an empty string. 616 2. For each member inner_list of input_list: 618 1. If inner_list is not a list, fail serialisation. 620 2. If inner_list is empty, fail serialisation. 622 3. For each inner_mem of inner_list: 624 1. Let value be the result of applying Serialising an Item 625 (Section 4.1.5) to inner_mem. 627 2. Append value to output. 629 3. If more members remain in inner_list: 631 1. Append a ";" to output. 633 2. Append a single WS to output. 635 4. If more members remain in input_list: 637 1. Append a COMMA to output. 639 2. Append a single WS to output. 641 3. Return output. 643 4.1.4. Serialising a Parameterised List 645 Given a parameterised list as input_plist: 647 1. Let output be an empty string. 649 2. For each member mem of input_plist: 651 1. Let id be the result of applying Serialising a Token 652 (Section 4.1.9) to mem's token. 654 2. Append id to output. 656 3. For each parameter in mem's parameters: 658 1. Append ";" to output. 660 2. Let name be the result of applying Serialising a Key 661 (Section 4.1.1.1) to parameter's param-name. 663 3. Append name to output. 665 4. If parameter has a param-value: 667 1. Let value be the result of applying Serialising an 668 Item (Section 4.1.5) to parameter's param-value. 670 2. Append "=" to output. 672 3. Append value to output. 674 4. If more members remain in input_plist: 676 1. Append a COMMA to output. 678 2. Append a single WS to output. 680 3. Return output. 682 4.1.5. Serialising an Item 684 Given an item as input_item: 686 1. If input_item is an integer, return the result of applying 687 Serialising an Integer (Section 4.1.6) to input_item. 689 2. If input_item is a float, return the result of applying 690 Serialising a Float (Section 4.1.7) to input_item. 692 3. If input_item is a string, return the result of applying 693 Serialising a String (Section 4.1.8) to input_item. 695 4. If input_item is a token, return the result of Serialising a 696 Token (Section 4.1.9) to input_item. 698 5. If input_item is a Boolean, return the result of applying 699 Serialising a Boolean (Section 4.1.11) to input_item. 701 6. If input_item is a byte sequence, return the result of applying 702 Serialising a Byte Sequence (Section 4.1.10) to input_item. 704 7. Otherwise, fail serialisation. 706 4.1.6. Serialising an Integer 708 Given an integer as input_integer: 710 1. If input_integer is not an integer in the range of 711 -999,999,999,999,999 to 999,999,999,999,999 inclusive, fail 712 serialisation. 714 2. Let output be an empty string. 716 3. If input_integer is less than (but not equal to) 0, append "-" to 717 output. 719 4. Append input_integer's numeric value represented in base 10 using 720 only decimal digits to output. 722 5. Return output. 724 4.1.7. Serialising a Float 726 Given a float as input_float: 728 1. If input_float is not a IEEE 754 double precision number, fail 729 serialisation. 731 2. Let output be an empty string. 733 3. If input_float is less than (but not equal to) 0, append "-" to 734 output. 736 4. Append input_float's integer component represented in base 10 737 using only decimal digits to output; if it is zero, append "0". 739 5. Append "." to output. 741 6. Append input_float's decimal component represented in base 10 742 using only decimal digits to output; if it is zero, append "0". 744 7. Return output. 746 4.1.8. Serialising a String 748 Given a string as input_string: 750 1. If input_string is not a sequence of characters, or contains 751 characters outside the range allowed by VCHAR or SP, fail 752 serialisation. 754 2. Let output be an empty string. 756 3. Append DQUOTE to output. 758 4. For each character char in input_string: 760 1. If char is "\" or DQUOTE: 762 1. Append "\" to output. 764 2. Append char to output, using ASCII encoding [RFC0020]. 766 5. Append DQUOTE to output. 768 6. Return output. 770 4.1.9. Serialising a Token 772 Given a token as input_token: 774 1. If input_token is not a sequence of characters, or contains 775 characters not allowed in Section 3.9}, fail serialisation. 777 2. Let output be an empty string. 779 3. Append input_token to output, using ASCII encoding [RFC0020]. 781 4. Return output. 783 4.1.10. Serialising a Byte Sequence 785 Given a byte sequence as input_bytes: 787 1. If input_bytes is not a sequence of bytes, fail serialisation. 789 2. Let output be an empty string. 791 3. Append "*" to output. 793 4. Append the result of base64-encoding input_bytes as per 794 [RFC4648], Section 4, taking account of the requirements below. 796 5. Append "*" to output. 798 6. Return output. 800 The encoded data is required to be padded with "=", as per [RFC4648], 801 Section 3.2. 803 Likewise, encoded data SHOULD have pad bits set to zero, as per 804 [RFC4648], Section 3.5, unless it is not possible to do so due to 805 implementation constraints. 807 4.1.11. Serialising a Boolean 809 Given a Boolean as input_boolean: 811 1. If input_boolean is not a boolean, fail serialisation. 813 2. Let output be an empty string. 815 3. Append "?" to output. 817 4. If input_boolean is true, append "1" to output. 819 5. If input_boolean is false, append "0" to output. 821 6. Return output. 823 4.2. Parsing HTTP/1 Header Fields into Structured Headers 825 When a receiving implementation parses textual HTTP header fields 826 (e.g., in HTTP/1 or HTTP/2) that are known to be Structured Headers, 827 it is important that care be taken, as there are a number of edge 828 cases that can cause interoperability or even security problems. 829 This section specifies the algorithm for doing so. 831 Given an ASCII string input_string that represents the chosen 832 header's field-value, and header_type, one of "dictionary", "list", 833 "list-list", "param-list", or "item", return the parsed header value. 835 1. Discard any leading OWS from input_string. 837 2. If header_type is "dictionary", let output be the result of 838 Parsing a Dictionary from Text (Section 4.2.1). 840 3. If header_type is "list", let output be the result of Parsing a 841 List from Text (Section 4.2.3). 843 4. If header_type is "list-list", let output be the result of 844 Parsing a List of Lists from Text (Section 4.2.4). 846 5. If header_type is "param-list", let output be the result of 847 Parsing a Parameterised List from Text (Section 4.2.5). 849 6. If header_type is "item", let output be the result of Parsing an 850 Item from Text (Section 4.2.7). 852 7. Discard any leading OWS from input_string. 854 8. If input_string is not empty, fail parsing. 856 9. Otherwise, return output. 858 When generating input_string, parsers MUST combine all instances of 859 the target header field into one comma-separated field-value, as per 860 [RFC7230], Section 3.2.2; this assures that the header is processed 861 correctly. 863 For Lists, Lists of Lists, Parameterised Lists and Dictionaries, this 864 has the effect of correctly concatenating all instances of the header 865 field, as long as individual individual members of the top-level data 866 structure are not split across multiple header instances. 868 Strings split across multiple header instances will have 869 unpredictable results, because comma(s) and whitespace inserted upon 870 combination will become part of the string output by the parser. 871 Since concatenation might be done by an upstream intermediary, the 872 results are not under the control of the serialiser or the parser. 874 Integers, Floats and Byte Sequences cannot be split across multiple 875 headers because the inserted commas will cause parsing to fail. 877 If parsing fails - including when calling another algorithm - the 878 entire header field's value MUST be discarded. This is intentionally 879 strict, to improve interoperability and safety, and specifications 880 referencing this document cannot loosen this requirement. 882 Note that this has the effect of discarding any header field with 883 non-ASCII characters in input_string. 885 4.2.1. Parsing a Dictionary from Text 887 Given an ASCII string input_string, return an ordered map of (key, 888 item). input_string is modified to remove the parsed value. 890 1. Let dictionary be an empty, ordered map. 892 2. While input_string is not empty: 894 1. Let this_key be the result of running Parse a Key from Text 895 (Section 4.2.2) with input_string. 897 2. If dictionary already contains this_key, fail parsing. 899 3. Consume the first character of input_string; if it is not 900 "=", fail parsing. 902 4. Let this_value be the result of running Parse Item from Text 903 (Section 4.2.7) with input_string. 905 5. Add key this_key with value this_value to dictionary. 907 6. Discard any leading OWS from input_string. 909 7. If input_string is empty, return dictionary. 911 8. Consume the first character of input_string; if it is not 912 COMMA, fail parsing. 914 9. Discard any leading OWS from input_string. 916 10. If input_string is empty, fail parsing. 918 3. No structured data has been found; fail parsing. 920 4.2.2. Parsing a Key from Text 922 Given an ASCII string input_string, return a key. input_string is 923 modified to remove the parsed value. 925 1. If the first character of input_string is not lcalpha, fail 926 parsing. 928 2. Let output_string be an empty string. 930 3. While input_string is not empty: 932 1. Let char be the result of removing the first character of 933 input_string. 935 2. If char is not one of lcalpha, DIGIT, "_", or "-": 937 1. Prepend char to input_string. 939 2. Return output_string. 941 3. Append char to output_string. 943 4. Return output_string. 945 4.2.3. Parsing a List from Text 947 Given an ASCII string input_string, return a list of items. 948 input_string is modified to remove the parsed value. 950 1. Let items be an empty array. 952 2. While input_string is not empty: 954 1. Let item be the result of running Parse Item from Text 955 (Section 4.2.7) with input_string. 957 2. Append item to items. 959 3. Discard any leading OWS from input_string. 961 4. If input_string is empty, return items. 963 5. Consume the first character of input_string; if it is not 964 COMMA, fail parsing. 966 6. Discard any leading OWS from input_string. 968 7. If input_string is empty, fail parsing. 970 3. No structured data has been found; fail parsing. 972 4.2.4. Parsing a List of Lists from Text 974 Given an ASCII string input_string, return a list of lists of items. 975 input_string is modified to remove the parsed value. 977 1. let top_list be an empty array. 979 2. Let inner_list be an empty array. 981 3. While input_string is not empty: 983 1. Let item be the result of running Parse Item from Text 984 (Section 4.2.7) with input_string. 986 2. Append item to inner_list. 988 3. Discard any leading OWS from input_string. 990 4. If input_string is empty, append inner_list to top_list and 991 return top_list. 993 5. Let char be the result of consuming the first character of 994 input_string. 996 6. If char is COMMA: 998 1. Append inner_list to top_list. 1000 2. Let inner_list be an empty array. 1002 7. Else if char is not ";", fail parsing. 1004 8. Discard any leading OWS from input_string. 1006 9. If input_string is empty, fail parsing. 1008 4. No structured data has been found; fail parsing. 1010 4.2.5. Parsing a Parameterised List from Text 1012 Given an ASCII string input_string, return a list of parameterised 1013 identifiers. input_string is modified to remove the parsed value. 1015 1. Let items be an empty array. 1017 2. While input_string is not empty: 1019 1. Let item be the result of running Parse Parameterised 1020 Identifier from Text (Section 4.2.6) with input_string. 1022 2. Append item to items. 1024 3. Discard any leading OWS from input_string. 1026 4. If input_string is empty, return items. 1028 5. Consume the first character of input_string; if it is not 1029 COMMA, fail parsing. 1031 6. Discard any leading OWS from input_string. 1033 7. If input_string is empty, fail parsing. 1035 3. No structured data has been found; fail parsing. 1037 4.2.6. Parsing a Parameterised Identifier from Text 1039 Given an ASCII string input_string, return an token with an unordered 1040 map of parameters. input_string is modified to remove the parsed 1041 value. 1043 1. Let primary_identifier be the result of Parsing a Token from Text 1044 (Section 4.2.10) from input_string. 1046 2. Let parameters be an empty, ordered map. 1048 3. In a loop: 1050 1. Discard any leading OWS from input_string. 1052 2. If the first character of input_string is not ";", exit the 1053 loop. 1055 3. Consume a ";" character from the beginning of input_string. 1057 4. Discard any leading OWS from input_string. 1059 5. let param_name be the result of Parsing a key from Text 1060 (Section 4.2.2) from input_string. 1062 6. If param_name is already present in parameters, fail parsing. 1064 7. Let param_value be a null value. 1066 8. If the first character of input_string is "=": 1068 1. Consume the "=" character at the beginning of 1069 input_string. 1071 2. Let param_value be the result of Parsing an Item from 1072 Text (Section 4.2.7) from input_string. 1074 9. Add key param_name with value param_value to parameters. 1076 4. Return the tuple (primary_identifier, parameters). 1078 4.2.7. Parsing an Item from Text 1080 Given an ASCII string input_string, return an item. input_string is 1081 modified to remove the parsed value. 1083 1. If the first character of input_string is a "-" or a DIGIT, 1084 process input_string as a number (Section 4.2.8) and return the 1085 result. 1087 2. If the first character of input_string is a DQUOTE, process 1088 input_string as a string (Section 4.2.9) and return the result. 1090 3. If the first character of input_string is "*", process 1091 input_string as a byte sequence (Section 4.2.11) and return the 1092 result. 1094 4. If the first character of input_string is "?", process 1095 input_string as a Boolean (Section 4.2.12) and return the result. 1097 5. If the first character of input_string is an ALPHA, process 1098 input_string as a token (Section 4.2.10) and return the result. 1100 6. Otherwise, fail parsing. 1102 4.2.8. Parsing a Number from Text 1104 Given an ASCII string input_string, return a number. input_string is 1105 modified to remove the parsed value. 1107 NOTE: This algorithm parses both Integers Section 3.6 and Floats 1108 Section 3.7, and returns the corresponding structure. 1110 1. Let type be "integer". 1112 2. Let sign be 1. 1114 3. Let input_number be an empty string. 1116 4. If the first character of input_string is "-", remove it from 1117 input_string and set sign to -1. 1119 5. If input_string is empty, fail parsing. 1121 6. If the first character of input_string is not a DIGIT, fail 1122 parsing. 1124 7. While input_string is not empty: 1126 1. Let char be the result of removing the first character of 1127 input_string. 1129 2. If char is a DIGIT, append it to input_number. 1131 3. Else, if type is "integer" and char is ".", append char to 1132 input_number and set type to "float". 1134 4. Otherwise, prepend char to input_string, and exit the loop. 1136 5. If type is "integer" and input_number contains more than 15 1137 characters, fail parsing. 1139 6. If type is "float" and input_number contains more than 16 1140 characters, fail parsing. 1142 8. If type is "integer": 1144 1. Parse input_number as an integer and let output_number be 1145 the product of the result and sign. 1147 2. If output_number is outside the range defined in 1148 Section 3.6, fail parsing. 1150 9. Otherwise: 1152 1. If the final character of input_number is ".", fail parsing. 1154 2. Parse input_number as a float and let output_number be the 1155 product of the result and sign. 1157 10. Return output_number. 1159 4.2.9. Parsing a String from Text 1161 Given an ASCII string input_string, return an unquoted string. 1162 input_string is modified to remove the parsed value. 1164 1. Let output_string be an empty string. 1166 2. If the first character of input_string is not DQUOTE, fail 1167 parsing. 1169 3. Discard the first character of input_string. 1171 4. While input_string is not empty: 1173 1. Let char be the result of removing the first character of 1174 input_string. 1176 2. If char is a backslash ("\"): 1178 1. If input_string is now empty, fail parsing. 1180 2. Else: 1182 1. Let next_char be the result of removing the first 1183 character of input_string. 1185 2. If next_char is not DQUOTE or "\", fail parsing. 1187 3. Append next_char to output_string. 1189 3. Else, if char is DQUOTE, return output_string. 1191 4. Else, if char is in the range %x00-1f or %x7f (i.e., is not 1192 in VCHAR or SP), fail parsing. 1194 5. Else, append char to output_string. 1196 5. Reached the end of input_string without finding a closing DQUOTE; 1197 fail parsing. 1199 4.2.10. Parsing a Token from Text 1201 Given an ASCII string input_string, return a token. input_string is 1202 modified to remove the parsed value. 1204 1. If the first character of input_string is not ALPHA, fail 1205 parsing. 1207 2. Let output_string be an empty string. 1209 3. While input_string is not empty: 1211 1. Let char be the result of removing the first character of 1212 input_string. 1214 2. If char is not one of ALPHA, DIGIT, "_", "-", ".", ":", "%", 1215 "*" or "/": 1217 1. Prepend char to input_string. 1219 2. Return output_string. 1221 3. Append char to output_string. 1223 4. Return output_string. 1225 4.2.11. Parsing a Byte Sequence from Text 1227 Given an ASCII string input_string, return a byte sequence. 1228 input_string is modified to remove the parsed value. 1230 1. If the first character of input_string is not "*", fail parsing. 1232 2. Discard the first character of input_string. 1234 3. If there is not a "*" character before the end of input_string, 1235 fail parsing. 1237 4. Let b64_content be the result of removing content of input_string 1238 up to but not including the first instance of the character "*". 1240 5. Consume the "*" character at the beginning of input_string. 1242 6. If b64_content contains a character not included in ALPHA, DIGIT, 1243 "+", "/" and "=", fail parsing. 1245 7. Let binary_content be the result of Base 64 Decoding [RFC4648] 1246 b64_content, synthesising padding if necessary (note the 1247 requirements about recipient behaviour below). 1249 8. Return binary_content. 1251 Because some implementations of base64 do not allow reject of encoded 1252 data that is not properly "=" padded (see [RFC4648], Section 3.2), 1253 parsers SHOULD NOT fail when it is not present, unless they cannot be 1254 configured to do so. 1256 Because some implementations of base64 do not allow rejection of 1257 encoded data that has non-zero pad bits (see [RFC4648], Section 3.5), 1258 parsers SHOULD NOT fail when it is present, unless they cannot be 1259 configured to do so. 1261 This specification does not relax the requirements in [RFC4648], 1262 Section 3.1 and 3.3; therefore, parsers MUST fail on characters 1263 outside the base64 alphabet, and on line feeds in encoded data. 1265 4.2.12. Parsing a Boolean from Text 1267 Given an ASCII string input_string, return a Boolean. input_string is 1268 modified to remove the parsed value. 1270 1. If the first character of input_string is not "?", fail parsing. 1272 2. Discard the first character of input_string. 1274 3. If the first character of input_string matches "1", discard the 1275 first character, and return true. 1277 4. If the first character of input_string matches "0", discard the 1278 first character, and return false. 1280 5. No value has matched; fail parsing. 1282 5. IANA Considerations 1284 This draft has no actions for IANA. 1286 6. Security Considerations 1288 The size of most types defined by Structured Headers is not limited; 1289 as a result, extremely large header fields could be an attack vector 1290 (e.g., for resource consumption). Most HTTP implementations limit 1291 the sizes of size of individual header fields as well as the overall 1292 header block size to mitigate such attacks. 1294 It is possible for parties with the ability to inject new HTTP header 1295 fields to change the meaning of a Structured Header. In some 1296 circumstances, this will cause parsing to fail, but it is not 1297 possible to reliably fail in all such circumstances. 1299 7. References 1301 7.1. Normative References 1303 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 1304 RFC 20, DOI 10.17487/RFC0020, October 1969, 1305 . 1307 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1308 Requirement Levels", BCP 14, RFC 2119, 1309 DOI 10.17487/RFC2119, March 1997, 1310 . 1312 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1313 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1314 . 1316 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1317 Specifications: ABNF", STD 68, RFC 5234, 1318 DOI 10.17487/RFC5234, January 2008, 1319 . 1321 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1322 Protocol (HTTP/1.1): Message Syntax and Routing", 1323 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1324 . 1326 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1327 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1328 May 2017, . 1330 7.2. Informative References 1332 [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", 1333 IEEE 754-2008, DOI 10.1109/IEEESTD.2008.4610935, 1334 ISBN 978-0-7381-5752-8, August 2008, 1335 . 1337 See also http://grouper.ieee.org/groups/754/ [6]. 1339 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1340 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1341 DOI 10.17487/RFC7231, June 2014, 1342 . 1344 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 1345 DOI 10.17487/RFC7493, March 2015, 1346 . 1348 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1349 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1350 DOI 10.17487/RFC7540, May 2015, 1351 . 1353 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1354 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1355 . 1357 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1358 Interchange Format", STD 90, RFC 8259, 1359 DOI 10.17487/RFC8259, December 2017, 1360 . 1362 7.3. URIs 1364 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 1366 [2] https://httpwg.github.io/ 1368 [3] https://github.com/httpwg/http-extensions/labels/header-structure 1370 [4] https://github.com/httpwg/structured-header-tests 1372 [5] https://github.com/httpwg/wiki/wiki/Structured-Headers 1374 [6] https://github.com/httpwg/structured-header-tests 1376 Appendix A. Acknowledgements 1378 Many thanks to Matthew Kerwin for his detailed feedback and careful 1379 consideration during the development of this specification. 1381 Appendix B. Frequently Asked Questions 1383 B.1. Why not JSON? 1385 Earlier proposals for structured headers were based upon JSON 1386 [RFC8259]. However, constraining its use to make it suitable for 1387 HTTP header fields required senders and recipients to implement 1388 specific additional handling. 1390 For example, JSON has specification issues around large numbers and 1391 objects with duplicate members. Although advice for avoiding these 1392 issues is available (e.g., [RFC7493]), it cannot be relied upon. 1394 Likewise, JSON strings are by default Unicode strings, which have a 1395 number of potential interoperability issues (e.g., in comparison). 1396 Although implementers can be advised to avoid non-ASCII content where 1397 unnecessary, this is difficult to enforce. 1399 Another example is JSON's ability to nest content to arbitrary 1400 depths. Since the resulting memory commitment might be unsuitable 1401 (e.g., in embedded and other limited server deployments), it's 1402 necessary to limit it in some fashion; however, existing JSON 1403 implementations have no such limits, and even if a limit is 1404 specified, it's likely that some header field definition will find a 1405 need to violate it. 1407 Because of JSON's broad adoption and implementation, it is difficult 1408 to impose such additional constraints across all implementations; 1409 some deployments would fail to enforce them, thereby harming 1410 interoperability. 1412 Since a major goal for Structured Headers is to improve 1413 interoperability and simplify implementation, these concerns led to a 1414 format that requires a dedicated parser and serialiser. 1416 Additionally, there were widely shared feelings that JSON doesn't 1417 "look right" in HTTP headers. 1419 B.2. Structured Headers don't "fit" my data. 1421 Structured headers intentionally limits the complexity of data 1422 structures, to assure that it can be processed in a performant manner 1423 with little overhead. This means that work is necessary to fit some 1424 data types into them. 1426 Sometimes, this can be achieved by creating limited substructures in 1427 values, and/or using more than one header. For example, consider: 1429 Example-Thing: name="Widget", cost=89.2, descriptions="foo bar" 1430 Example-Description: foo; url="https://example.net"; context=123, 1431 bar; url="https://example.org"; context=456 1433 Since the description contains a list of key/value pairs, we use a 1434 Parameterised List to represent them, with the token for each item in 1435 the list used to identify it in the "descriptions" member of the 1436 Example-Thing header. 1438 When specifying more than one header, it's important to remember to 1439 describe what a processor's behaviour should be when one of the 1440 headers is missing. 1442 If you need to fit arbitrarily complex data into a header, Structured 1443 Headers is probably a poor fit for your use case. 1445 B.3. What should generic Structured Headers implementations expose? 1447 A generic implementation should expose the top-level parse 1448 (Section 4.2) and serialise (Section 4.1) functions. They need not 1449 be functions; for example, it could be implemented as an object, with 1450 methods for each of the different top-level types. 1452 For interoperability, it's important that generic implementations be 1453 complete and follow the algorithms closely; see Section 1.1. To aid 1454 this, a common test suite is being maintained by the community; see 1455 https://github.com/httpwg/structured-header-tests [7]. 1457 Implementers should note that dictionaries and parameters are order- 1458 preserving maps. Some headers may not convey meaning in the ordering 1459 of these data types, but it should still be exposed so that 1460 applications which need to use it will have it available. 1462 Appendix C. Changes 1464 _RFC Editor: Please remove this section before publication._ 1466 C.1. Since draft-ietf-httpbis-header-structure-09 1468 o Changed Boolean from T/F to 1/0 (#784). 1470 o Parameters are now ordered maps (#765). 1472 o Clamp integers to 15 digits (#737). 1474 C.2. Since draft-ietf-httpbis-header-structure-08 1476 o Disallow whitespace before items properly (#703). 1478 o Created "key" for use in dictionaries and parameters, rather than 1479 relying on identifier (#702). Identifiers have a separate minimum 1480 supported size. 1482 o Expanded the range of special characters allowed in identifier to 1483 include all of ALPHA, ".", ":", and "%" (#702). 1485 o Use "?" instead of "!" to indicate a Boolean (#719). 1487 o Added "Intentionally Strict Processing" (#684). 1489 o Gave better names for referring specs to use in Parameterised 1490 Lists (#720). 1492 o Added Lists of Lists (#721). 1494 o Rename Identifier to Token (#725). 1496 o Add implementation guidance (#727). 1498 C.3. Since draft-ietf-httpbis-header-structure-07 1500 o Make Dictionaries ordered mappings (#659). 1502 o Changed "binary content" to "byte sequence" to align with Infra 1503 specification (#671). 1505 o Changed "mapping" to "map" for #671. 1507 o Don't fail if byte sequences aren't "=" padded (#658). 1509 o Add Booleans (#683). 1511 o Allow identifiers in items again (#629). 1513 o Disallowed whitespace before items (#703). 1515 o Explain the consequences of splitting a string across multiple 1516 headers (#686). 1518 C.4. Since draft-ietf-httpbis-header-structure-06 1520 o Add a FAQ. 1522 o Allow non-zero pad bits. 1524 o Explicitly check for integers that violate constraints. 1526 C.5. Since draft-ietf-httpbis-header-structure-05 1528 o Reorganise specification to separate parsing out. 1530 o Allow referencing specs to use ABNF. 1532 o Define serialisation algorithms. 1534 o Refine relationship between ABNF, parsing and serialisation 1535 algorithms. 1537 C.6. Since draft-ietf-httpbis-header-structure-04 1539 o Remove identifiers from item. 1541 o Remove most limits on sizes. 1543 o Refine number parsing. 1545 C.7. Since draft-ietf-httpbis-header-structure-03 1547 o Strengthen language around failure handling. 1549 C.8. Since draft-ietf-httpbis-header-structure-02 1551 o Split Numbers into Integers and Floats. 1553 o Define number parsing. 1555 o Tighten up binary parsing and give it an explicit end delimiter. 1557 o Clarify that mappings are unordered. 1559 o Allow zero-length strings. 1561 o Improve string parsing algorithm. 1563 o Improve limits in algorithms. 1565 o Require parsers to combine header fields before processing. 1567 o Throw an error on trailing garbage. 1569 C.9. Since draft-ietf-httpbis-header-structure-01 1571 o Replaced with draft-nottingham-structured-headers. 1573 C.10. Since draft-ietf-httpbis-header-structure-00 1575 o Added signed 64bit integer type. 1577 o Drop UTF8, and settle on BCP137 ::EmbeddedUnicodeChar for h1- 1578 unicode-string. 1580 o Change h1_blob delimiter to ":" since "'" is valid t_char 1582 Authors' Addresses 1584 Mark Nottingham 1585 Fastly 1587 Email: mnot@mnot.net 1588 URI: https://www.mnot.net/ 1590 Poul-Henning Kamp 1591 The Varnish Cache Project 1593 Email: phk@varnish-cache.org