2026-09-13 · 8 min read
- http
- headers
- interoperability
HTTP Structured Fields provide a common syntax for headers that declare themselves as dictionaries, lists, or items. Supported bare values include integers, decimals, strings, tokens, byte sequences, booleans, and dates, with parameters attached to members.
The framework does not retrofit every historical header. Each field definition chooses its top-level type and adds semantic requirements that a generic parser cannot supply.
Select grammar from the field definition
Call the parser in dictionary, list, or item mode according to the registered field specification. Reject invalid input rather than falling back to comma splitting or a different top-level type.
- Preserve keys and parameters separately.
- Apply numeric ranges and precision rules.
- Decode byte sequences only after syntax validation.
- Enforce member, nesting, and total-size limits.
Handle repeated field lines deliberately
HTTP libraries and intermediaries may expose repeated lines separately or as a combined field value. Use the field's defined combination behavior and preserve ordering where the semantics require it.
A comma inside a quoted string or the structure of an inner list cannot be handled by a generic split. Parse the complete combined field value with a compliant implementation.
Separate normalization from security protocols
A compliant serializer emits a deterministic valid representation of a parsed value, but it does not automatically reconstruct bytes received on the wire. Message-signature and cache protocols specify which derived components and transformations participate.
- Do not invent canonicalization for signatures.
- Retain raw values when a protocol requires them.
- Validate field semantics after structural parsing.
- Classify proxy transformations in compatibility tests.
Use standards test vectors
Use Flashman's URL tool for request-target fixtures, Base64 for public byte values, hash for exact fixture identity, diff for parser outputs, and timestamp converter for date-item examples.
Test repeated lines, whitespace, quoted delimiters, tokens, decimals, dates, byte sequences, booleans, duplicate dictionary keys, inner lists, parameters, invalid escapes, limits, serializer round trips, and each proxy or runtime in the path.