Support for structured-headers de/serialization

[ioggstream]

I expect

A way to express structured-fields serialization rfc8941

• https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html

Here are some examples:

Example-IntegerHeader: 42
Example-BoolHdr: ?1
Example-StringHeader: "hello world"
Example-BinaryHdr: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==:
Example-StrListHeader: "foo", "bar", "It was the best of times."
Example-DictHeader: en="Applepie", da=*w4ZibGV0w6ZydGU=*

Note

In the near future, all http headers will probably be de/serialized using structured-header specs.

[handrews]

@ioggstream JSON Schema is defined over a data model, so as long as the structured header format can be unambiguously parsed into that data model, it would make sense to just use JSON Schema for that.

@darrelmiller @webron is this something we should note or clarify for 3.0.3 and/or 3.1? I'm going to flag this under #2099 even though its pretty tangential to the JSON Schema draft update. It is related to JSON Schema stuff that we have tried to make more explicit in recent drafts.

[ioggstream]

Can define structured-headers as an alternative schema help?

[darrelmiller]

It might be worth introducing a new style value called structured-header or something like that in the future. The Schema object can describe the header value content and the style will clarify how it should be serialized. I am still not seeing very many uses of structured headers so I don't think there is an urgency. It is worth considering for 3.2.

[ioggstream]

structured-headers is still WIP, so 3.2 is fine.

OTOH it could be interesting some feedback from the OAS community to https://github.com/httpwg/http-extensions/blob/master/draft-ietf-httpbis-header-structure.md

[Budda0ne]

I expect

A way to express structured-headers serialization

• https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html

Here are some examples:

Example-IntegerHeader: 42

Example-BoolHdr: ?1

Example-StringHeader: "hello world"

Example-BinaryHdr: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==:

Example-StrListHeader: "foo", "bar", "It was the best of times."

Example-DictHeader: en="Applepie", da=*w4ZibGV0w6ZydGU=*

Note

In the near future, all http headers will probably be de/serialized using structured-header specs.

[ioggstream]

Structured fields is now RFC 8941
RFC 9651

[baywet]

kind of related to #2458

[Clockwork-Muse]

One big use of a structured header would be the distributed tracing headers for tracestate and baggage.

For that matter, having a common definition for those two plus the traceparent header would be handy...

[handrews]

@Clockwork-Muse everyone is definitely sold on implementing this, it's just a question of how to best model headers, including structured headers, RFC9110-style headers, and other headers, without it either being overly generic (and therefore very complex) or a giant pile of header-specific rules (a different kind of very complex).

[handrews]

Here are two possible generic schemas for RFC9651 Structured Fields.

Many elements of Structured Fields involve a value and optional parameters. Additionally, all name-value pairs (dictionaries and parameters) are ordered. There are several possible ways to handle these things, with the two options below representing two extremes.

Individual headers using structured fields would use these definitions to describe their specific values and parameters.

Note: I have not tested all of the schemas and regexes, although I did test the sf-string regex. These are meant to convey the general idea, they're not meant to be perfect right now.

Using Arrays

This first option uses arrays almost as much as possible. Parametrized values have the value as the first item, and the parameters as the second. Name-value pairs are done as lists objects, each of which must have exactly one property (these could have been done as two-element arrays, but that seemed excessive).

