Shared Brotli extends Brotli (RFC 7932) with
shared dictionaries, a larger LZ77 window and a framing format. It is RFC 9841, “Shared Brotli
Compressed Data Format” (Informational, September 2025, updating RFC 7932). A stream that uses
none of it is an ordinary Brotli stream; a decoder given no dictionary behaves as RFC 7932
says. The extension adds two kinds of dictionary, and this page also covers the framing format
and the checks the google/brotli reader makes on a serialised dictionary.
Sources, read in November 2026: RFC 9841 (rfc-editor.org/rfc/rfc9841.txt), and the
google/brotli files c/common/shared_dictionary.c,
c/common/shared_dictionary_internal.h and
c/include/brotli/shared_dictionary.h (master, commit
5516943f69130987002357bb0dd3764ce7c9670b, 2026-11-18).
The two kinds of shared dictionary
- LZ77 dictionary (a prefix, or compound, dictionary)
- A run of bytes the encoder and decoder both hold. The decoder treats it as if those bytes sat in front of the sliding window, so a copy can reach back into them. Several can be set at once.
- Custom static dictionary
- A word list with transforms that replaces the built-in static dictionary of RFC 7932 (Appendices A and B), and may switch by context. The list can also refer to the built-in dictionary and transforms.
A shared dictionary may set LZ77 dictionaries, override static dictionary words, override transforms, or any of them. The same dictionary must be used to compress and to decompress.
LZ77 dictionaries in the distance arithmetic
Let L be the LZ77 dictionary’s length (RFC 9841 section 3.2). A distance in the range
(max allowed distance + 1) to (L + max allowed distance) refers into the
dictionary, at the byte at dictionary_address = L + max allowed distance − distance.
If the copy is longer than L − dictionary_address it carries on from
the start of the regular window for the remaining length − L + dictionary_address
bytes. The static dictionary’s word_id becomes
distance − (max allowed distance + 1 + L); with L = 0 it is the RFC 7932
definition.
Custom static dictionaries
With a custom word list the decoder changes three things (section 3.1): the words come from
the custom lists instead of Appendix A, each list has its own SIZE_BITS_BY_LENGTH
in place of NDBITS, and a static-dictionary copy length must be 4 to 31 and a length whose
size bits are 0 is not allowed. With a custom transform list (and no context dependence) the
transforms replace Appendix B, and transform_id must be less than the number of
transforms in the list.
If the dictionary is context dependent it holds a table of 64 word-list and transform-list pairs. To resolve a static dictionary word the decoder computes the literal context ID as in RFC 7932 section 7.1 and uses it as the index; without context dependence the ID is 0. When a distance goes past the dictionary for the current ID and several pairs are defined, the next one is used: with context, the pair for the current context first and then the others in the order of the shared dictionary; without it, the order of the shared dictionary.
The shared dictionary stream
A dictionary can stand alone as a file, or be the contents of a resource inside a
framing format container (RFC 9841 section 5). All multi-byte fields
below are as the RFC gives them: PREFIX_SUFFIX_LENGTH and the transform
parameters are 2 bytes; the google/brotli reader loads them little-endian
(BROTLI_UNALIGNED_LOAD16LE).
| Field | Size | Meaning |
|---|---|---|
| Signature | 2 bytes | 91 00 |
LZ77_DICTIONARY_LENGTH | varint | The number of bytes of LZ77 dictionary, 0 for none. At most the largest window of brotli or large-window brotli (RFC). The google/brotli reader refuses a value above 1,073,741,823 and a varint whose fifth byte is above 15. |
| LZ77 dictionary | LZ77_DICTIONARY_LENGTH bytes | The dictionary bytes. |
NUM_CUSTOM_WORD_LISTS | 1 byte | 0 to 64. |
| Word lists | that many | See below. |
NUM_CUSTOM_TRANSFORM_LISTS | 1 byte | 0 to 64. |
| Transform lists | that many | See below. |
NUM_DICTIONARIES | 1 byte | Only if there is at least one custom word list or transform list: 1 to 64. Each dictionary is a word list with a transform list. The next is used when a distance goes beyond the previous. |
DICTIONARY_MAP | NUM_DICTIONARIES × 2 bytes | Per dictionary: an index into the custom word lists, or NUM_CUSTOM_WORD_LISTS for the built-in word list; then the same for transform lists. |
CONTEXT_ENABLED | 1 byte | 0: no context map. 1: a context map follows. (The google/brotli reader refuses any other value.) |
CONTEXT_MAP | 64 bytes | Only when CONTEXT_ENABLED is 1: for each of the 64 literal contexts, the index into the dictionary map of the first dictionary to use. (The reader refuses an entry not less than NUM_DICTIONARIES.) |
With no custom lists, NUM_DICTIONARIES is implicitly 1 and points to the built-in
dictionary, and there is no context map; none of the three fields after the transform lists
is present.
A word list
| Field | Size | Meaning |
|---|---|---|
SIZE_BITS_BY_LENGTH | 28 bytes | Indexed by word length 4 to 31: log2 of the number of words of that length, 0 meaning none. At most 15 (the reader refuses more). |
| Word data | N bytes | All the words of the shortest length first, then the next length, and so on; each length has none or a power-of-two number of words. N = OFFSETS_BY_LENGTH[31] + (SIZE_BITS_BY_LENGTH[31] ? 31 << SIZE_BITS_BY_LENGTH[31] : 0), where OFFSETS_BY_LENGTH[i + 1] = OFFSETS_BY_LENGTH[i] + (SIZE_BITS_BY_LENGTH[i] ? (i << SIZE_BITS_BY_LENGTH[i]) : 0). |
A transform list
| Field | Size | Meaning |
|---|---|---|
PREFIX_SUFFIX_LENGTH | 2 bytes | The length of the prefix and suffix data. At least 1: the list always ends with a zero-length stringlet. |
| Stringlets | NUM_PREFIX_SUFFIX of them, 1 to 256 | Each is a 1-byte STRING_LENGTH then that many bytes. Entries before the last have a length of 1 to 255. The last has length 0 and must be the last of the PREFIX_SUFFIX_LENGTH bytes, or the stream is invalid. (The google/brotli reader stops at 255 stringlets before the terminator.) |
NTRANSFORMS | 1 byte | The number of transform triplets. |
| Triplets | NTRANSFORMS × 3 bytes | Prefix index (less than NUM_PREFIX_SUFFIX), suffix index (the same limit), operation index (the table below). |
| Parameters | NTRANSFORMS × 2 bytes | Present if and only if at least one transform is ShiftFirst or ShiftAll. An unsigned 16-bit value for those two; it must be 0 for any other operation. |
Transform operations
Operations 0 to 20 are those of RFC 7932 section 8; 21 and 22 are new (RFC 9841 section 3.1.1).
| ID | Operation |
|---|---|
| 0 | Identity |
| 1 to 9 | OmitLast1 to OmitLast9 |
| 10 | FermentFirst |
| 11 | FermentAll |
| 12 to 20 | OmitFirst1 to OmitFirst9 |
| 21 | ShiftFirst (by PARAMETER) |
| 22 | ShiftAll (by PARAMETER) |
ShiftFirst and ShiftAll change specially encoded scalars. A SCALAR is an unsigned integer of 7, 11, 16 or 21 bits held in 1, 2, 3 or 4 bytes (the s bits make the value, the most significant first; the X bits are arbitrary):
| Bits | Bytes |
|---|---|
| 7 | 0sssssss |
| 11 | 110sssss XXssssss |
| 16 | 1110ssss XXssssss XXssssss |
| 21 | 11110sss XXssssss XXssssss XXssssss |
The ADDEND is the 16-bit PARAMETER zero-extended to 32 bits, with 0xFF0000 added if the result is at least 0x8000. ShiftAll starts at the first byte of the word and repeats: if the next untransformed byte matches the first byte of one of the four patterns, then (if the rest of the word is too short for the whole pattern the whole word is marked transformed; otherwise let SHIFTED be ADDEND plus the encoded SCALAR, write its lowest bits back into the s positions, leaving the 0, 1 and X bits, and mark 1 to 4 bytes transformed by the pattern’s length); otherwise mark the byte transformed. ShiftFirst does this once.
What the google/brotli reader checks
The reader is DecodeSharedDictionary in c/common/shared_dictionary.c.
Its public declaration, in c/include/brotli/shared_dictionary.h, marks the serialised
type “DO NOT USE: methods accepting this value will fail”, and the code is compiled only when
BROTLI_EXPERIMENTAL is defined; a raw dictionary (a plain LZ77 prefix) is always
accepted.
- The first two bytes must be
91 00. - At most 15 prefix dictionaries in all (
SHARED_BROTLI_MAX_COMPOUND_DICTS); each raw dictionary and each non-empty LZ77 part of a serialised one counts as one. - A second serialised dictionary that carries custom words or transforms is refused when one is already attached: only prefix dictionaries combine.
- Word lists and transform lists are at most 64 each (
SHARED_BROTLI_NUM_DICTIONARY_CONTEXTS);NUM_DICTIONARIESis 1 to 64; a word-list index may equalNUM_CUSTOM_WORD_LISTS(the built-in list) and a transform-list index likewise, never more. - Word lengths run from 4 (
SHARED_BROTLI_MIN_DICTIONARY_WORD_LENGTH) to 31 (…MAX…). - Data may not run past the end of the file; a raw dictionary’s practical limit is the constant
SHARED_BROTLI_MAX_RAW_DICT_SIZE(1 << (23 + sizeof(size_t)): 128 MiB with 4-byte sizes, 2 GiB with 8-byte sizes). The header calls it a practical limit and says that it knows of no use for more than 64 MiB in regular mode or 2 GiB in large-window mode.
Large-window brotli
Described on the stream page from
the same source. RFC 9841 section 6 gives the header as 8 bits 00010001 then 6
bits of WBITS, 10 to 62. The distance alphabet may then be up to 16 + NDIRECT + (124 << NPOSTFIX)
symbols, with no symbol able to stand for a distance above (1 << 63) − 4. A decoder
without 64-bit integers may reject WBITS above 30, or a distance symbol able to encode more
than 2,147,483,644.
Varints
Base 128, least significant group first: each byte except the last has its top bit set, and
the last has it clear (1xxxxxxx repeated 0 to 8 times, then 0xxxxxxx).
At most 63 bits are read: a ninth byte with its top bit set makes the stream invalid (RFC 9841
section 4). A reversed varint (the final footer) has the same form with its bytes in reverse
order, so that it can be read from the end of the file backwards.
The framing format
An optional container (RFC 9841 section 8) holding one or more resources as chunks. Brotli streams themselves are unchanged; the framing carries names, metadata, dictionary references and a directory.
| Field | Size | Meaning |
|---|---|---|
| Signature | 4 bytes | 91 0A 42 52. The first byte is an invalid WBITS combination for both brotli and large-window brotli. |
| Container flags | 1 byte | Bits 0 and 1: version, must be 00. Bit 2: if 0, there is no final footer, no metadata chunk and no central directory, and a single resource (in one or more data chunks); if 1, there may be several resources, metadata and a central directory, and a final footer is required. |
| Chunks | repeated | As below. |
Chunk format
| Field | Size | Meaning |
|---|---|---|
| Length | varint | The chunk’s length without this varint but with all the header bytes below and the data. If 0, the type byte is absent and the type is 0 (padding). |
CHUNK_TYPE | 1 byte | See the table below. |
CODEC | 1 byte | Not present for padding, central directory and final footer. 0 uncompressed, 1 keep decoder (continue the stream the previous chunk left, with its decoder state), 2 brotli, 3 shared brotli. |
| Uncompressed size | varint | Unless the codec is uncompressed: the size of the data inside the compressed stream. |
| Dictionary references | 1 byte count, then each | Only for shared brotli. At most 1 serialised dictionary and 15 prefix dictionaries (a serialised one may already hold one prefix dictionary). A chunk may not refer to itself, directly or through others. |
| Extra header bytes | as the type says | |
| Contents | the rest | Raw bytes, the continuation of a stream, a brotli stream (RFC 7932) or a shared brotli stream (section 7: the extensions above, regular or large-window). |
Chunk types
| Type | Chunk | Extra header and contents |
|---|---|---|
| 0 | Padding | All bytes after the length varint are zero. A single byte 0 is a padding chunk of length 1; use larger values for more, not several short chunks. |
| 1 | Metadata | Applies to the resource encoded in the following data or first partial chunk. Metadata format. |
| 2 | Data | One flags byte, then (if the hash bit is set) a hash type byte and the hash. The resource’s bytes. |
| 3 | First partial data | As data; the hash bit must be 0; the size is of this part only. |
| 4 | Middle partial data | As data; the first two flag bits must be 0. |
| 5 | Last partial data | As data; the first flag bit must be 0. A hash, if given, is of the whole resource. It ends the resource. |
| 6 | Footer metadata | Applies to the resource that ended in the previous data or last partial chunk. No lowercase fields are defined. |
| 7 | Global metadata | Applies to the whole container. No lowercase fields are defined. |
| 8 | Repeat metadata | One extra byte: the chunk type of the repeated chunk (metadata or footer metadata). Optional; if present, one for every metadata and footer metadata chunk, in the same order as the container and the central directory, and decompressible without other chunks. |
| 9 | Central directory | Always uncompressed, no codec byte. A varint pointer to the repeat metadata chunks (0 if none), then for each chunk a varint pointer to it, a varint count N of header bytes and a copy of those N bytes (not the contents). It lists every data and metadata chunk. |
| 10 | Final footer | Always uncompressed: a reversed varint with the size of the whole file (0 if not given), then a reversed varint with the pointer to the central directory (0 if none). Present only if container flag bit 2 is set; it is the last chunk. |
Data chunk flags
| Bit | Meaning |
|---|---|
| 0 | The resource is not output implicitly when extracting; it can only be referred to, for example as a dictionary by hash or offset. Set it on data used only as a dictionary. |
| 1 | A hash code is given. |
| 2 to 7 | Must be 0. |
The hash is a hash type byte, only 3 defined (256-bit HighwayHash), then 32 bytes of the hash of the uncompressed data.
A dictionary reference
| Field | Meaning |
|---|---|
| Flags bits 0 and 1: source | 00 a full resource by pointer (a full data chunk or a first partial data chunk, which can span chunks); 01 the contents of a single chunk by pointer (any chunk with content, not as a serialised dictionary; for a partial data chunk only that part); 10 a hash of a resource, which may come from outside this container (the decoder’s user must supply it, or it is an error); 11 invalid. |
| Flags bits 2 and 3: type | 00 a prefix dictionary, set in front of the sliding window; 01 a serialised dictionary in the format above; 10 and 11 invalid. |
| Flags bits 4 to 7 | Must be 0. |
| Hash-based | A hash type byte (only 3, 256-bit HighwayHash) and 32 bytes of the hash. |
| Pointer-based | A varint pointer to the chunk in this container, which must come earlier than the current chunk. |
Metadata fields
The uncompressed contents of every metadata chunk type is a run of fields (section 8.3): a 2-byte code of two lowercase or two uppercase ASCII letters, a varint length, then the contents. The run must end exactly at the end of the contents. A lowercase code the decoder does not know for that chunk type, or a code of non-letters, makes the stream invalid; uppercase codes are custom user metadata and a decoder may ignore them.
| Code | In | Meaning |
|---|---|---|
id | metadata chunk, 0 or 1 times | A name in UTF-8, which may be used as a file name: with / as the separator, relative paths, and a name ending in / with an empty data chunk as an empty directory. |
mt | metadata chunk, 0 or 1 times | 8 bytes: microseconds since the epoch, a little-endian signed 64-bit integer. |
| two uppercase letters | any | Custom user field. |
Chunk order
A decoder must reject a stream that breaks these rules (section 8.4.12). Padding chunks may go anywhere. A metadata chunk comes immediately before the data of its resource, a footer metadata chunk immediately after it, with at most one of each per resource. A resource is one data chunk, or one first partial, any number of middle partials and one last partial, in that order. At most one central directory. If container flag bit 2 is 0: one resource only, no metadata chunk of any kind, no central directory and no final footer; if it is 1 there must be exactly one final footer, last in the file. (The RFC’s text of section 8.4.12 states the two cases the other way round from section 8.1; this page follows section 8.1, which is the one that defines the flag.)
Not covered here
HighwayHash is named by the RFC and not described by it. How .dcb files wrap a
shared brotli stream over HTTP is on the
DCB and DCZ page.
The explorer reads everything on this page. A 91 00 file opens as a dictionary and a
91 0A 42 52 file as a container; a stream is decoded with an LZ77 dictionary (checked byte for
byte against the brotli tool, -D) and with custom word lists, transform lists and
a context map (checked against streams made by hand, as no encoder writes them). Several prefix dictionaries
are joined in the order they are listed, and a dictionary reference’s pointer is read as the offset in the
container of the chunk it names; the RFC states neither outright. When a stream’s dictionary is not
available, the viewer lists its references to the dictionary and decodes as far as it can.
Sources
- RFC 9841 – Shared Brotli Compressed Data Format
- google/brotli, c/common/shared_dictionary.c and shared_dictionary.h