draft-ietf-httpbis-header-structure-13.txt   draft-ietf-httpbis-header-structure-latest.txt 
HTTP Working Group M. Nottingham HTTP Working Group M. Nottingham
Internet-Draft Fastly Internet-Draft Fastly
Intended status: Standards Track P-H. Kamp Intended status: Standards Track P-H. Kamp
Expires: February 25, 2020 The Varnish Cache Project Expires: April 21, 2020 The Varnish Cache Project
August 24, 2019 October 19, 2019
Structured Headers for HTTP Structured Headers for HTTP
draft-ietf-httpbis-header-structure-13 draft-ietf-httpbis-header-structure-latest
Abstract Abstract
This document describes a set of data types and associated algorithms This document describes a set of data types and associated algorithms
that are intended to make it easier and safer to define and handle that are intended to make it easier and safer to define and handle
HTTP header fields. It is intended for use by specifications of new HTTP header fields. It is intended for use by specifications of new
HTTP header fields that wish to use a common syntax that is more HTTP header fields that wish to use a common syntax that is more
restrictive than traditional HTTP field values. restrictive than traditional HTTP field values.
Note to Readers Note to Readers
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 February 25, 2020. This Internet-Draft will expire on April 21, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 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 43 skipping to change at page 2, line 43
3. Structured Header Data Types . . . . . . . . . . . . . . . . 6 3. Structured Header Data Types . . . . . . . . . . . . . . . . 6
3.1. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 8 3.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 8
3.3. Items . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.3. Items . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4. Integers . . . . . . . . . . . . . . . . . . . . . . . . 9 3.4. Integers . . . . . . . . . . . . . . . . . . . . . . . . 9
3.5. Floats . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.5. Floats . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.6. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.6. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.7. Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.7. Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.8. Byte Sequences . . . . . . . . . . . . . . . . . . . . . 11 3.8. Byte Sequences . . . . . . . . . . . . . . . . . . . . . 11
3.9. Booleans . . . . . . . . . . . . . . . . . . . . . . . . 11 3.9. Booleans . . . . . . . . . . . . . . . . . . . . . . . . 11
4. Working With Structured Headers in Textual HTTP Headers . . . 12 4. Working With Structured Headers in HTTP Headers . . . . . . . 12
4.1. Serializing Structured Headers . . . . . . . . . . . . . 12 4.1. Serializing Structured Headers . . . . . . . . . . . . . 12
4.2. Parsing Header Fields into Structured Headers . . . . . . 18 4.2. Parsing Header Fields into Structured Headers . . . . . . 18
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
6. Security Considerations . . . . . . . . . . . . . . . . . . . 27 6. Security Considerations . . . . . . . . . . . . . . . . . . . 27
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.1. Normative References . . . . . . . . . . . . . . . . . . 27 7.1. Normative References . . . . . . . . . . . . . . . . . . 27
7.2. Informative References . . . . . . . . . . . . . . . . . 28 7.2. Informative References . . . . . . . . . . . . . . . . . 28
7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 29 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 29 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 29
Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 29 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 29
B.1. Why not JSON? . . . . . . . . . . . . . . . . . . . . . . 29 B.1. Why not JSON? . . . . . . . . . . . . . . . . . . . . . . 29
B.2. Structured Headers don't "fit" my data. . . . . . . . . . 30 B.2. Structured Headers don't "fit" my data. . . . . . . . . . 30
Appendix C. Implementation Notes . . . . . . . . . . . . . . . . 31 Appendix C. Implementation Notes . . . . . . . . . . . . . . . . 31
Appendix D. Changes . . . . . . . . . . . . . . . . . . . . . . 31 Appendix D. Changes . . . . . . . . . . . . . . . . . . . . . . 31
D.1. Since draft-ietf-httpbis-header-structure-12 . . . . . . 31 D.1. Since draft-ietf-httpbis-header-structure-13 . . . . . . 31
D.2. Since draft-ietf-httpbis-header-structure-11 . . . . . . 31 D.2. Since draft-ietf-httpbis-header-structure-12 . . . . . . 31
D.3. Since draft-ietf-httpbis-header-structure-10 . . . . . . 31 D.3. Since draft-ietf-httpbis-header-structure-11 . . . . . . 32
D.4. Since draft-ietf-httpbis-header-structure-09 . . . . . . 32 D.4. Since draft-ietf-httpbis-header-structure-10 . . . . . . 32
D.5. Since draft-ietf-httpbis-header-structure-08 . . . . . . 32 D.5. Since draft-ietf-httpbis-header-structure-09 . . . . . . 32
D.6. Since draft-ietf-httpbis-header-structure-07 . . . . . . 33 D.6. Since draft-ietf-httpbis-header-structure-08 . . . . . . 32
D.7. Since draft-ietf-httpbis-header-structure-06 . . . . . . 33 D.7. Since draft-ietf-httpbis-header-structure-07 . . . . . . 33
D.8. Since draft-ietf-httpbis-header-structure-05 . . . . . . 33 D.8. Since draft-ietf-httpbis-header-structure-06 . . . . . . 33
D.9. Since draft-ietf-httpbis-header-structure-04 . . . . . . 33 D.9. Since draft-ietf-httpbis-header-structure-05 . . . . . . 33
D.10. Since draft-ietf-httpbis-header-structure-03 . . . . . . 34 D.10. Since draft-ietf-httpbis-header-structure-04 . . . . . . 34
D.11. Since draft-ietf-httpbis-header-structure-02 . . . . . . 34 D.11. Since draft-ietf-httpbis-header-structure-03 . . . . . . 34
D.12. Since draft-ietf-httpbis-header-structure-01 . . . . . . 34 D.12. Since draft-ietf-httpbis-header-structure-02 . . . . . . 34
D.13. Since draft-ietf-httpbis-header-structure-00 . . . . . . 34 D.13. Since draft-ietf-httpbis-header-structure-01 . . . . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 D.14. Since draft-ietf-httpbis-header-structure-00 . . . . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35
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 Section 8.3.1 of [RFC7231], there are many even with the guidance in Section 8.3.1 of [RFC7231], 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 serializers often Once a header field is defined, bespoke parsers and serializers often
need to be written, because each header has slightly different need to be written, because each header has slightly different
handling of what looks like common syntax. handling of what looks like common syntax.
This document introduces a set of common data structures for use in This document introduces a set of common data structures for use in
definitions of new HTTP header field values to address these definitions of new HTTP header field values to address these
problems. In particular, it defines a generic, abstract model for problems. In particular, it defines a generic, abstract model for
header field values, along with a concrete serialisation for header field values, along with a concrete serialisation for
expressing that model in textual HTTP [RFC7230] header fields. expressing that model in HTTP [RFC7230] header fields.
HTTP headers that are defined as "Structured Headers" use the types HTTP headers that are defined as "Structured Headers" use the types
defined in this specification to define their syntax and basic defined in this specification to define their syntax and basic
handling rules, thereby simplifying both their definition by handling rules, thereby simplifying both their definition by
specification writers and handling by implementations. specification writers and handling by implementations.
Additionally, future versions of HTTP can define alternative Additionally, future versions of HTTP can define alternative
serialisations of the abstract model of these structures, allowing serialisations of the abstract model of these structures, allowing
headers that use it to be transmitted more efficiently without being headers that use it to be transmitted more efficiently without being
redefined. redefined.
Note that it is not a goal of this document to redefine the syntax of Note that it is not a goal of this document to redefine the syntax of
existing HTTP headers; the mechanisms described herein are only existing HTTP headers; the mechanisms described herein are only
intended to be used with headers that explicitly opt into them. intended to be used with headers that explicitly opt into them.
Section 2 describes how to specify a Structured Header. Section 2 describes how to specify a Structured Header.
Section 3 defines a number of abstract data types that can be used in Section 3 defines a number of abstract data types that can be used in
Structured Headers. Those abstract types can be serialized into and Structured Headers. Those abstract types can be serialized into and
parsed from textual HTTP headers using the algorithms described in parsed from HTTP headers using the algorithms described in Section 4.
Section 4.
1.1. Intentionally Strict Processing 1.1. Intentionally Strict Processing
This specification intentionally defines strict parsing and This specification intentionally defines strict parsing and
serialisation behaviours using step-by-step algorithms; the only serialisation behaviours using step-by-step algorithms; the only
error handling defined is to fail the operation altogether. error handling defined is to fail the operation altogether.
It is designed to encourage faithful implementation and therefore It is designed to encourage faithful implementation and therefore
good interoperability. Therefore, an implementation that tried to be good interoperability. Therefore, an implementation that tried to be
"helpful" by being more tolerant of input would make interoperability "helpful" by being more tolerant of input would make interoperability
skipping to change at page 4, line 48 skipping to change at page 4, line 47
1.2. Notational Conventions 1.2. 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 algorithms to specify parsing and serialisation This document uses algorithms to specify parsing and serialisation
behaviours, and the Augmented Backus-Naur Form (ABNF) notation of behaviours, and the Augmented Backus-Naur Form (ABNF) notation of
[RFC5234] to illustrate expected syntax in textual HTTP header [RFC5234] to illustrate expected syntax in HTTP header fields. In
fields. In doing so, uses the VCHAR, SP, DIGIT, ALPHA and DQUOTE doing so, uses the VCHAR, SP, DIGIT, ALPHA and DQUOTE rules from
rules from [RFC5234]. It also includes the OWS rule from [RFC7230]. [RFC5234]. It also includes the OWS rule from [RFC7230].
When parsing from textual HTTP header fields, implementations MUST When parsing from HTTP header fields, implementations MUST follow the
follow the algorithms, but MAY vary in implementation so as the algorithms, but MAY vary in implementation so as the behaviours are
behaviours are indistinguishable from specified behaviour. If there indistinguishable from specified behaviour. If there is disagreement
is disagreement between the parsing algorithms and ABNF, the between the parsing algorithms and ABNF, the specified algorithms
specified algorithms take precedence. In some places, the algorithms take precedence. In some places, the algorithms are "greedy" with
are "greedy" with whitespace, but this should not affect conformance. whitespace, but this should not affect conformance.
For serialisation to textual header fields, the ABNF illustrates the For serialisation to header fields, the ABNF illustrates the range of
range of acceptable wire representations with as much fidelity as acceptable wire representations with as much fidelity as possible,
possible, and the algorithms define the recommended way to produce and the algorithms define the recommended way to produce them.
them. Implementations MAY vary from the specified behaviour so long Implementations MAY vary from the specified behaviour so long as the
as the output still matches the ABNF. output still matches the ABNF.
2. Defining New Structured Headers 2. Defining New Structured Headers
To define a HTTP header as a structured header, its specification To define a HTTP header as a structured header, its specification
needs to: needs to:
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.
skipping to change at page 6, line 7 skipping to change at page 6, line 5
can only use Structured Headers for the entire header field value, can only use Structured Headers for the entire header field value,
not a portion thereof. not a portion thereof.
This specification defines minimums for the length or number of This specification defines minimums for the length or number of
various structures supported by Structured Headers implementations. various structures supported by Structured Headers implementations.
It does not specify maximum sizes in most cases, but header authors It does not specify maximum sizes in most cases, but header authors
should be aware that HTTP implementations do impose various limits on should be aware that HTTP implementations do impose various limits on
the size of individual header fields, the total number of fields, the size of individual header fields, the total number of fields,
and/or the size of the entire header block. and/or the size of the entire header block.
Specifications can refer to a Structured Header's field-name as a
"structured header name" and its field-value as a "structured header
value" as necessary.
For example, a fictitious Foo-Example header field might be specified For example, a fictitious Foo-Example header field might be specified
as: as:
42. Foo-Example Header 42. Foo-Example Header
The Foo-Example HTTP header field conveys information about how The Foo-Example HTTP header field conveys information about how
much Foo the message has. much Foo the message has.
Foo-Example is a Structured Header [RFCxxxx]. Its value MUST be a Foo-Example is a Structured Header [RFCxxxx]. Its value MUST be a
dictionary (Section Y.Y of [RFCxxxx]). Its ABNF is: dictionary (Section Y.Y of [RFCxxxx]). Its ABNF is:
skipping to change at page 6, line 29 skipping to change at page 6, line 31
The dictionary MUST contain: The dictionary MUST contain:
* Exactly one member whose name is "foo", and whose value is an * Exactly one member whose name is "foo", and whose value is an
integer (Section Y.Y of [RFCxxxx]), indicating the number of foos integer (Section Y.Y of [RFCxxxx]), indicating the number of foos
in the message. in the message.
* Exactly one member whose name is "barUrl", and whose value is a * Exactly one member whose name is "barUrl", and whose value is a
list of strings (Section Y.Y of [RFCxxxx]), conveying the Bar URLs list of strings (Section Y.Y of [RFCxxxx]), conveying the Bar URLs
for the message. See below for processing requirements. for the message. See below for processing requirements.
If the parsed header field does not contain both, it MUST be If the structured header value does not contain both, it MUST be
ignored. ignored.
"foo" MUST be between 0 and 10, inclusive; other values MUST cause "foo" MUST be between 0 and 10, inclusive; other values MUST cause
the header to be ignored. the header to be ignored.
"barUrl" contains one or more URI-references (Section 4.1 of "barUrl" contains one or more URI-references (Section 4.1 of
[RFC3986], Section 4.1). If barURL is not a valid URI-reference, [RFC3986], Section 4.1). If barURL is not a valid URI-reference,
it MUST be ignored. If barURL is a relative reference (Section 4.2 it MUST be ignored. If barURL is a relative reference (Section 4.2
of [RFC3986]), it MUST be resolved (Section 5 of [RFC3986]) before of [RFC3986]), it MUST be resolved (Section 5 of [RFC3986]) before
being used. being used.
For example: For example:
Foo-Example: foo=2, barUrl=("https://bar.example.com/") Foo-Example: foo=2, barUrl=("https://bar.example.com/")
3. Structured Header Data Types 3. Structured Header Data Types
This section defines the abstract value types that can be composed This section defines the abstract value types that can be composed
into Structured Headers. The ABNF provided represents the on-wire into Structured Headers. The ABNF provided represents the on-wire
format in textual HTTP headers. format in HTTP headers.
3.1. Lists 3.1. Lists
Lists are arrays of zero or more members, each of which can be an Lists are arrays of zero or more members, each of which can be an
item (Section 3.3) or an inner list (an array of zero or more items). item (Section 3.3) or an inner list (an array of zero or more items).
Each member of the top-level list can also have associated parameters Each member of the top-level list can also have associated parameters
- an ordered map of key-value pairs where the keys are short, textual - an ordered map of key-value pairs where the keys are short, textual
strings and the values are items (Section 3.3). There can be zero or strings and the values are items (Section 3.3). There can be zero or
more parameters on a member, and their keys are required to be unique more parameters on a member, and their keys are required to be unique
skipping to change at page 7, line 27 skipping to change at page 7, line 27
sh-list = list-member *( OWS "," OWS list-member ) sh-list = list-member *( OWS "," OWS list-member )
list-member = ( sh-item / inner-list ) *parameter list-member = ( sh-item / inner-list ) *parameter
inner-list = "(" OWS [ sh-item *( SP sh-item ) OWS ] ")" inner-list = "(" OWS [ sh-item *( SP sh-item ) OWS ] ")"
parameter = OWS ";" OWS param-name [ "=" param-value ] parameter = OWS ";" OWS param-name [ "=" param-value ]
param-name = key param-name = key
key = lcalpha *( lcalpha / DIGIT / "_" / "-" / "*" ) key = lcalpha *( lcalpha / DIGIT / "_" / "-" / "*" )
lcalpha = %x61-7A ; a-z lcalpha = %x61-7A ; a-z
param-value = sh-item param-value = sh-item
In textual HTTP headers, each member is separated by a comma and In HTTP headers, each member is separated by a comma and optional
optional whitespace. For example, a header field whose value is whitespace. For example, a header field whose value is defined as a
defined as a list of strings could look like: list of strings could look like:
Example-StrListHeader: "foo", "bar", "It was the best of times." Example-StrListHeader: "foo", "bar", "It was the best of times."
In textual HTTP headers, inner lists are denoted by surrounding In HTTP headers, inner lists are denoted by surrounding parenthesis,
parenthesis, and have their values delimited by a single space. A and have their values delimited by a single space. A header field
header field whose value is defined as a list of lists of strings whose value is defined as a list of lists of strings could look like:
could look like:
Example-StrListListHeader: ("foo" "bar"), ("baz"), ("bat" "one"), () Example-StrListListHeader: ("foo" "bar"), ("baz"), ("bat" "one"), ()
Note that the last member in this example is an empty inner list. Note that the last member in this example is an empty inner list.
In textual HTTP headers, members' parameters are separated from the In HTTP headers, members' parameters are separated from the member
member and each other by semicolons. For example: and each other by semicolons. For example:
Example-ParamListHeader: abc;a=1;b=2; cde_456, (ghi jkl);q="9";r=w Example-ParamListHeader: abc;a=1;b=2; cde_456, (ghi jkl);q="9";r=w
In textual HTTP headers, an empty list is denoted by not serialising In HTTP headers, an empty list is denoted by not serialising the
the header at all. header at all.
Parsers MUST support lists containing at least 1024 members, support Parsers MUST support lists containing at least 1024 members, support
members with at least 256 parameters, support inner-lists containing members with at least 256 parameters, support inner-lists containing
at least 256 members, and support parameter keys with at least 64 at least 256 members, and support parameter keys with at least 64
characters. characters.
Header specifications can constrain the types of individual list Header specifications can constrain the types of individual list
values (including that of individual inner-list members and values (including that of individual inner-list members and
parameters) if necessary. parameters) if necessary.
skipping to change at page 8, line 29 skipping to change at page 8, line 27
Each member of the dictionary can also have associated parameters - Each member of the dictionary can also have associated parameters -
an ordered map of key-value pairs where the keys are short, textual an ordered map of key-value pairs where the keys are short, textual
strings and the values are items (Section 3.3). There can be zero or strings and the values are items (Section 3.3). There can be zero or
more parameters on a member, and their keys are required to be unique more parameters on a member, and their keys are required to be unique
within that scope. within that scope.
Implementations MUST provide access to dictionaries both by index and Implementations MUST provide access to dictionaries both by index and
by name. Specifications MAY use either means of accessing the by name. Specifications MAY use either means of accessing the
members. members.
The ABNF for dictionaries in textual HTTP headers is: The ABNF for dictionaries in HTTP headers is:
sh-dictionary = dict-member *( OWS "," OWS dict-member ) sh-dictionary = dict-member *( OWS "," OWS dict-member )
dict-member = member-name "=" member-value *parameter dict-member = member-name "=" member-value *parameter
member-name = key member-name = key
member-value = sh-item / inner-list member-value = sh-item / inner-list
In textual HTTP headers, members are separated by a comma with In HTTP headers, members are separated by a comma with optional
optional whitespace, while names and values are separated by "=" whitespace, while names and values are separated by "=" (without
(without whitespace). For example: whitespace). For example:
Example-DictHeader: en="Applepie", da=*w4ZibGV0w6ZydGU=* Example-DictHeader: en="Applepie", da=*w4ZibGV0w6ZydGU=*
A dictionary with a member whose value is an inner-list of tokens: A dictionary with a member whose value is an inner-list of tokens:
Example-DictListHeader: rating=1.5, feelings=(joy sadness) Example-DictListHeader: rating=1.5, feelings=(joy sadness)
A dictionary with a mix of singular and list values, some with A dictionary with a mix of singular and list values, some with
parameters: parameters:
Example-MixDict: a=(1,2), b=3, c=4;aa=bb, d=(5,6);valid=?T Example-MixDict: a=(1 2), b=3, c=4;aa=bb, d=(5 6);valid=?1
As with lists, an empty dictionary is represented in textual HTTP
headers by omitting the entire header field. As with lists, an empty dictionary is represented in HTTP headers by
omitting the entire header field.
Typically, a header field specification will define the semantics Typically, a header field specification will define the semantics
using individual member names, as well as whether their presence is using individual member names, as well as whether their presence is
required or optional. Recipients MUST ignore names that are required or optional. Recipients MUST ignore names that are
undefined or unknown, unless the header field's specification undefined or unknown, unless the header field's specification
specifically disallows them. specifically disallows them.
Parsers MUST support dictionaries containing at least 1024 name/value Parsers MUST support dictionaries containing at least 1024 name/value
pairs, and names with at least 64 characters. pairs, and names with at least 64 characters.
3.3. Items 3.3. Items
An item is can be a integer (Section 3.4), float (Section 3.5), An item is can be a integer (Section 3.4), float (Section 3.5),
string (Section 3.6), token (Section 3.7), byte sequence string (Section 3.6), token (Section 3.7), byte sequence
(Section 3.8), or Boolean (Section 3.9). (Section 3.8), or Boolean (Section 3.9).
The ABNF for items in textual HTTP headers is: The ABNF for items in HTTP headers is:
sh-item = sh-integer / sh-float / sh-string / sh-token / sh-binary sh-item = sh-integer / sh-float / sh-string / sh-token / sh-binary
/ sh-boolean / sh-boolean
3.4. Integers 3.4. Integers
Integers have a range of -999,999,999,999,999 to 999,999,999,999,999 Integers have a range of -999,999,999,999,999 to 999,999,999,999,999
inclusive (i.e., up to fifteen digits, signed), for IEEE 754 inclusive (i.e., up to fifteen digits, signed), for IEEE 754
compatibility ([IEEE754]). compatibility ([IEEE754]).
The ABNF for integers in textual HTTP headers is: The ABNF for integers in HTTP headers is:
sh-integer = ["-"] 1*15DIGIT sh-integer = ["-"] 1*15DIGIT
For example: For example:
Example-IntegerHeader: 42 Example-IntegerHeader: 42
Note that commas in integers are used in this section's prose only Note that commas in integers are used in this section's prose only
for readability; they are not valid in the wire format. for readability; they are not valid in the wire format.
3.5. Floats 3.5. Floats
Floats are decimal numbers with an integer and a fractional Floats are decimal numbers with an integer and a fractional
component. The fractional component has at most six digits of component. The fractional component has at most six digits of
precision. Additionally, like integers, it can have no more than precision. Additionally, like integers, it can have no more than
fifteen digits in total, which in some cases further constrains its fifteen digits in total, which in some cases further constrains its
precision. precision.
The ABNF for floats in textual HTTP headers is: The ABNF for floats in HTTP headers is:
sh-float = ["-"] (1*9DIGIT "." 1*6DIGIT / sh-float = ["-"] (1*9DIGIT "." 1*6DIGIT /
10DIGIT "." 1*5DIGIT / 10DIGIT "." 1*5DIGIT /
11DIGIT "." 1*4DIGIT / 11DIGIT "." 1*4DIGIT /
12DIGIT "." 1*3DIGIT / 12DIGIT "." 1*3DIGIT /
13DIGIT "." 1*2DIGIT / 13DIGIT "." 1*2DIGIT /
14DIGIT "." 1DIGIT ) 14DIGIT "." 1DIGIT )
For example, a header whose value is defined as a float could look For example, a header whose value is defined as a float could look
like: like:
Example-FloatHeader: 4.5 Example-FloatHeader: 4.5
3.6. Strings 3.6. Strings
Strings are zero or more printable ASCII [RFC0020] characters (i.e., Strings are zero or more printable ASCII [RFC0020] characters (i.e.,
the range 0x20 to 0x7E). Note that this excludes tabs, newlines, the range %x20 to %x7E). Note that this excludes tabs, newlines,
carriage returns, etc. carriage returns, etc.
The ABNF for strings in textual HTTP headers is: The ABNF for strings in HTTP headers is:
sh-string = DQUOTE *(chr) DQUOTE sh-string = DQUOTE *(chr) DQUOTE
chr = unescaped / escaped chr = unescaped / escaped
unescaped = %x20-21 / %x23-5B / %x5D-7E unescaped = %x20-21 / %x23-5B / %x5D-7E
escaped = "\" ( DQUOTE / "\" ) escaped = "\" ( DQUOTE / "\" )
In textual HTTP headers, strings are delimited with double quotes, In HTTP headers, strings are delimited with double quotes, using a
using a backslash ("\") to escape double quotes and backslashes. For backslash ("\") to escape double quotes and backslashes. For
example: example:
Example-StringHeader: "hello world" Example-StringHeader: "hello world"
Note that strings only use DQUOTE as a delimiter; single quotes do Note that strings only use DQUOTE as a delimiter; single quotes do
not delimit strings. Furthermore, only DQUOTE and "\" can be not delimit strings. Furthermore, only DQUOTE and "\" can be
escaped; other sequences MUST cause parsing to fail. escaped; other sequences MUST cause parsing to fail.
Unicode is not directly supported in this document, because it causes Unicode is not directly supported in this document, because it causes
a number of interoperability issues, and - with few exceptions - a number of interoperability issues, and - with few exceptions -
header values do not require it. header values do not require it.
When it is necessary for a field value to convey non-ASCII string When it is necessary for a field value to convey non-ASCII string
content, a byte sequence (Section 3.8) SHOULD be specified, along content, a byte sequence (Section 3.8) SHOULD be specified, along
with a character encoding (preferably UTF-8). with a character encoding (preferably [UTF-8]).
Parsers MUST support strings with at least 1024 characters. Parsers MUST support strings with at least 1024 characters.
3.7. Tokens 3.7. Tokens
Tokens are short textual words; their abstract model is identical to Tokens are short textual words; their abstract model is identical to
their expression in the textual HTTP serialisation. their expression in the HTTP header serialisation.
The ABNF for tokens in textual HTTP headers is: The ABNF for tokens in HTTP headers is:
sh-token = ALPHA sh-token = ALPHA
*( ALPHA / DIGIT / "_" / "-" / "." / ":" / "%" *( ALPHA / DIGIT / "_" / "-" / "." / ":" / "%"
/ "*" / "/" ) / "*" / "/" )
Parsers MUST support tokens with at least 512 characters. Parsers MUST support tokens with at least 512 characters.
Note that a Structured Header token is not the same as the "token" Note that a Structured Header token is not the same as the "token"
ABNF rule defined in [RFC7230]. ABNF rule defined in [RFC7230].
3.8. Byte Sequences 3.8. Byte Sequences
Byte sequences can be conveyed in Structured Headers. Byte sequences can be conveyed in Structured Headers.
The ABNF for a byte sequence in textual HTTP headers is: The ABNF for a byte sequence in HTTP headers is:
sh-binary = "*" *(base64) "*" sh-binary = "*" *(base64) "*"
base64 = ALPHA / DIGIT / "+" / "/" / "=" base64 = ALPHA / DIGIT / "+" / "/" / "="
In textual HTTP headers, a byte sequence is delimited with asterisks In HTTP headers, a byte sequence is delimited with asterisks and
and encoded using base64 ([RFC4648], Section 4). For example: encoded using base64 ([RFC4648], Section 4). For example:
Example-BinaryHdr: *cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==* Example-BinaryHdr: *cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==*
Parsers MUST support byte sequences with at least 16384 octets after Parsers MUST support byte sequences with at least 16384 octets after
decoding. decoding.
3.9. Booleans 3.9. Booleans
Boolean values can be conveyed in Structured Headers. Boolean values can be conveyed in Structured Headers.
The ABNF for a Boolean in textual HTTP headers is: The ABNF for a Boolean in HTTP headers is:
sh-boolean = "?" boolean sh-boolean = "?" boolean
boolean = "0" / "1" boolean = "0" / "1"
In textual HTTP headers, a boolean is indicated with a leading "?" In HTTP headers, a boolean is indicated with a leading "?" character
character. For example: followed by a "1" for a true value or "0" for false. For example:
Example-BoolHdr: ?1 Example-BoolHdr: ?1
4. Working With Structured Headers in Textual HTTP Headers 4. Working With Structured Headers in HTTP Headers
This section defines how to serialize and parse Structured Headers in This section defines how to serialize and parse Structured Headers in
textual header fields, and protocols compatible with them (e.g., in header fields, and protocols compatible with them (e.g., in HTTP/2
HTTP/2 [RFC7540] before HPACK [RFC7541] is applied). [RFC7540] before HPACK [RFC7541] is applied).
4.1. Serializing Structured Headers 4.1. Serializing Structured Headers
Given a structure defined in this specification, return an ASCII Given a structure defined in this specification, return an ASCII
string suitable for use in a textual HTTP header value. string suitable for use in a HTTP header value.
1. If the structure is a dictionary or list and its value is empty 1. If the structure is a dictionary or list and its value is empty
(i.e., it has no members), do not send the serialize field at all (i.e., it has no members), do not send the serialize field at all
(i.e., omit both the field-name and field-value). (i.e., omit both the field-name and field-value).
2. If the structure is a dictionary, let output_string be the result 2. If the structure is a dictionary, let output_string be the result
of Serializing a Dictionary (Section 4.1.2). of Serializing a Dictionary (Section 4.1.2).
3. Else if the structure is a list, let output_string be the result 3. Else if the structure is a list, let output_string be the result
of Serializing a List (Section 4.1.1). of Serializing a List (Section 4.1.1).
skipping to change at page 12, line 37 skipping to change at page 12, line 37
of Serializing an Item (Section 4.1.3). of Serializing an Item (Section 4.1.3).
5. Else, fail serialisation. 5. Else, fail serialisation.
6. Return output_string converted into an array of bytes, using 6. Return output_string converted into an array of bytes, using
ASCII encoding [RFC0020]. ASCII encoding [RFC0020].
4.1.1. Serializing a List 4.1.1. Serializing a List
Given a list of (member-value, parameters) as input_list, return an Given a list of (member-value, parameters) as input_list, return an
ASCII string suitable for use in a textual HTTP header value. ASCII string suitable for use in a HTTP header value.
1. Let output be an empty string. 1. Let output be an empty string.
2. For each (member-value, parameters) of input_list: 2. For each (member-value, parameters) of input_list:
1. If member-value is an array, append the result of applying 1. If member-value is an array, append the result of applying
Serialising an Inner List (Section 4.1.1.1) with member-value Serialising an Inner List (Section 4.1.1.1) with member-value
to output. to output.
2. Otherwise, append the result of applying Serializing an Item 2. Otherwise, append the result of applying Serializing an Item
skipping to change at page 13, line 16 skipping to change at page 13, line 16
1. Append a COMMA to output. 1. Append a COMMA to output.
2. Append a single WS to output. 2. Append a single WS to output.
3. Return output. 3. Return output.
4.1.1.1. Serialising an Inner List 4.1.1.1. Serialising an Inner List
Given an array as inner_list, return an ASCII string suitable for use Given an array as inner_list, return an ASCII string suitable for use
in a textual HTTP header value. in a HTTP header value.
1. Let output be the string "(". 1. Let output be the string "(".
2. For each member-value of inner_list: 2. For each member-value of inner_list:
1. Append the result of applying Serializing an Item 1. Append the result of applying Serializing an Item
(Section 4.1.3) with member-value to output. (Section 4.1.3) with member-value to output.
2. If inner_list is not empty, append a single WS to output. 2. If more member-values remain in inner_list, append a single
WS to output.
3. Append ")" to output. 3. Append ")" to output.
4. Return output. 4. Return output.
4.1.1.2. Serializing Parameters 4.1.1.2. Serializing Parameters
Given an ordered dictionary as input_parameters (each member having a Given an ordered dictionary as input_parameters (each member having a
param-name and a param-value), return an ASCII string suitable for param-name and a param-value), return an ASCII string suitable for
use in a textual HTTP header value. use in a HTTP header value.
1. Let output be an empty string. 1. Let output be an empty string.
2. For each parameter-name with a value of param-value in 2. For each parameter-name with a value of param-value in
input_parameters: input_parameters:
1. Append ";" to output. 1. Append ";" to output.
2. Append the result of applying Serializing a Key 2. Append the result of applying Serializing a Key
(Section 4.1.1.3) with param-name to output. (Section 4.1.1.3) with param-name to output.
skipping to change at page 14, line 10 skipping to change at page 14, line 13
1. Append "=" to output. 1. Append "=" to output.
2. Append the result of applying Serializing an Item 2. Append the result of applying Serializing an Item
(Section 4.1.3) with param-value to output. (Section 4.1.3) with param-value to output.
3. Return output. 3. Return output.
4.1.1.3. Serializing a Key 4.1.1.3. Serializing a Key
Given a key as input_key, return an ASCII string suitable for use in Given a key as input_key, return an ASCII string suitable for use in
a textual HTTP header value. a HTTP header value.
1. If input_key is not a sequence of characters, or contains 1. If input_key is not a sequence of characters, or contains
characters not in lcalpha, DIGIT, "*", "_", or "-", fail characters not in lcalpha, DIGIT, "*", "_", or "-", fail
serialisation. serialisation.
2. Let output be an empty string. 2. Let output be an empty string.
3. Append input_key to output. 3. Append input_key to output.
4. Return output. 4. Return output.
4.1.2. Serializing a Dictionary 4.1.2. Serializing a Dictionary
Given an ordered dictionary as input_dictionary (each member having a Given an ordered dictionary as input_dictionary (each member having a
member-name and a tuple value of (member-value, parameters)), return member-name and a tuple value of (member-value, parameters)), return
an ASCII string suitable for use in a textual HTTP header value. an ASCII string suitable for use in a HTTP header value.
1. Let output be an empty string. 1. Let output be an empty string.
2. For each member-name with a value of (member-value, parameters) 2. For each member-name with a value of (member-value, parameters)
in input_dictionary: in input_dictionary:
1. Append the result of applying Serializing a Key 1. Append the result of applying Serializing a Key
(Section 4.1.1.3) with member's member-name to output. (Section 4.1.1.3) with member's member-name to output.
2. Append "=" to output. 2. Append "=" to output.
skipping to change at page 15, line 10 skipping to change at page 15, line 14
1. Append a COMMA to output. 1. Append a COMMA to output.
2. Append a single WS to output. 2. Append a single WS to output.
3. Return output. 3. Return output.
4.1.3. Serializing an Item 4.1.3. Serializing an Item
Given an item as input_item, return an ASCII string suitable for use Given an item as input_item, return an ASCII string suitable for use
in a textual HTTP header value. in a HTTP header value.
1. If input_item is an integer, return the result of applying 1. If input_item is an integer, return the result of applying
Serializing an Integer (Section 4.1.4) to input_item. Serializing an Integer (Section 4.1.4) to input_item.
2. If input_item is a float, return the result of applying 2. If input_item is a float, return the result of applying
Serializing a Float (Section 4.1.5) to input_item. Serializing a Float (Section 4.1.5) to input_item.
3. If input_item is a string, return the result of applying 3. If input_item is a string, return the result of applying
Serializing a String (Section 4.1.6) to input_item. Serializing a String (Section 4.1.6) to input_item.
skipping to change at page 15, line 35 skipping to change at page 15, line 39
Serializing a Boolean (Section 4.1.9) to input_item. Serializing a Boolean (Section 4.1.9) to input_item.
6. If input_item is a byte sequence, return the result of applying 6. If input_item is a byte sequence, return the result of applying
Serializing a Byte Sequence (Section 4.1.8) to input_item. Serializing a Byte Sequence (Section 4.1.8) to input_item.
7. Otherwise, fail serialisation. 7. Otherwise, fail serialisation.
4.1.4. Serializing an Integer 4.1.4. Serializing an Integer
Given an integer as input_integer, return an ASCII string suitable Given an integer as input_integer, return an ASCII string suitable
for use in a textual HTTP header value. for use in a HTTP header value.
1. If input_integer is not an integer in the range of 1. If input_integer is not an integer in the range of
-999,999,999,999,999 to 999,999,999,999,999 inclusive, fail -999,999,999,999,999 to 999,999,999,999,999 inclusive, fail
serialisation. serialisation.
2. Let output be an empty string. 2. Let output be an empty string.
3. If input_integer is less than (but not equal to) 0, append "-" to 3. If input_integer is less than (but not equal to) 0, append "-" to
output. output.
4. Append input_integer's numeric value represented in base 10 using 4. Append input_integer's numeric value represented in base 10 using
only decimal digits to output. only decimal digits to output.
5. Return output. 5. Return output.
4.1.5. Serializing a Float 4.1.5. Serializing a Float
Given a float as input_float, return an ASCII string suitable for use Given a float as input_float, return an ASCII string suitable for use
in a textual HTTP header value. in a HTTP header value.
1. Let output be an empty string. 1. Let output be an empty string.
2. If input_float is less than (but not equal to) 0, append "-" to 2. If input_float is less than (but not equal to) 0, append "-" to
output. output.
3. Append input_float's integer component represented in base 10 3. Append input_float's integer component represented in base 10
(using only decimal digits) to output; if it is zero, append (using only decimal digits) to output; if it is zero, append
"0". "0".
skipping to change at page 16, line 41 skipping to change at page 16, line 43
9. Append at most fractional_digits_avail digits of input_float's 9. Append at most fractional_digits_avail digits of input_float's
fractional component represented in base 10 to output (using fractional component represented in base 10 to output (using
only decimal digits, and truncating any remaining digits); if it only decimal digits, and truncating any remaining digits); if it
is zero, append "0". is zero, append "0".
10. Return output. 10. Return output.
4.1.6. Serializing a String 4.1.6. Serializing a String
Given a string as input_string, return an ASCII string suitable for Given a string as input_string, return an ASCII string suitable for
use in a textual HTTP header value. use in a HTTP header value.
1. If input_string is not a sequence of characters, or contains 1. If input_string is not a sequence of characters, or contains
characters outside the range %x00-1f or %x7f (i.e., is not in characters in the range %x00-1f or %x7f (i.e., is not in VCHAR or
VCHAR or SP), fail serialisation. SP), 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_string: 4. For each character char in input_string:
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. 2. Append char to output.
5. Append DQUOTE to output. 5. Append DQUOTE to output.
6. Return output. 6. Return output.
4.1.7. Serializing a Token 4.1.7. Serializing a Token
Given a token as input_token, return an ASCII string suitable for use Given a token as input_token, return an ASCII string suitable for use
in a textual HTTP header value. in a HTTP header value.
1. If input_token is not a sequence of characters, or contains 1. If input_token is not a sequence of characters, or contains
characters not in ALPHA, DIGIT, "_", "-", ".", ":", "%", "*" or characters not in ALPHA, DIGIT, "_", "-", ".", ":", "%", "*" or
"/", fail serialisation. "/", fail serialisation.
2. Let output be an empty string. 2. Let output be an empty string.
3. Append input_token to output. 3. Append input_token to output.
4. Return output. 4. Return output.
4.1.8. Serializing a Byte Sequence 4.1.8. Serializing a Byte Sequence
Given a byte sequence as input_bytes, return an ASCII string suitable Given a byte sequence as input_bytes, return an ASCII string suitable
for use in a textual HTTP header value. for use in a HTTP header value.
1. If input_bytes is not a sequence of bytes, fail serialisation. 1. If input_bytes is not a sequence of bytes, fail serialisation.
2. Let output be an empty string. 2. Let output be an empty string.
3. Append "*" to output. 3. Append "*" to output.
4. Append the result of base64-encoding input_bytes as per 4. Append the result of base64-encoding input_bytes as per
[RFC4648], Section 4, taking account of the requirements below. [RFC4648], Section 4, taking account of the requirements below.
skipping to change at page 18, line 12 skipping to change at page 18, line 12
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. Section 3.2.
Likewise, encoded data SHOULD have pad bits set to zero, as per 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 [RFC4648], Section 3.5, unless it is not possible to do so due to
implementation constraints. implementation constraints.
4.1.9. Serializing a Boolean 4.1.9. Serializing a Boolean
Given a Boolean as input_boolean, return an ASCII string suitable for Given a Boolean as input_boolean, return an ASCII string suitable for
use in a textual HTTP header value. use in a HTTP header value.
1. If input_boolean is not a boolean, fail serialisation. 1. If input_boolean is not a boolean, fail serialisation.
2. Let output be an empty string. 2. Let output be an empty string.
3. Append "?" to output. 3. Append "?" to output.
4. If input_boolean is true, append "1" to output. 4. If input_boolean is true, append "1" to output.
5. If input_boolean is false, append "0" to output. 5. If input_boolean is false, append "0" to output.
6. Return output. 6. Return output.
4.2. Parsing Header Fields into Structured Headers 4.2. Parsing Header Fields into Structured Headers
When a receiving implementation parses textual HTTP header fields When a receiving implementation parses HTTP header fields that are
that are known to be Structured Headers, it is important that care be known to be Structured Headers, it is important that care be taken,
taken, as there are a number of edge cases that can cause as there are a number of edge cases that can cause interoperability
interoperability or even security problems. This section specifies or even security problems. This section specifies the algorithm for
the algorithm for doing so. doing so.
Given an array of bytes input_bytes that represents the chosen Given an array of bytes input_bytes that represents the chosen
header's field-value (which is an empty string if that header is not header's field-value (which is an empty string if that header is not
present), and header_type (one of "dictionary", "list", or "item"), present), and header_type (one of "dictionary", "list", or "item"),
return the parsed header value. return the parsed header value.
1. Convert input_bytes into an ASCII string input_string; if 1. Convert input_bytes into an ASCII string input_string; if
conversion fails, fail parsing. conversion fails, fail parsing.
2. Discard any leading OWS from input_string. 2. Discard any leading OWS from input_string.
skipping to change at page 28, line 31 skipping to change at page 28, line 31
RFC 7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<https://www.rfc-editor.org/info/rfc7230>. <https://www.rfc-editor.org/info/rfc7230>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
7.2. Informative References 7.2. Informative References
[IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic",
IEEE 754-2008, DOI 10.1109/IEEESTD.2008.4610935, IEEE 754-2019, DOI 10.1109/IEEESTD.2019.8766229,
ISBN 978-0-7381-5752-8, August 2008, ISBN 978-1-5044-5924-2, July 2019,
<http://ieeexplore.ieee.org/document/4610935/>. <https://ieeexplore.ieee.org/document/8766229>.
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, [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
DOI 10.17487/RFC7493, March 2015, DOI 10.17487/RFC7493, March 2015,
<https://www.rfc-editor.org/info/rfc7493>. <https://www.rfc-editor.org/info/rfc7493>.
skipping to change at page 29, line 14 skipping to change at page 29, line 10
[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 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
[UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <http://www.rfc-editor.org/info/std63>.
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
skipping to change at page 31, line 15 skipping to change at page 31, line 15
Appendix C. Implementation Notes Appendix C. Implementation Notes
A generic implementation of this specification should expose the top- A generic implementation of this specification should expose the top-
level parse (Section 4.2) and serialize (Section 4.1) functions. level parse (Section 4.2) and serialize (Section 4.1) functions.
They need not be functions; for example, it could be implemented as They need not be functions; for example, it could be implemented as
an object, with methods for each of the different top-level types. an object, with methods for each of the different top-level types.
For interoperability, it's important that generic implementations be For interoperability, it's important that generic implementations be
complete and follow the algorithms closely; see Section 1.1. To aid complete and follow the algorithms closely; see Section 1.1. To aid
this, a common test suite is being maintained by the community at this, a common test suite is being maintained by the community at
https://github.com/httpwg/structured-header-tests [7]. https://github.com/httpwg/structured-header-tests [6].
Implementers should note that dictionaries and parameters are order- Implementers should note that dictionaries and parameters are order-
preserving maps. Some headers may not convey meaning in the ordering preserving maps. Some headers may not convey meaning in the ordering
of these data types, but it should still be exposed so that of these data types, but it should still be exposed so that
applications which need to use it will have it available. applications which need to use it will have it available.
Likewise, implementations should note that it's important to preserve Likewise, implementations should note that it's important to preserve
the distinction between tokens and strings. While most programming the distinction between tokens and strings. While most programming
languages have native types that map to the other types well, it may languages have native types that map to the other types well, it may
be necessary to create a wrapper "token" object or use a parameter on be necessary to create a wrapper "token" object or use a parameter on
functions to assure that these types remain separate. functions to assure that these types remain separate.
Appendix D. Changes Appendix D. Changes
_RFC Editor: Please remove this section before publication._ _RFC Editor: Please remove this section before publication._
D.1. Since draft-ietf-httpbis-header-structure-12 D.1. Since draft-ietf-httpbis-header-structure-13
o Editorial improvements.
o Define "structured header name" and "structured header value"
terms (#908).
o Corrected text about valid characters in strings (#931).
o Removed most instances of the word "textual", as it was redundant
(#915).
D.2. Since draft-ietf-httpbis-header-structure-12
o Editorial improvements. o Editorial improvements.
o Reworked float serialisation (#896). o Reworked float serialisation (#896).
D.2. Since draft-ietf-httpbis-header-structure-11 o Don't add a trailing space in inner-list (#904).
D.3. Since draft-ietf-httpbis-header-structure-11
o Allow * in key (#844). o Allow * in key (#844).
o Constrain floats to six digits of precision (#848). o Constrain floats to six digits of precision (#848).
o Allow dictionary members to have parameters (#842). o Allow dictionary members to have parameters (#842).
D.3. Since draft-ietf-httpbis-header-structure-10 D.4. Since draft-ietf-httpbis-header-structure-10
o Update abstract (#799). o Update abstract (#799).
o Input and output are now arrays of bytes (#662). o Input and output are now arrays of bytes (#662).
o Implementations need to preserve difference between token and o Implementations need to preserve difference between token and
string (#790). string (#790).
o Allow empty dictionaries and lists (#781). o Allow empty dictionaries and lists (#781).
o Change parameterized lists to have primary items (#797). o Change parameterized lists to have primary items (#797).
o Allow inner lists in both dictionaries and lists; removes lists of o Allow inner lists in both dictionaries and lists; removes lists of
lists (#816). lists (#816).
o Subsume Parameterised Lists into Lists (#839). o Subsume Parameterised Lists into Lists (#839).
D.4. Since draft-ietf-httpbis-header-structure-09 D.5. Since draft-ietf-httpbis-header-structure-09
o Changed Boolean from T/F to 1/0 (#784). o Changed Boolean from T/F to 1/0 (#784).
o Parameters are now ordered maps (#765). o Parameters are now ordered maps (#765).
o Clamp integers to 15 digits (#737). o Clamp integers to 15 digits (#737).
D.5. Since draft-ietf-httpbis-header-structure-08 D.6. Since draft-ietf-httpbis-header-structure-08
o Disallow whitespace before items properly (#703). o Disallow whitespace before items properly (#703).
o Created "key" for use in dictionaries and parameters, rather than o Created "key" for use in dictionaries and parameters, rather than
relying on identifier (#702). Identifiers have a separate minimum relying on identifier (#702). Identifiers have a separate minimum
supported size. supported size.
o Expanded the range of special characters allowed in identifier to o Expanded the range of special characters allowed in identifier to
include all of ALPHA, ".", ":", and "%" (#702). include all of ALPHA, ".", ":", and "%" (#702).
skipping to change at page 33, line 5 skipping to change at page 33, line 14
o Gave better names for referring specs to use in Parameterised o Gave better names for referring specs to use in Parameterised
Lists (#720). Lists (#720).
o Added Lists of Lists (#721). o Added Lists of Lists (#721).
o Rename Identifier to Token (#725). o Rename Identifier to Token (#725).
o Add implementation guidance (#727). o Add implementation guidance (#727).
D.6. Since draft-ietf-httpbis-header-structure-07 D.7. Since draft-ietf-httpbis-header-structure-07
o Make Dictionaries ordered mappings (#659). o Make Dictionaries ordered mappings (#659).
o Changed "binary content" to "byte sequence" to align with Infra o Changed "binary content" to "byte sequence" to align with Infra
specification (#671). specification (#671).
o Changed "mapping" to "map" for #671. o Changed "mapping" to "map" for #671.
o Don't fail if byte sequences aren't "=" padded (#658). o Don't fail if byte sequences aren't "=" padded (#658).
o Add Booleans (#683). o Add Booleans (#683).
o Allow identifiers in items again (#629). o Allow identifiers in items again (#629).
o Disallowed whitespace before items (#703). o Disallowed whitespace before items (#703).
o Explain the consequences of splitting a string across multiple o Explain the consequences of splitting a string across multiple
headers (#686). headers (#686).
D.7. Since draft-ietf-httpbis-header-structure-06 D.8. Since draft-ietf-httpbis-header-structure-06
o Add a FAQ. o Add a FAQ.
o Allow non-zero pad bits. o Allow non-zero pad bits.
o Explicitly check for integers that violate constraints. o Explicitly check for integers that violate constraints.
D.8. Since draft-ietf-httpbis-header-structure-05 D.9. 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.
D.9. Since draft-ietf-httpbis-header-structure-04 D.10. 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.
D.10. Since draft-ietf-httpbis-header-structure-03 D.11. Since draft-ietf-httpbis-header-structure-03
o Strengthen language around failure handling. o Strengthen language around failure handling.
D.11. Since draft-ietf-httpbis-header-structure-02 D.12. 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.
D.12. Since draft-ietf-httpbis-header-structure-01 D.13. Since draft-ietf-httpbis-header-structure-01
o Replaced with draft-nottingham-structured-headers. o Replaced with draft-nottingham-structured-headers.
D.13. Since draft-ietf-httpbis-header-structure-00 D.14. 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. 67 change blocks. 
115 lines changed or deleted 136 lines changed or added

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