Structured Field Values for HTTP
obsoletes
- rfc-8941 — Structured Field Values for HTTP
Extracted elements (26)
Because a field definition must reference a specific RFC for Structured Fields, the Date and Display String types added in RFC 9651 are unavailable to fields whose definitions reference RFC 8941. Upgrading a parser from RFC 8941 to RFC 9651 may cause previously-rejected field values (e.g., syntactically valid Dates) to be accepted, which could affect field-specific logic.
JSON was considered and rejected for Structured Fields because it has underspecified behavior for large numbers and duplicate object keys, Unicode string interoperability issues, and arbitrary nesting depth — all of which would require additional constraints that existing JSON parsers would not enforce, harming interoperability. The goal of a dedicated parser/serializer was to make non-conformance visible and correctible.
Parameters are the primary extensibility mechanism for Items and Inner Lists, allowing field specifications to add information later without breaking parsers. Field specifications are discouraged from treating unrecognized parameters as errors, and Dictionary-based fields should ignore unknown keys to enable forward compatibility.
Strict, step-by-step parsing and serialization algorithms are intentional: the only error handling defined is to fail the entire operation. Leniency would create pressure on other implementations to add subtly different workarounds, creating interoperability and security problems; strict processing lets producers discover and correct non-conformant output early.
RFC 9651 is designed to be backward compatible with RFC 8941: a parser implementing RFC 9651 can also parse valid Structured Fields whose definitions reference RFC 8941. However, upgrading from RFC 8941 to RFC 9651 may cause previously-invalid field values (e.g., those containing Date or Display String syntax) to be accepted, potentially affecting field-specific logic.
Display Strings are NOT RECOMMENDED for use in situations where a String or Token would be adequate, because Unicode has processing considerations (e.g., normalization) and security considerations (e.g., homograph attacks) that make it more difficult to handle correctly.
If parsing fails, either the entire field value MUST be ignored (treated as if the field is not present) or the complete HTTP message MUST be treated as malformed. Field specifications that use Structured Fields are not allowed to loosen this requirement.
Parsers MUST combine all field lines in the same section that case-insensitively match the field name into one comma-separated field-value before parsing, per HTTP Section 5.2. Individual members of Lists and Dictionaries cannot be safely split across multiple field lines; Strings split across lines will have unpredictable results.
Parsers MUST support Lists and Dictionaries containing at least 1024 members/key-value pairs, Inner Lists with at least 256 members, at least 256 Parameters on an Item or Inner List, and Parameter/Dictionary keys with at least 64 characters.
When parsing HTTP fields, implementations MUST have behavior indistinguishable from following the specified step-by-step algorithms. For serialization, implementations MAY vary from the specified algorithms so long as the output is correctly handled by the specified parsing algorithm.
When serializing Byte Sequences, encoded data SHOULD have pad bits set to zero per RFC 4648 Section 3.5, unless not possible due to implementation constraints. '=' padding is required.
Decimals have an integer component of at most 12 digits and a fractional component of at most 3 digits. The serialization algorithm rounds input with more than three fractional digits to the nearest value (or even value if equidistant); field definitions requiring a different rounding strategy must specify it before serialization.
Dictionaries are ordered maps of key/value pairs where keys follow the same syntax as Parameter keys and values are Items or Inner Lists (both optionally parameterized). Duplicate keys result in all but the last instance being ignored. Recipients MUST ignore members with undefined or unknown keys unless the field specification explicitly disallows them.
Integers have a range of -999,999,999,999,999 to 999,999,999,999,999 inclusive (up to fifteen digits, signed), chosen for IEEE 754 compatibility. Leading zeros and signed zero are valid to serialize but may not be preserved by implementations.
Parameters are an ordered map of key/value pairs attached to an Item or Inner List, separated by semicolons. Keys must begin with a lowercase letter or '*' and contain only lcalpha, DIGIT, '_', '-', '.', or '*'. Keys are unique per scope; duplicate keys overwrite earlier entries. Implementations MUST provide access both by index and by key.
Strings consist of zero or more printable ASCII characters (range %x20 to %x7E) delimited by double quotes, with backslash escaping for '"' and '\'. Non-ASCII characters are not supported; use Display Strings for Unicode content. Parsers MUST support at least 1024 characters after decoding.
Structured Fields define three top-level types: List (ordered array of Items or Inner Lists), Dictionary (ordered map of key/value pairs), and Item (a single typed value). Lists and Dictionaries are containers whose members may be parameterized; Items carry the primitive values.
Tokens are short textual words beginning with an alphabetic character or '*', followed by zero or more token characters (HTTP tchar plus ':' and '/'). Tokens exist largely for compatibility with existing HTTP field data models; new fields are encouraged to use Strings instead. Parsers MUST support at least 512 characters.
IANA added a new 'Structured Type' column to the 'Hypertext Transfer Protocol (HTTP) Field Name Registry', with values 'Dictionary', 'List', or 'Item'. Existing entries for Accept-CH, Cache-Status, CDN-Cache-Control, Cross-Origin-* Policy fields, Origin-Agent-Cluster, Priority, and Proxy-Status were annotated with their respective structured types.
Parties able to inject new HTTP fields can change the meaning of a Structured Field; while this may cause parsing to fail in some cases, it is not possible to reliably detect all such tampering.
The Display String type can convey any Unicode code point without sanitization, including unassigned code points, control characters (including NUL), and noncharacters. Applications consuming Display Strings MUST consider filtering or escaping untrusted content before displaying it; see PRECIS and Unicode Security Considerations.
The size of most Structured Field types is not limited by this specification; extremely large field values could be an attack vector for resource consumption. HTTP implementations should limit sizes of individual fields and overall header/trailer sections to mitigate such attacks.
Booleans are serialized as '?1' (true) or '?0' (false). In Dictionary values and Parameters, Boolean true is indicated by omitting the value entirely (key only); parsers must still correctly handle an explicit true value ('?1') in these positions.
Byte Sequences are delimited by colons (':') and encoded using standard base64 (RFC 4648 Section 4) with required '=' padding. Parsers SHOULD NOT fail on missing padding or non-zero pad bits due to implementation variation, but MUST fail on characters outside the base64 alphabet or line feeds. Parsers MUST support at least 16384 octets after decoding.
Dates are serialized with a leading '@' followed by an integer representing a (possibly negative) delta in seconds from 1970-01-01T00:00:00Z excluding leap seconds, identical in encoding to Integers. Parsers MUST support all days in years 1–9999 (-62,135,596,800 to 253,402,214,400 delta seconds).
Display Strings are serialized with a leading '%' followed by a double-quoted string where non-ASCII bytes (and '%' and '"') are percent-encoded as lowercase hex pairs. The encoding applies UTF-8 first; surrogate code points (U+D800–U+DFFF) cause serialization to fail. Parsers decode the percent-encoded bytes and then UTF-8 decode the result.