$id: https://spec.openapis.org/oas/3.3/schema/2026-09-01/structured-fields-array
$schema: https://json-schema.org/draft/2020-12/schema
$defs:
  sf-boolean:
    type: boolean
  sf-byte-sequence:
    type: string
    contentMediaType: application/octet-stream
    contentEncoding: base64
  sf-token:
    type: string
    pattern: |-
      ^[a-zA-Z*][a-zA-Z0-9!#$%&'*.^_`|~+-]+$
  sf-string:
    type: string
    pattern: |-
      ^([\x20\x21\x23-\x5B\x5D-\x7E]|(\\\\)|(\\"))*$
  sf-decimal:
    type: string
    pattern: |-
      ^-?\d{1,12}\.\d{1,3}$
  sf-integer:
    type: integer
    format: int64
    minimum: -999999999999999
    maximum: 999999999999999
  sf-date:
    type: integer
    format: int64
    minimum: -62135596800  # Technically can be less but not interop?
    maximum: 253402214400  # Technically can be more but not interop?
  sf-display-string:
    type: string
    pattern: |-
      ^([\x20\x21\x23-\x5B\x5D-\x7E]|(\\\\)|(\\")|(%[0-9a-f][0-9a-f]))*$
  sf-bare-item:
    anyOf:
    - $ref: "#/$defs/sf-boolean"
    - $ref: "#/$defs/sf-byte-sequence"
    - $ref: "#/$defs/sf-token"
    - $ref: "#/$defs/sf-string"
    - $ref: "#/$defs/sf-decimal"
    - $ref: "#/$defs/sf-integer"
  sf-parameters:
    type: array 
    items:
      type: object
      minProperties: 1
      maxProperties: 1
      patternProperties:
        "[a-z*][a-z0-9*._-]*":
          $ref: "#/$defs/sf-bare-item"
  sf-item:
    type: array
    minItems: 1
    prefixItems:
    - $ref: "#/$defs/sf-bare-item"
    - $ref: "#/$defs/parameters"
  sf-inner-list:
    type: array
    minItems: 1
    prefixItems:
    - type: array
      items:
        $ref: "#/$defs/sf-item"
    - $ref: "#/$defs/parameters"
  sf-list:
    type: array
    minItems: 1
    prefixItems:
    - type: array
      items:
        anyOf:
        - $ref: "#/$defs/sf-item"
        - $ref: "#/$defs/sf-inner-list"
    - $ref: "#/$defs/parameters"
  sf-dictionary:
    type: array
    items:
      type: object
      minProperties: 1
      maxProperties: 1
      patternProperties:
        "[a-z*][a-z0-9*._-]*":
          anyOf:
          - $ref: "#/$defs/sf-item"
          - $ref: "#/$defs/sfinner-list"

Using Objects

In this version, parametrized values are two-property objects, with the properties named "value" and "parameters". Name value pairs are still arrays of objects, but the objects have two required fields, "key" and "value".

$id: https://spec.openapis.org/oas/3.3/schema/2026-09-01/structured-fields-object
$schema: https://json-schema.org/draft/2020-12/schema
$defs:
  sf-boolean:
    type: boolean
  sf-byte-sequence:
    type: string
    contentMediaType: application/octet-stream
    contentEncoding: base64
  sf-token:
    type: string
    pattern: |-
      ^[a-zA-Z*][a-zA-Z0-9!#$%&'*.^_`|~+-]+$
  sf-string:
    type: string
    pattern: |- 
      ^([\x20\x21\x23-\x5B\x5D-\x7E]|(\\\\)|(\\"))*$
  sf-decimal: 
    type: string
    pattern: |-
      ^-?\d{1,12}\.\d{1,3}$
  sf-integer:
    type: integer
    format: int64
    minimum: -999999999999999
    maximum: 999999999999999
  sf-date:
    type: integer 
    format: int64 
    minimum: -62135596800  # Technically can be less but not interop?
    maximum: 253402214400  # Technically can be more but not interop?
  sf-display-string:
    type: string
    pattern: |-
      ^([\x20\x21\x23-\x5B\x5D-\x7E]|(\\\\)|(\\")|(%[0-9a-f][0-9a-f]))*$
  sf-bare-item:
    anyOf:
    - $ref: "#/$defs/sf-boolean"
    - $ref: "#/$defs/sf-byte-sequence"
    - $ref: "#/$defs/sf-token"
    - $ref: "#/$defs/sf-string"
    - $ref: "#/$defs/sf-decimal"
    - $ref: "#/$defs/sf-integer"
  sf-parameters:
    type: array
    items:
      type: object
      required:
      - key 
      - value
      properties:
        key:
          type: string
          pattern: |-
            [a-z*][a-z0-9*._-]*
        value:
          $ref: "#/$defs/sf-bare-item"
  sf-item:
    type: object
    required:
    - value 
    properties:
      value:
        $ref: "#/$defs/sf-bare-item"
      parameters:
        $ref: "#/$defs/parameters"
  sf-inner-list:
    type: object
    required:
    - value
    properties:
      value:
        type: array
        items:
          $ref: "#/$defs/sf-item"
      parameters:
        $ref: "#/$defs/parameters"
  sf-list:
    type: object
    required:
    - value
    properties:
      value:
        type: array
        items:
          anyOf:
          - $ref: "#/$defs/sf-item"
          - $ref: "#/$defs/sf-inner-list"
      parameters:
        $ref: "#/$defs/parameters"
  sf-dictionary:
    type: array
    items:
      type: object
      required:
      - key
      - value
      properties:
        key:
          type: string
          pattern: |-
            [a-z*][a-z0-9*._-]*
        value:
          anyOf:
          - $ref: "#/$defs/sf-item"
          - $ref: "#/$defs/sfinner-list"

[baywet]

This might be a little out of topic: I'm curious about why you've used anyOf instead of oneOf for the bare-item here?