Structured Field Values for HTTP

JSON was rejected as the basis for Structured Fields because it has unresolved specification issues around large numbers and duplicate object keys, uses Unicode strings by default (causing interoperability issues), and allows unlimited nesting depth. Because JSON is so broadly adopted, it is not feasible to impose the additional constraints needed for HTTP header use across all implementations.

http, json

Strict parsing and serialization are intentional features: the only error handling defined is to fail the operation altogether. Being more tolerant of input would create pressure on other implementations to implement similar but subtly different workarounds, harming interoperability and potentially introducing security issues.

http, security

Structured Fields abstract model is designed so that future HTTP versions can define alternative serializations (e.g., binary) that transmit the same abstract model more efficiently without requiring field redefinition. The format described in this document is the canonical text serialization for HTTP/1.1 and HTTP/2.

http

Unicode is not directly supported in Strings because it causes interoperability issues (e.g., in comparison) and most HTTP field values do not require it. When non-ASCII content is needed, a Byte Sequence with an explicit character encoding (preferably UTF-8) should be used instead.

http

Implementations must preserve the distinction between Tokens and Strings, and must expose the ordering of Dictionaries and Parameters even if the field definition does not convey meaning in the ordering, so that applications requiring it can access it.

http

Strings split across multiple HTTP field lines will have unpredictable results because concatenation inserts one or more commas (with optional whitespace) into the string. Tokens, Integers, Decimals, and Byte Sequences cannot be split across field lines because the inserted commas will cause parsing to fail.

http

This specification is only intended for use with new HTTP fields that explicitly opt into it; it does not redefine the syntax of existing HTTP fields. Field definitions cannot relax the requirements of this specification, only add additional constraints.

http

Base64-encoded Byte Sequences MUST use '=' padding as per RFC 4648 Section 3.2. Parsers MUST fail on characters outside the base64 alphabet and on line feeds in encoded data; they SHOULD NOT fail on missing padding or non-zero pad bits.

http

Boolean true MUST omit its value when serialized as a Parameter value or Dictionary member value (i.e., the key appears without '=' and a value). Parsers are still required to correctly handle the explicit true value ('?1') when it appears.

http

Field specifications are discouraged from treating unrecognized Parameters as errors, in order to preserve forward compatibility. A specification may stipulate that 'grease' parameters be sent to prevent recipients from writing parsers that ignore Parameters entirely.

http

For serialization, implementations MAY vary from the specified algorithm so long as the output is still correctly handled by the parsing algorithm. This allows flexibility in serializers while requiring strict conformance in parsers.

http

If parsing fails at any point — including when calling a sub-algorithm — the entire field value MUST be ignored (treated as if the field were not present). This requirement cannot be loosened by specifications that reference this document.

http, security

Recipients MUST ignore Dictionary members whose keys are undefined or unknown, unless the field's specification specifically disallows them. This enables forward-compatible extension of Dictionary-based fields.

http

When generating the input to the parsing algorithm, parsers MUST combine all field lines in the same section that case-insensitively match the field name into one comma-separated field-value, as per RFC 7230 Section 3.2.2.

http

When parsing from HTTP fields, implementations MUST have behavior that is indistinguishable from following the specified parsing algorithms. If there is disagreement between the parsing algorithms and ABNF, the algorithms take precedence.

http

A Dictionary is an ordered map of key/value pairs where keys are short lowercase strings and values are Items or Inner Lists (optionally parameterized). Implementations MUST provide access by both index and key. Parsers MUST support at least 1024 key/value pairs and keys with at least 64 characters.

http

A List is an array of zero or more members (Items or Inner Lists), comma-separated with optional whitespace. An empty List is represented by omitting the field entirely. Parsers MUST support Lists containing at least 1024 members.

http

An Inner List is an array of zero or more Items delimited by parentheses, with items separated by one or more spaces. Both the Inner List itself and its individual Items can carry Parameters. Parsers MUST support Inner Lists with at least 256 members.

http

Parameters are an ordered map of key/value pairs associated with an Item or Inner List; keys are unique, lowercase-only strings, and values are bare items (non-parameterizable). Implementations MUST provide access to Parameters by both index and key. Parsers MUST support at least 256 parameters and keys of at least 64 characters.

http

Structured Fields have three top-level types: List, Dictionary, and Item. Lists and Dictionaries are containers whose members can be Items or Inner Lists; both Items and Inner Lists can be Parameterized with key/value pairs.

http

Parties with the ability to inject new HTTP fields may change the meaning of a Structured Field. In some circumstances this will cause parsing to fail, but it is not possible to reliably detect all such tampering via parsing failure alone.

http, security

The sizes of most Structured Field types are not limited by this specification; extremely large field values could be used as an attack vector for resource consumption. Most HTTP implementations should impose limits on individual field sizes and total header/trailer section size to mitigate such attacks.

http, security

Boolean (sf-boolean): a '?' character followed by '1' (true) or '0' (false). In Dictionary member values and Parameter values, Boolean true is indicated by omitting the value entirely on serialization.

http

Byte Sequence (sf-binary): colon-delimited standard base64 encoding per RFC 4648 Section 4. Serializers MUST use '=' padding and SHOULD set pad bits to zero. Parsers SHOULD NOT fail on missing '=' padding or non-zero pad bits for compatibility with common base64 implementations.

http

Decimal (sf-decimal): integer component of at most 12 digits, fractional component of at most 3 digits, encoded as optional '-', integer digits, '.', and fractional digits. The serializer rounds to 3 fractional places using round-half-to-even.

http

Integer (sf-integer): signed, up to 15 decimal digits, range -999,999,999,999,999 to 999,999,999,999,999, encoded as optional leading '-' followed by 1–15 ASCII digits. Range chosen for IEEE 754 compatibility.

http

String (sf-string): zero or more printable ASCII characters (%x20–%x7E) delimited by DQUOTE; only DQUOTE and backslash may be backslash-escaped. Unicode is not supported. Parsers MUST support strings of at least 1024 characters.

http

Token (sf-token): a short textual word whose first character must be ALPHA or '*', followed by tchar, ':', or '/' characters. Parsers MUST support Tokens of at least 512 characters.

http