Specification · FAB2 · version 0.2
The container, byte by byte
A .fab file is a fixed header, one compressed JSON manifest and a chunk arena. Nothing in it is a web document, and nothing in it is a ZIP archive. This page documents the layout as implemented, verified against real files on 2026-08-17.
Identification
The first sixteen bytes of every FAB2 file are the ASCII string FABYLON_BOOK_02! at offset 0, with no preceding bytes. This is the recommended identification signature for format registries and file-type utilities.
| Extension | .fab |
|---|---|
| Magic, ASCII | FABYLON_BOOK_02! |
| Magic, hex | 46 41 42 59 4C 4F 4E 5F 42 4F 4F 4B 5F 30 32 21 |
| Offset | 0, always |
| Byte order | Little-endian |
| Compression | Zstandard (zstd), RFC 8878 |
| Container ID | manifest field format = "FAB2", version = "0.2" |
| Legacy magic | FABYLON_REALM_01 — an earlier SQLite-backed container, still readable, no longer written |
| Media type | application/vnd.fabylon.book — proposed, not yet registered with IANA |
Header and top-level layout
Offset Size Field 0 16 magic — ASCII "FABYLON_BOOK_02!" 16 4 manifest length, compressed (little-endian uint32) 20 4 manifest length, uncompressed (little-endian uint32) 24 N manifest — zstd-compressed compact JSON 24+N M chunk arena
A reader that knows only these twenty-four bytes can already locate everything else: the manifest gives byte offsets into the arena for every other structure in the file.
The manifest
The manifest is compact JSON, zstd-compressed. Top-level fields as written by the current implementation:
| Field | Type | Meaning |
|---|---|---|
| format | string | Container identifier, "FAB2" |
| version | string | Container version, currently "0.2" |
| enc | string | Page encoding strategy, e.g. "perpage" |
| metadata | object | fab_version, container, title, author, language |
| layout | object | Book-wide defaults: trim_size, font_name, font_size, title_font_size, line_spacing, stanza_spacing, page_number_font_size, page_number_position, start_page_number |
| page_count | integer | Number of pages in the book |
| lead_page | object | A complete copy of page one, inline — see below |
| page_index_ref | object | Arena reference to the page index: offset, size, raw_size, codec |
| assets | array | Asset chunk table — asset id, filename, mime type, offset, size, raw size, codec |
| arena_len | integer | Total length of the chunk arena in bytes |
| dict_ref, shared_dict | object or null | Optional shared compression dictionary |
| search_block | object or null | Optional search text block |
Why page one is stored twice
lead_page duplicates the first page inside the compressed manifest. Opening a book and showing page one therefore needs the manifest only — the page block is never touched. The cost is a few hundred bytes; the benefit is that first paint does not depend on book length. This is the single design decision behind the first-page timings on the benchmarks page.
Page records
Pages are stored as one zstd-compressed compact JSON array in the arena. Compressing the pages together rather than individually removes repeated frame overhead and lets the recurring patterns of literary layout compress across the whole book.
Each page record carries the page as a typographic object, not as markup:
- idx, type, num, show_num, recto — position in the book, page kind, folio and recto/verso side
- frame_w, frame_h, top_extra, line_spacing, font_name, font_size — per-page overrides of the book defaults
- stanzas — arrays of rich-line records: the line text, its indent, its x-position, font size and name, bold and italic, alignment, a stable line id, and optional mixed-format spans within the line
- images — asset references with their placement geometry
The stable line id matters: a line keeps its identity across revisions of the book, so annotations and references survive a re-export.
Why lines, not paragraphs
The line records are where the typography from the mathematics page is preserved. The optimal line breaks, the optical margins and the glyph expansion are all decided once, at typesetting time, and then stored. A reader places what is already decided instead of re-deciding it with less information.
Assets
Assets are independent chunks in the arena, each with its own offset, size, uncompressed size and codec, so any single asset can be read without touching the others. Assets that are already compressed — most images — are stored raw when zstd does not reduce their size, rather than being wrapped in a pointless second compression layer.
What the container does not contain
- No embedded PDF or EPUB fallback. Earlier material described .fab as carrying readable fallback copies. It does not. Fallbacks are published alongside the file, as on the overview page.
- No publication identity. Hashes, signatures, prices, keys and storage addresses stay outside the file, in publication records. A .fab is a book, not a licence.
- No executable content and no scripting. The container holds text, geometry and assets. There is nothing in it to run.
Versioning
The container version is encoded in the magic string itself, so a reader can reject an unknown generation before parsing anything. FABYLON_BOOK_02! is the current generation; FABYLON_REALM_01 was an earlier SQLite-backed design that current readers still open but no longer write. A future incompatible generation will change the magic string rather than a field inside it.
Reference material
- Specification paper, five languages, as PDF, EPUB and .fab — on the overview page
- Repository — github.com/mbenders/fab-format
- Reference reader — Fabylon Reader, free
- Reference writer — Fabylon Bookmaker