This section defines the abstract types for Structured Fields. The ABNF provided represents the on-wire format in HTTP field values.
There are three top-level types that an HTTP field can be defined as: Lists, Dictionaries, and Items.
Lists and Dictionaries are containers; their members can be Items or Inner Lists (which are themselves arrays of Items).
Both Items and Inner Lists can be Parameterized with key/value pairs.
Lists are arrays of zero or more members, each of which can be an Item (Section 3.3
) or an Inner List (Section 3.1.1
), both of which can be Parameterized (Section 3.1.2
The ABNF for Lists in HTTP fields is:
sf-list = list-member *( OWS "," OWS list-member )
list-member = sf-item / inner-list
Each member is separated by a comma and optional whitespace. For example, a field whose value is defined as a List of Tokens could look like:
Example-List: sugar, tea, rum
An empty List is denoted by not serializing the field at all. This implies that fields defined as Lists have a default empty value.
Note that Lists can have their members split across multiple lines of the same header or trailer section, as per Section 3.2.2
of RFC 7230
; for example, the following are equivalent:
Example-List: sugar, tea, rum
Example-List: sugar, tea
However, individual members of a List cannot be safely split between lines; see Section 4.2
support Lists containing at least 1024 members. Field specifications can constrain the types and cardinality of individual List values as they require.
An Inner List is an array of zero or more Items (Section 3.3
). Both the individual Items and the Inner List itself can be Parameterized (Section 3.1.2
The ABNF for Inner Lists is:
inner-list = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")"
Inner Lists are denoted by surrounding parenthesis, and their values are delimited by one or more spaces. A field whose value is defined as a List of Inner Lists of Strings could look like:
Example-List: ("foo" "bar"), ("baz"), ("bat" "one"), ()
Note that the last member in this example is an empty Inner List.
A header field whose value is defined as a List of Inner Lists with Parameters at both levels could look like:
Example-List: ("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1
support Inner Lists containing at least 256 members. Field specifications can constrain the types and cardinality of individual Inner List members as they require.
Parameters are an ordered map of key-value pairs that are associated with an Item (Section 3.3
) or Inner List (Section 3.1.1
). The keys are unique within the scope of the Parameters they occur within, and the values are bare items (i.e., they themselves cannot be parameterized; see Section 3.3
provide access to Parameters both by index and by key. Specifications MAY
use either means of accessing them.
The ABNF for Parameters is:
parameters = *( ";" *SP parameter )
parameter = param-key [ "=" param-value ]
param-key = key
key = ( lcalpha / "*" )
*( lcalpha / DIGIT / "_" / "-" / "." / "*" )
lcalpha = %x61-7A ; a-z
param-value = bare-item
Note that parameters are ordered as serialized, and parameter keys cannot contain uppercase letters. A parameter is separated from its Item or Inner List and other parameters by a semicolon. For example:
Example-List: abc;a=1;b=2; cde_456, (ghi;jk=4 l);q="9";r=w
Parameters whose value is Boolean (see Section 3.3.6
) true MUST
omit that value when serialized. For example, the "a" parameter here is true, while the "b" parameter is false:
Example-Integer: 1; a; b=?0
Note that this requirement is only on serialization; parsers are still required to correctly handle the true value when it appears in a parameter.
support at least 256 parameters on an Item or Inner List, and support parameter keys with at least 64 characters. Field specifications can constrain the order of individual parameters, as well as their values' types as required.
Dictionaries are ordered maps of key-value pairs, where the keys are short textual strings and the values are Items (Section 3.3
) or arrays of Items, both of which can be Parameterized (Section 3.1.2
). There can be zero or more members, and their keys are unique in the scope of the Dictionary they occur within.
provide access to Dictionaries both by index and by key. Specifications MAY
use either means of accessing the members.
The ABNF for Dictionaries is:
sf-dictionary = dict-member *( OWS "," OWS dict-member )
dict-member = member-key ( parameters / ( "=" member-value ))
member-key = key
member-value = sf-item / inner-list
Members are ordered as serialized and separated by a comma with optional whitespace. Member keys cannot contain uppercase characters. Keys and values are separated by "=" (without whitespace). For example:
Example-Dict: en="Applepie", da=:w4ZibGV0w6ZydGU=:
Note that in this example, the final "=" is due to the inclusion of a Byte Sequence; see Section 3.3.5
Members whose value is Boolean (see Section 3.3.6
) true MUST
omit that value when serialized. For example, here both "b" and "c" are true:
Example-Dict: a=?0, b, c; foo=bar
Note that this requirement is only on serialization; parsers are still required to correctly handle the true Boolean value when it appears in Dictionary values.
A Dictionary with a member whose value is an Inner List of Tokens:
Example-Dict: rating=1.5, feelings=(joy sadness)
A Dictionary with a mix of Items and Inner Lists, some with parameters:
Example-Dict: a=(1 2), b=3, c=4;aa=bb, d=(5 6);valid
As with Lists, an empty Dictionary is represented by omitting the entire field. This implies that fields defined as Dictionaries have a default empty value.
Typically, a field specification will define the semantics of Dictionaries by specifying the allowed type(s) for individual members by their keys, as well as whether their presence is required or optional. Recipients MUST
ignore members whose keys that are undefined or unknown, unless the field's specification specifically disallows them.
Note that Dictionaries can have their members split across multiple lines of the same header or trailer section; for example, the following are equivalent:
Example-Dict: foo=1, bar=2
However, individual members of a Dictionary cannot be safely split between lines; see Section 4.2
support Dictionaries containing at least 1024 key/value pairs and keys with at least 64 characters. Field specifications can constrain the order of individual Dictionary members, as well as their values' types as required.
An Item can be an Integer (Section 3.3.1
), a Decimal (Section 3.3.2
), a String (Section 3.3.3
), a Token (Section 3.3.4
), a Byte Sequence (Section 3.3.5
), or a Boolean (Section 3.3.6
). It can have associated parameters (Section 3.1.2
The ABNF for Items is:
sf-item = bare-item parameters
bare-item = sf-integer / sf-decimal / sf-string / sf-token
/ sf-binary / sf-boolean
For example, a header field that is defined to be an Item that is an Integer might look like:
or with parameters:
Example-Integer: 5; foo=bar
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 compatibility [IEEE754
The ABNF for Integers is:
sf-integer = ["-"] 1*15DIGIT
Integers larger than 15 digits can be supported in a variety of ways; for example, by using a String (Section 3.3.3
), a Byte Sequence (Section 3.3.5
), or a parameter on an Integer that acts as a scaling factor.
While it is possible to serialize Integers with leading zeros (e.g., "0002", "-01") and signed zero ("-0"), these distinctions may not be preserved by implementations.
Note that commas in Integers are used in this section's prose only for readability; they are not valid in the wire format.
Decimals are numbers with an integer and a fractional component. The integer component has at most 12 digits; the fractional component has at most three digits.
The ABNF for decimals is:
sf-decimal = ["-"] 1*12DIGIT "." 1*3DIGIT
For example, a header whose value is defined as a Decimal could look like:
While it is possible to serialize Decimals with leading zeros (e.g., "0002.5", "-01.334"), trailing zeros (e.g., "5.230", "-0.40"), and signed zero (e.g., "-0.0"), these distinctions may not be preserved by implementations.
Note that the serialization algorithm (Section 4.1.5
) rounds input with more than three digits of precision in the fractional component. If an alternative rounding strategy is desired, this should be specified by the header definition to occur before serialization.
Strings are zero or more printable ASCII [RFC 0020
] characters (i.e., the range %x20 to %x7E). Note that this excludes tabs, newlines, carriage returns, etc.
The ABNF for Strings is:
sf-string = DQUOTE *chr DQUOTE
chr = unescaped / escaped
unescaped = %x20-21 / %x23-5B / %x5D-7E
escaped = "\" ( DQUOTE / "\" )
Strings are delimited with double quotes, using a backslash ("\") to escape double quotes and backslashes. For example:
Example-String: "hello world"
Note that Strings only use DQUOTE as a delimiter; single quotes do not delimit Strings. Furthermore, only DQUOTE and "\" can be escaped; other characters after "\" MUST
cause parsing to fail.
Unicode is not directly supported in Strings, because it causes a number of interoperability issues, and -- with few exceptions -- field values do not require it.
When it is necessary for a field value to convey non-ASCII content, a Byte Sequence (Section 3.3.5
) can be specified, along with a character encoding (preferably UTF-8 [STD63
support Strings (after any decoding) with at least 1024 characters.
Tokens are short textual words; their abstract model is identical to their expression in the HTTP field value serialization.
The ABNF for Tokens is:
sf-token = ( ALPHA / "*" ) *( tchar / ":" / "/" )
support Tokens with at least 512 characters.
Note that Token allows the same characters as the "token" ABNF rule defined in [RFC 7230
], with the exceptions that the first character is required to be either ALPHA or "*", and ":" and "/" are also allowed in subsequent characters.
Byte Sequences can be conveyed in Structured Fields.
The ABNF for a Byte Sequence is:
sf-binary = ":" *(base64) ":"
base64 = ALPHA / DIGIT / "+" / "/" / "="
A Byte Sequence is delimited with colons and encoded using base64 (RFC 4648
, Section 4
). For example:
support Byte Sequences with at least 16384 octets after decoding.
Boolean values can be conveyed in Structured Fields.
The ABNF for a Boolean is:
sf-boolean = "?" boolean
boolean = "0" / "1"
A Boolean is indicated with a leading "?" character followed by a "1" for a true value or "0" for false. For example:
Note that in Dictionary (Section 3.2
) and Parameter (Section 3.1.2
) values, Boolean true is indicated by omitting the value.