draft-ietf-httpbis-header-structure-06.txt   draft-ietf-httpbis-header-structure-07.txt 
HTTP M. Nottingham HTTP M. Nottingham
Internet-Draft Fastly Internet-Draft Fastly
Intended status: Standards Track P-H. Kamp Intended status: Standards Track P-H. Kamp
Expires: December 7, 2018 The Varnish Cache Project Expires: January 3, 2019 The Varnish Cache Project
June 5, 2018 July 2, 2018
Structured Headers for HTTP Structured Headers for HTTP
draft-ietf-httpbis-header-structure-06 draft-ietf-httpbis-header-structure-07
Abstract Abstract
This document describes a set of data types and algorithms associated This document describes a set of data types and algorithms associated
with them that are intended to make it easier and safer to define and with them that are intended to make it easier and safer to define and
handle HTTP header fields. It is intended for use by new handle HTTP header fields. It is intended for use by new
specifications of HTTP header fields as well as revisions of existing specifications of HTTP header fields as well as revisions of existing
header field specifications when doing so does not cause header field specifications when doing so does not cause
interoperability issues. interoperability issues.
skipping to change at page 2, line 10 skipping to change at page 2, line 10
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 7, 2018. This Internet-Draft will expire on January 3, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 37 skipping to change at page 2, line 37
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
2. Defining New Structured Headers . . . . . . . . . . . . . . . 4 2. Defining New Structured Headers . . . . . . . . . . . . . . . 4
3. Structured Header Data Types . . . . . . . . . . . . . . . . 6 3. Structured Header Data Types . . . . . . . . . . . . . . . . 6
3.1. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.3. Parameterised Lists . . . . . . . . . . . . . . . . . . . 7 3.3. Parameterised Lists . . . . . . . . . . . . . . . . . . . 7
3.4. Items . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.4. Items . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.5. Integers . . . . . . . . . . . . . . . . . . . . . . . . 7 3.5. Integers . . . . . . . . . . . . . . . . . . . . . . . . 8
3.6. Floats . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.6. Floats . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.7. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.7. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.8. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 9 3.8. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 9
3.9. Binary Content . . . . . . . . . . . . . . . . . . . . . 9 3.9. Binary Content . . . . . . . . . . . . . . . . . . . . . 9
4. Structured Headers in HTTP/1 . . . . . . . . . . . . . . . . 10 4. Structured Headers in HTTP/1 . . . . . . . . . . . . . . . . 10
4.1. Serialising Structured Headers into HTTP/1 . . . . . . . 10 4.1. Serialising Structured Headers into HTTP/1 . . . . . . . 10
4.2. Parsing HTTP/1 Header Fields into Structured Headers . . 14 4.2. Parsing HTTP/1 Header Fields into Structured Headers . . 14
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
6. Security Considerations . . . . . . . . . . . . . . . . . . . 22 6. Security Considerations . . . . . . . . . . . . . . . . . . . 22
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.1. Normative References . . . . . . . . . . . . . . . . . . 22 7.1. Normative References . . . . . . . . . . . . . . . . . . 22
7.2. Informative References . . . . . . . . . . . . . . . . . 23 7.2. Informative References . . . . . . . . . . . . . . . . . 23
7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 23 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 24 Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 24
A.1. Since draft-ietf-httpbis-header-structure-05 . . . . . . 24 A.1. Why not JSON? . . . . . . . . . . . . . . . . . . . . . . 24
A.2. Since draft-ietf-httpbis-header-structure-04 . . . . . . 24 A.2. Structured Headers don't "fit" my data. . . . . . . . . . 25
A.3. Since draft-ietf-httpbis-header-structure-03 . . . . . . 24 Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . 25
A.4. Since draft-ietf-httpbis-header-structure-02 . . . . . . 24 B.1. Since draft-ietf-httpbis-header-structure-06 . . . . . . 25
A.5. Since draft-ietf-httpbis-header-structure-01 . . . . . . 25 B.2. Since draft-ietf-httpbis-header-structure-05 . . . . . . 25
A.6. Since draft-ietf-httpbis-header-structure-00 . . . . . . 25 B.3. Since draft-ietf-httpbis-header-structure-04 . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 B.4. Since draft-ietf-httpbis-header-structure-03 . . . . . . 26
B.5. Since draft-ietf-httpbis-header-structure-02 . . . . . . 26
B.6. Since draft-ietf-httpbis-header-structure-01 . . . . . . 26
B.7. Since draft-ietf-httpbis-header-structure-00 . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27
1. Introduction 1. Introduction
Specifying the syntax of new HTTP header fields is an onerous task; Specifying the syntax of new HTTP header fields is an onerous task;
even with the guidance in [RFC7231], Section 8.3.1, there are many even with the guidance in [RFC7231], Section 8.3.1, there are many
decisions - and pitfalls - for a prospective HTTP header field decisions - and pitfalls - for a prospective HTTP header field
author. author.
Once a header field is defined, bespoke parsers and serialisers often Once a header field is defined, bespoke parsers and serialisers often
need to be written, because each header has slightly different need to be written, because each header has slightly different
skipping to change at page 4, line 14 skipping to change at page 4, line 18
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document uses the Augmented Backus-Naur Form (ABNF) notation of This document uses the Augmented Backus-Naur Form (ABNF) notation of
[RFC5234], including the DIGIT, ALPHA and DQUOTE rules from that [RFC5234], including the VCHAR, DIGIT, ALPHA and DQUOTE rules from
document. It also includes the OWS rule from [RFC7230]. that document. It also includes the OWS rule from [RFC7230].
This document uses algorithms to specify parsing and serialisation This document uses algorithms to specify parsing and serialisation
behaviours, and ABNF to illustrate expected syntax. behaviours, and ABNF to illustrate expected syntax.
For parsing, implementations MUST follow the algorithms, but MAY vary For parsing, implementations MUST follow the algorithms, but MAY vary
in implementation so as the behaviours are indistinguishable from in implementation so as the behaviours are indistinguishable from
specified behaviour. If there is disagreement between the parsing specified behaviour. If there is disagreement between the parsing
algorithms and ABNF, the specified algorithms take precedence. algorithms and ABNF, the specified algorithms take precedence.
For serialisation, the ABNF illustrates the range of acceptable wire For serialisation, the ABNF illustrates the range of acceptable wire
skipping to change at page 4, line 46 skipping to change at page 4, line 50
o Reference this specification. Recipients and generators of the o Reference this specification. Recipients and generators of the
header need to know that the requirements of this document are in header need to know that the requirements of this document are in
effect. effect.
o Specify the header field's allowed syntax for values, in terms of o Specify the header field's allowed syntax for values, in terms of
the types described in Section 3, along with their associated the types described in Section 3, along with their associated
semantics. Syntax definitions are encouraged to use the ABNF semantics. Syntax definitions are encouraged to use the ABNF
rules beginning with "sh-" defined in this specification. rules beginning with "sh-" defined in this specification.
o Specify any additional constraints upon the syntax of the o Specify any additional constraints upon the syntax of the
structured sued, as well as the consequences when those structured used, as well as the consequences when those
constraints are violated. When Structured Headers parsing fails, constraints are violated. When Structured Headers parsing fails,
the header is discarded (see Section 4.2); in most situations, the header is discarded (see Section 4.2); in most situations,
header-specific constraints should do likewise. header-specific constraints should do likewise.
Note that a header field definition cannot relax the requirements of Note that a header field definition cannot relax the requirements of
a structure or its processing; they can only add additional a structure or its processing; they can only add additional
constraints, because doing so would preclude handling by generic constraints, because doing so would preclude handling by generic
software. software.
For example: For example:
skipping to change at page 13, line 31 skipping to change at page 13, line 33
6. Append input's decimal component represented in base 10 using 6. Append input's decimal component represented in base 10 using
only decimal digits to output; if it is zero, append "0". only decimal digits to output; if it is zero, append "0".
7. Return output. 7. Return output.
4.1.7. Serialising a String 4.1.7. Serialising a String
Given a string as input: Given a string as input:
1. If input is not a sequence of characters, or contains characters 1. If input is not a sequence of characters, or contains characters
outside the range allowed by the ABNF defined in Section 3.7, outside the range allowed by VCHAR, fail serialisation.
fail serialisation.
2. Let output be an empty string. 2. Let output be an empty string.
3. Append DQUOTE to output. 3. Append DQUOTE to output.
4. For each character char in input: 4. For each character char in input:
1. If char is "" or DQUOTE: 1. If char is "\" or DQUOTE:
1. Append "" to output. 1. Append "\" to output.
2. Append char to output, using ASCII encoding [RFC0020]. 2. Append char to output, using ASCII encoding [RFC0020].
5. Append DQUOTE to output. 5. Append DQUOTE to output.
6. Return output. 6. Return output.
4.1.8. Serialising an Identifier 4.1.8. Serialising an Identifier
Given an identifier as input: Given an identifier as input:
skipping to change at page 14, line 36 skipping to change at page 14, line 36
3. Append "*" to output. 3. Append "*" to output.
4. Append the result of base64-encoding input as per [RFC4648], 4. Append the result of base64-encoding input as per [RFC4648],
Section 4, taking account of the requirements below. Section 4, taking account of the requirements below.
5. Append "*" to output. 5. Append "*" to output.
6. Return output. 6. Return output.
The encoded data is required to be padded with "=", as per [RFC4648], The encoded data is required to be padded with "=", as per [RFC4648],
Section 3.2. Likewise, encoded data is required to have pad bits set Section 3.2.
to zero, as per [RFC4648], Section 3.5.
Likewise, encoded data SHOULD have pad bits set to zero, as per
[RFC4648], Section 3.5, unless it is not possible to do so due to
implementation constraints.
4.2. Parsing HTTP/1 Header Fields into Structured Headers 4.2. Parsing HTTP/1 Header Fields into Structured Headers
When a receiving implementation parses textual HTTP header fields When a receiving implementation parses textual HTTP header fields
(e.g., in HTTP/1 or HTTP/2) that are known to be Structured Headers, (e.g., in HTTP/1 or HTTP/2) that are known to be Structured Headers,
it is important that care be taken, as there are a number of edge it is important that care be taken, as there are a number of edge
cases that can cause interoperability or even security problems. cases that can cause interoperability or even security problems.
This section specifies the algorithm for doing so. This section specifies the algorithm for doing so.
Given an ASCII string input_string that represents the chosen Given an ASCII string input_string that represents the chosen
skipping to change at page 16, line 12 skipping to change at page 16, line 14
1. Let dictionary be an empty, unordered mapping. 1. Let dictionary be an empty, unordered mapping.
2. While input_string is not empty: 2. While input_string is not empty:
1. Let this_key be the result of running Parse Identifier from 1. Let this_key be the result of running Parse Identifier from
Text (Section 4.2.8) with input_string. Text (Section 4.2.8) with input_string.
2. If dictionary already contains this_key, fail parsing. 2. If dictionary already contains this_key, fail parsing.
3. Consume a "=" from input_string; if none is present, fail 3. Consume the first character of input_string; if it is not
parsing. "=", fail parsing.
4. Let this_value be the result of running Parse Item from Text 4. Let this_value be the result of running Parse Item from Text
(Section 4.2.5) with input_string. (Section 4.2.5) with input_string.
5. Add key this_key with value this_value to dictionary. 5. Add key this_key with value this_value to dictionary.
6. Discard any leading OWS from input_string. 6. Discard any leading OWS from input_string.
7. If input_string is empty, return dictionary. 7. If input_string is empty, return dictionary.
8. Consume a COMMA from input_string; if no comma is present, 8. Consume the first character of input_string; if it is not
fail parsing. COMMA, fail parsing.
9. Discard any leading OWS from input_string. 9. Discard any leading OWS from input_string.
10. If input_string is empty, fail parsing. 10. If input_string is empty, fail parsing.
3. No structured data has been found; fail parsing. 3. No structured data has been found; fail parsing.
4.2.2. Parsing a List from Text 4.2.2. Parsing a List from Text
Given an ASCII string input_string, return a list of items. Given an ASCII string input_string, return a list of items.
skipping to change at page 16, line 51 skipping to change at page 17, line 5
1. Let item be the result of running Parse Item from Text 1. Let item be the result of running Parse Item from Text
(Section 4.2.5) with input_string. (Section 4.2.5) with input_string.
2. Append item to items. 2. Append item to items.
3. Discard any leading OWS from input_string. 3. Discard any leading OWS from input_string.
4. If input_string is empty, return items. 4. If input_string is empty, return items.
5. Consume a COMMA from input_string; if no comma is present, 5. Consume the first character of input_string; if it is not
fail parsing. COMMA, fail parsing.
6. Discard any leading OWS from input_string. 6. Discard any leading OWS from input_string.
7. If input_string is empty, fail parsing. 7. If input_string is empty, fail parsing.
3. No structured data has been found; fail parsing. 3. No structured data has been found; fail parsing.
4.2.3. Parsing a Parameterised List from Text 4.2.3. Parsing a Parameterised List from Text
Given an ASCII string input_string, return a list of parameterised Given an ASCII string input_string, return a list of parameterised
skipping to change at page 17, line 29 skipping to change at page 17, line 32
1. Let item be the result of running Parse Parameterised 1. Let item be the result of running Parse Parameterised
Identifier from Text (Section 4.2.4) with input_string. Identifier from Text (Section 4.2.4) with input_string.
2. Append item to items. 2. Append item to items.
3. Discard any leading OWS from input_string. 3. Discard any leading OWS from input_string.
4. If input_string is empty, return items. 4. If input_string is empty, return items.
5. Consume a COMMA from input_string; if no comma is present, 5. Consume the first character of input_string; if it is not
fail parsing. COMMA, fail parsing.
6. Discard any leading OWS from input_string. 6. Discard any leading OWS from input_string.
7. If input_string is empty, fail parsing. 7. If input_string is empty, fail parsing.
3. No structured data has been found; fail parsing. 3. No structured data has been found; fail parsing.
4.2.4. Parsing a Parameterised Identifier from Text 4.2.4. Parsing a Parameterised Identifier from Text
Given an ASCII string input_string, return a identifier with an Given an ASCII string input_string, return a identifier with an
skipping to change at page 19, line 42 skipping to change at page 19, line 42
input_number and set type to "float". input_number and set type to "float".
4. Otherwise, fail parsing. 4. Otherwise, fail parsing.
5. If type is "integer" and input_number contains more than 19 5. If type is "integer" and input_number contains more than 19
characters, fail parsing. characters, fail parsing.
6. If type is "float" and input_number contains more than 16 6. If type is "float" and input_number contains more than 16
characters, fail parsing. characters, fail parsing.
8. If type is "integer", parse input_number as an integer and let 8. If type is "integer":
output_number be the result.
1. Parse input_number as an integer and let output_number be
the result.
2. If output_number is outside the range defined in
Section 3.5, fail parsing.
9. Otherwise: 9. Otherwise:
1. If the final character of input_number is ".", fail parsing. 1. If the final character of input_number is ".", fail parsing.
2. Parse input_number as a float and let output_number be the 2. Parse input_number as a float and let output_number be the
result. result.
10. Return the product of output_number and sign. 10. Return the product of output_number and sign.
Parsers that encounter an integer outside the range defined in
Section 3.5 MUST fail parsing. Therefore, the value
"9223372036854775808" would be invalid. Likewise, values that do not
conform to the ABNF above are invalid, and MUST fail parsing.
Parsers that encounter a float that does not conform to the ABNF in
Section 3.6 MUST fail parsing.
4.2.7. Parsing a String from Text 4.2.7. Parsing a String from Text
Given an ASCII string input_string, return an unquoted string. Given an ASCII string input_string, return an unquoted string.
input_string is modified to remove the parsed value. input_string is modified to remove the parsed value.
1. Let output_string be an empty string. 1. Let output_string be an empty string.
2. If the first character of input_string is not DQUOTE, fail 2. If the first character of input_string is not DQUOTE, fail
parsing. parsing.
skipping to change at page 20, line 45 skipping to change at page 20, line 42
1. Let next_char be the result of removing the first 1. Let next_char be the result of removing the first
character of input_string. character of input_string.
2. If next_char is not DQUOTE or "\", fail parsing. 2. If next_char is not DQUOTE or "\", fail parsing.
3. Append next_char to output_string. 3. Append next_char to output_string.
3. Else, if char is DQUOTE, return output_string. 3. Else, if char is DQUOTE, return output_string.
4. Else, append char to output_string. 4. Else, if char is in the range %x00-1f or %x7f (i.e., is not
in VCHAR), fail parsing.
5. Else, append char to output_string.
5. Otherwise, fail parsing. 5. Otherwise, fail parsing.
4.2.8. Parsing an Identifier from Text 4.2.8. Parsing an Identifier from Text
Given an ASCII string input_string, return a identifier. input_string Given an ASCII string input_string, return a identifier. input_string
is modified to remove the parsed value. is modified to remove the parsed value.
1. If the first character of input_string is not lcalpha, fail 1. If the first character of input_string is not lcalpha, fail
parsing. parsing.
skipping to change at page 21, line 46 skipping to change at page 21, line 46
2. Discard the first character of input_string. 2. Discard the first character of input_string.
3. Let b64_content be the result of removing content of input_string 3. Let b64_content be the result of removing content of input_string
up to but not including the first instance of the character "*". up to but not including the first instance of the character "*".
If there is not a "*" character before the end of input_string, If there is not a "*" character before the end of input_string,
fail parsing. fail parsing.
4. Consume the "*" character at the beginning of input_string. 4. Consume the "*" character at the beginning of input_string.
5. Let binary_content be the result of Base 64 Decoding [RFC4648] 5. If b64_content contains a character not included in ALPHA, DIGIT,
"+", "/" and "=", fail parsing.
6. Let binary_content be the result of Base 64 Decoding [RFC4648]
b64_content, synthesising padding if necessary (note the b64_content, synthesising padding if necessary (note the
requirements about recipient behaviour below). requirements about recipient behaviour below).
6. Return binary_content. 7. Return binary_content.
As per [RFC4648], Section 3.2, it is RECOMMENDED that parsers reject As per [RFC4648], Section 3.2, it is RECOMMENDED that parsers reject
encoded data that is not properly padded, although this might not be encoded data that is not properly padded, although this might not be
possible in some base64 implementations. possible in some base64 implementations.
As per [RFC4648], Section 3.5, it is RECOMMENDED that parsers fail on Because some implementations of base64 do not allow rejection of
encoded data that has non-zero pad bits, although this might not be encoded data that has non-zero pad bits (see [RFC4648], Section 3.5),
possible in some base64 implementations. parsers SHOULD NOT fail when it is present, unless they cannot be
configured to handle it.
This specification does not relax the requirements in [RFC4648], This specification does not relax the requirements in [RFC4648],
Section 3.1 and 3.3; therefore, parsers MUST fail on characters Section 3.1 and 3.3; therefore, parsers MUST fail on characters
outside the base64 alphabet, and on line feeds in encoded data. outside the base64 alphabet, and on line feeds in encoded data.
5. IANA Considerations 5. IANA Considerations
This draft has no actions for IANA. This draft has no actions for IANA.
6. Security Considerations 6. Security Considerations
skipping to change at page 23, line 33 skipping to change at page 23, line 33
ISBN 978-0-7381-5752-8, August 2008, ISBN 978-0-7381-5752-8, August 2008,
<http://ieeexplore.ieee.org/document/4610935/>. <http://ieeexplore.ieee.org/document/4610935/>.
See also http://grouper.ieee.org/groups/754/ [6]. See also http://grouper.ieee.org/groups/754/ [6].
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231, Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014, DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>. <https://www.rfc-editor.org/info/rfc7231>.
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
DOI 10.17487/RFC7493, March 2015,
<https://www.rfc-editor.org/info/rfc7493>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540, Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015, DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>. <https://www.rfc-editor.org/info/rfc7540>.
[RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for
HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015,
<https://www.rfc-editor.org/info/rfc7541>. <https://www.rfc-editor.org/info/rfc7541>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
7.3. URIs 7.3. URIs
[1] https://lists.w3.org/Archives/Public/ietf-http-wg/ [1] https://lists.w3.org/Archives/Public/ietf-http-wg/
[2] https://httpwg.github.io/ [2] https://httpwg.github.io/
[3] https://github.com/httpwg/http-extensions/labels/header-structure [3] https://github.com/httpwg/http-extensions/labels/header-structure
[4] https://github.com/httpwg/structured-header-tests [4] https://github.com/httpwg/structured-header-tests
[5] https://github.com/httpwg/wiki/wiki/Structured-Headers [5] https://github.com/httpwg/wiki/wiki/Structured-Headers
Appendix A. Changes Appendix A. Frequently Asked Questions
A.1. Since draft-ietf-httpbis-header-structure-05 A.1. Why not JSON?
Earlier proposals for structured headers were based upon JSON
[RFC8259]. However, constraining its use to make it suitable for
HTTP header fields required senders and recipients to implement
specific additional handling.
For example, JSON has specification issues around large numbers and
objects with duplicate members. Although advice for avoiding these
issues is available (e.g., [RFC7493]), it cannot be relied upon.
Likewise, JSON strings are by default Unicode strings, which have a
number of potential interoperability issues (e.g., in comparison).
Although implementers can be advised to avoid non-ASCII content where
unnecessary, this is difficult to enforce.
Another example is JSON's ability to nest content to arbitrary
depths. Since the resulting memory commitment might be unsuitable
(e.g., in embedded and other limited server deployments), it's
necessary to limit it in some fashion; however, existing JSON
implementations have no such limits, and even if a limit is
specified, it's likely that some header field definition will find a
need to violate it.
Because of JSON's broad adoption and implementation, it is difficult
to impose such additional constraints across all implementations;
some deployments would fail to enforce them, thereby harming
interoperability.
Since a major goal for Structured Headers is to improve
interoperability and simplify implementation, these concerns led to a
format that requires a dedicated parser and serialiser.
Additionally, there were widely shared feelings that JSON doesn't
"look right" in HTTP headers.
A.2. Structured Headers don't "fit" my data.
Structured headers intentionally limits the complexity of data
structures, to assure that it can be processed in a performant manner
with little overhead. This means that work is necessary to fit some
data types into them.
Sometimes, this can be achieved by creating limited substructures in
values, and/or using more than one header. For example, consider:
Example-Thing: name="Widget", cost=89.2, descriptions="foo bar"
Example-Description: foo; url="https://example.net"; context=123,
bar; url="https://example.org"; context=456
Since the description contains a list of key/value pairs, we use a
Parameterised List to represent them, with the identifier for each
item in the list used to identify it in the "descriptions" member of
the Example-Thing header.
When specifying more than one header, it's important to remember to
describe what a processor's behaviour should be when one of the
headers is missing.
If you need to fit arbitrarily complex data into a header, Structured
Headers is probably a poor fit for your use case.
Appendix B. Changes
_RFC Editor: Please remove this section before publication._
B.1. Since draft-ietf-httpbis-header-structure-06
o Add a FAQ.
o Allow non-zero pad bits.
o Explicitly check for integers that violate constraints.
B.2. Since draft-ietf-httpbis-header-structure-05
o Reorganise specification to separate parsing out. o Reorganise specification to separate parsing out.
o Allow referencing specs to use ABNF. o Allow referencing specs to use ABNF.
o Define serialisation algorithms. o Define serialisation algorithms.
o Refine relationship between ABNF, parsing and serialisation o Refine relationship between ABNF, parsing and serialisation
algorithms. algorithms.
A.2. Since draft-ietf-httpbis-header-structure-04 B.3. Since draft-ietf-httpbis-header-structure-04
o Remove identifiers from item. o Remove identifiers from item.
o Remove most limits on sizes. o Remove most limits on sizes.
o Refine number parsing. o Refine number parsing.
A.3. Since draft-ietf-httpbis-header-structure-03 B.4. Since draft-ietf-httpbis-header-structure-03
o Strengthen language around failure handling. o Strengthen language around failure handling.
A.4. Since draft-ietf-httpbis-header-structure-02 B.5. Since draft-ietf-httpbis-header-structure-02
o Split Numbers into Integers and Floats. o Split Numbers into Integers and Floats.
o Define number parsing. o Define number parsing.
o Tighten up binary parsing and give it an explicit end delimiter. o Tighten up binary parsing and give it an explicit end delimiter.
o Clarify that mappings are unordered. o Clarify that mappings are unordered.
o Allow zero-length strings. o Allow zero-length strings.
o Improve string parsing algorithm. o Improve string parsing algorithm.
o Improve limits in algorithms. o Improve limits in algorithms.
o Require parsers to combine header fields before processing. o Require parsers to combine header fields before processing.
o Throw an error on trailing garbage. o Throw an error on trailing garbage.
A.5. Since draft-ietf-httpbis-header-structure-01 B.6. Since draft-ietf-httpbis-header-structure-01
o Replaced with draft-nottingham-structured-headers. o Replaced with draft-nottingham-structured-headers.
A.6. Since draft-ietf-httpbis-header-structure-00 B.7. Since draft-ietf-httpbis-header-structure-00
o Added signed 64bit integer type. o Added signed 64bit integer type.
o Drop UTF8, and settle on BCP137 ::EmbeddedUnicodeChar for h1- o Drop UTF8, and settle on BCP137 ::EmbeddedUnicodeChar for h1-
unicode-string. unicode-string.
o Change h1_blob delimiter to ":" since "'" is valid t_char o Change h1_blob delimiter to ":" since "'" is valid t_char
Authors' Addresses Authors' Addresses
 End of changes. 30 change blocks. 
54 lines changed or deleted 147 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/