Binary Structured HTTP Field Values

1.1. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

This specification describes wire formats using the convention described in Section 1.3 of [QUIC].¶

2.1. Literal Values

A Literal Value is a special type that carries the string value of a field; they are used to carry field values that are not structured using the data types defined in Section 3 of [STRUCTURED-FIELDS]. This might be because the field is not recognised as a Structured Field, or it might be because a field that is understood to be a Structured Field cannot be parsed successfully as one.¶

A literal value's payload consists of an integer Length field (using the variable-length encoding from Section 16 of [QUIC]), followed by that many octets of the field value. They are functionally equivalent to String Literal Representations in Section 5.2 of [RFC7541].¶

Literal Value {
  Type (5) = 0,
  Unused Flags (3) = 0,
  Length (i),
  Payload (..)
}

2.2. Lists

A List (Section 3.1 of [STRUCTURED-FIELDS]) uses its Flags to carry a Short Member Count as three bits.¶

If the Short Member Count is zero, it indicates that the next byte is the Member Count, represented using the variable-length encoding from Section 16 of [QUIC]. Otherwise, it indicates the Member Count itself. This allows a small list to be encoded without using an extra byte for its length.¶

In either case, the payload indicates the number of List members that follow.¶

List {
  Type (5) = 1,
  Short Member Count (3),
  [ Member Count (i) ],
  Binary Structured Type (..) ...
}

2.3. Dictionaries

A Dictionary (Section 3.2 of [STRUCTURED-FIELDS]) uses its Flags to indicate its number of members, in a fashion similar to Lists.¶

Dictionary {
  Type (5) = 2,
  Short Member Count (3),
  [ Member Count (i) ],
  Dictionary Member (..) ...
}

Each Dictionary member is represented by a length, followed by that many bytes of the member-key, followed by the Binary Structured Type(s) representing the member-value.¶

Dictionary Member {
  Key Length (i),
  Member Key (..),
  Binary Structured Type (..),
}

A Dictionary Member MUST NOT be a Parameters (0x2).¶

2.4. Inner Lists

An Inner List (Section 3.1.1 of [STRUCTURED-FIELDS]) has a payload consisting a Member Count field (using the variable-length encoding from Section 16 of [QUIC]), followed by one or more fields representing the members of the list.¶

Inner List {
  Type (5) = 3,
  Parameters (1),
  Unused Flags (2),
  Member Count (i),
  Binary Structured Type (..) ...
  [Parameters (..)]
}

The Parameters Flag indicates whether the value is followed by Parameters (see Section 2.4.1).¶

Parameters on the Inner List itself, if present, are serialised in a following Parameter type (Section 2.4.1); they do not form part of the payload of the Inner List (and therefore are not counted in Member Count).¶

Parameters {
  Type (5) = 4,
  Short Parameter Count (3),
  [ Parameter Count (i) ],
  Parameter (..) ...
}

Parameter {
  Parameter Key Length (i),
  Parameter Key (..),
  Binary Structured Type (..)
}

Integer {
  Type (5) = 5,
  Parameters (1),
  Sign (1),
  Unused Flag (1) = 0,
  Payload (i)
}

Decimal {
  Type (5) = 6,
  Parameters (1),
  Sign (1),
  Unused Flag (1) = 0,
  Dividend (i),
  Divisor (i)
}

String {
  Type (5) = 7,
  Parameters (1),
  Unused Flags (2) = 0,
  Length (i),
  Payload (..)
}

Token {
  Type (5) = 8,
  Parameters (1),
  Unused Flags (2) = 0,
  Length (i),
  Payload (..)
}

Byte Sequence {
  Type (5) = 9,
  Parameters (1),
  Unused Flags (2) = 0,
  Length (i),
  Payload (..)
}

Boolean {
  Type (5) = 10,
  Parameters (1),
  Payload (1),
  Unused Flag (1) = 0,
}

3.1. The SETTINGS_BINARY_STRUCTURED_FIELDS Setting

Advertising support for Binary Structured Fields is accomplished using a HTTP/2 setting, SETTINGS_BINARY_STRUCTURED_FIELDS (0xTODO).¶

Receiving SETTINGS_BINARY_STRUCTURED_FIELDS with a non-zero value from a peer indicates that:¶

1. The peer supports all of the Binary Structured Types defined in Section 2.¶

2. The peer will process the BINARY_STRUCTRED HEADERS flag as defined in Section 3.2.¶

3. When passing the message to a downstream consumer (whether on the network or not) who does not support this extension or otherwise explicitly negotiate an equivalent mechanism, the peer will:¶

   1. Transform all fields defined as Mapped Fields in Section 1.3 of [RETROFIT] into their unmapped forms, removing the mapped fields.¶

   2. Serialize all fields into the appropriate form for that peer (e.g., the textual representation of Structured Fields data types defined in [STRUCTURED-FIELDS]).¶

The default value of SETTINGS_BINARY_STRUCTURED_FIELDS is 0, whereas a value of 1 indicates that this specification is supported with no further extensions. Future specifications might use values greater than one to indicate support for extensions.¶

3.2. The BINARY_STRUCTRED HEADERS Flag

When a peer has indicated that it supports this specification as per Section 3.1, a sender can send the BINARY_STRUCTURED flag (0xTODO) on the HEADERS frame.¶

This flag indicates that the HEADERS frame containing it and subsequent CONTINUATION frames on the same stream use the Binary Structured Types defined in Section 2 instead of the String Literal Representation defined in Section 5.2 of [RFC7541] to represent all field values. Field names are still serialised as String Literal Representations.¶

In such frames, all field values MUST be sent as Binary Structured Field Values. Note that this includes Binary Literals (Section 2.1) for those field values that are not recognised as Structured Fields, as well as textual values that cannot be successfully parsed as Structured Fields. Implementations MAY also send a field value as a Binary Literal even when it is possible to represent it as a Structured Field (e.g., for efficiency purposes).¶

Binary Structured Field Values are stored in the HPACK [RFC7541] dynamic table, and their lengths are used for the purposes of maintaining dynamic table size (see [RFC7541], Section 4).¶

Note that HEADERS frames with and without the BINARY_STRUCTURED flag MAY be mixed on the same connection, depending on the requirements of the sender.¶