← .fab

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, ASCIIFABYLON_BOOK_02!
Magic, hex46 41 42 59 4C 4F 4E 5F 42 4F 4F 4B 5F 30 32 21
Offset0, always
Byte orderLittle-endian
CompressionZstandard (zstd), RFC 8878
Container IDmanifest field format = "FAB2", version = "0.2"
Legacy magicFABYLON_REALM_01 — an earlier SQLite-backed container, still readable, no longer written
Media typeapplication/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:

FieldTypeMeaning
formatstringContainer identifier, "FAB2"
versionstringContainer version, currently "0.2"
encstringPage encoding strategy, e.g. "perpage"
metadataobjectfab_version, container, title, author, language
layoutobjectBook-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_countintegerNumber of pages in the book
lead_pageobjectA complete copy of page one, inline — see below
page_index_refobjectArena reference to the page index: offset, size, raw_size, codec
assetsarrayAsset chunk table — asset id, filename, mime type, offset, size, raw size, codec
arena_lenintegerTotal length of the chunk arena in bytes
dict_ref, shared_dictobject or nullOptional shared compression dictionary
search_blockobject or nullOptional 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

FAB2, container version 0.2. Header, magic string and manifest fields on this page were verified on 2026-08-17 by parsing the published specification files in this directory. Registry maintainers who need anything further may write to m.benders@fabylon.net.