Dictionary-ID

The HTTP Dictionary-ID request header carries an opaque identifier for a Compression dictionary the client has cached, echoing the identifier the server assigned via the Use-As-Dictionary response header.

Table of Contents

Usage

Compression dictionaries enable smaller payload sizes by referencing shared data patterns between requests. A server advertising a dictionary via Use-As-Dictionary provides the dictionary content and assigns the dictionary an identifier. The client caches the dictionary and stores the identifier alongside the dictionary.

On subsequent requests matching the dictionary's scope, the client sends Dictionary-ID alongside the Available-Dictionary request header. The Dictionary-ID value echoes the identifier the server originally assigned, letting the server confirm which dictionary version the client holds. The server then applies dictionary-based compression to the response body if the content benefits from compression.

The header works alongside Use-As-Dictionary and Available-Dictionary to coordinate dictionary-based compression with schemes like Brotli and Zstandard.

Values

The Dictionary-ID header accepts a Structured Field String representing the server's internal identifier for the dictionary resource. Servers generate identifiers based on their own dictionary storage and versioning mechanisms. The value must not exceed 1024 characters and must match the id value from the original Use-As-Dictionary response.

Dictionary-ID: "v42"

The identifier remains stable as long as the dictionary content remains unchanged. When the server updates the dictionary, the server assigns a new identifier via Use-As-Dictionary, and the client updates its cached value accordingly.

Example

A server sends a response with Use-As-Dictionary assigning a dictionary identifier. The client caches both the dictionary and the identifier.

Use-As-Dictionary: match="/api/*", id="dict-2024-08"

On a subsequent request matching the pattern, the client echoes the stored identifier back to the server alongside the dictionary hash.

Available-Dictionary: :pZGm1Av0IEBKARczz7exkNYsZb8LzaMrV7J32a2fFG4=:
Dictionary-ID: "dict-2024-08"

When the server updates the dictionary, a new identifier is issued. The client fetches the updated dictionary and sends the new identifier on future requests.

Dictionary-ID: "dict-2024-09"

A lookup key, not an identity

The hash inside Available-Dictionary is the authoritative identity of a dictionary, and Dictionary-ID is a convenience beside the hash. A server storing dictionaries under its own identifiers avoids a hash-table scan by reading the echoed id, and remains obliged to verify the hash before compressing against the blob, since the id is client-echoed text up to 1024 characters and proves nothing.

The header appears only when the server asked for the echo by attaching an id parameter to Use-As-Dictionary. Dictionaries stored without one produce requests carrying the hash alone, so the absence of Dictionary-ID on an otherwise dictionary-aware request means the server never assigned an identifier rather than a client omission.

A ttl parameter for Use-As-Dictionary is moving through standardization, decoupling dictionary lifetime from HTTP cache freshness, after the original design dropped the knob for lack of use cases and deployment experience brought the cases back.

See also

Last updated: August 17, 2026