Use-As-Dictionary

The HTTP Use-As-Dictionary response header instructs the client to store the response body as a Compression dictionary for future requests matching the specified patterns.

Table of Contents

Usage
Directives
Example
Takeaway
See also

Usage

Compression dictionaries reduce bandwidth by encoding repeated patterns against a shared reference. The Use-As-Dictionary header turns the current response into a dictionary the client stores locally. When the client later requests a URL matching the dictionary's match pattern, the client sends Available-Dictionary with the SHA-256 hash of the stored dictionary. The server then compresses the response against the dictionary using dictionary-compressed Brotli (dcb) or dictionary-compressed Zstandard (dcz) via Content-Encoding.

The header uses Structured Fields syntax. The match parameter specifies a URL path pattern (regular expressions are not supported). The match-dest parameter limits the dictionary to specific Fetch request destinations (document, script, style, fetch). The id parameter assigns an opaque identifier the client echoes back via Dictionary-ID. The type parameter declares the dictionary format, with raw as the only defined value.

The response carrying Use-As-Dictionary must include standard Caching headers so the client stores the dictionary alongside the response. Dictionaries work best for resources with stable structure and repeated content across versions: JavaScript bundles, API responses, and template fragments. The specification requires compression dictionary transport to operate exclusively in secure contexts (HTTPS).

Directives

match

The match parameter defines a URL path pattern determining which future requests use this dictionary. The pattern operates on percent-encoded URL paths and must be same-origin as the dictionary resource. Regular expressions are not supported.

match-dest

The match-dest parameter restricts the dictionary to specific Fetch request destination types. The value is an inner list of strings such as document, script, style, font, image, or fetch. When omitted or empty, the dictionary matches all destination types.

id

The id parameter assigns an opaque server-provided identifier to the dictionary (up to 1024 characters). The client echoes this value via the Dictionary-ID request header when using the dictionary. The server must not rely on id to guarantee dictionary contents.

type

The type parameter declares the dictionary format. The only valid value is raw, indicating an unformatted byte sequence usable as an external dictionary for Brotli or Zstandard. Clients reject unknown type values. The compression algorithm is negotiated separately through Accept-Encoding and Content-Encoding using the dcb (dictionary-compressed Brotli) or dcz (dictionary-compressed Zstandard) tokens.

Example

A server marks an API response as a compression dictionary for all paths under /api/. The response includes Cache-Control so the client stores the dictionary.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=86400
Use-As-Dictionary: match="/api/"

{
  "version": "2.1",
  "common_fields": [...]
}

On the next request to a matching path, the client sends the SHA-256 hash of the stored dictionary and advertises dictionary-compressed encodings.

GET /api/users HTTP/1.1
Host: example.re
Accept-Encoding: dcb, dcz
Available-Dictionary:
  :pZGm1Av0IEBKARczz7exkNYsZb8LzaMrV7J32a2fFG4=:

The server compresses the response against the dictionary and signals the encoding used.

HTTP/1.1 200 OK
Content-Encoding: dcz
Content-Type: application/json

A dictionary restricted to fetch destinations with an identifier for server-side tracking.

Use-As-Dictionary: match="/data/", match-dest=("fetch"), id="data-v1"

A JavaScript bundle dictionary scoped to script destinations. The client reuses the dictionary across bundle version updates where the structure is stable.

Use-As-Dictionary: match="/assets/app-", match-dest=("script")

Takeaway

The Use-As-Dictionary header marks the response as a Compression dictionary for future requests, defining match patterns, destination types, and dictionary format to enable bandwidth reduction through dictionary-compressed Brotli (dcb) or Zstandard (dcz).