CBDF Specification: Overview
Version 1.1 (Phase II)Document: 00-Overview • Date: 2026-07-13
1. What is CBDF?
CBDF (Compact Binary Document Format) is a binary open-standard document format designed to radically reduce the size of marked-up documents relative to HTML/CSS. A CBDF-formatted message can be on the order of 1% of an equivalent modern HTML email for styled mail; tiny messages are a few percent. The format optimizes for bandwidth, storage, and parse cost while remaining degradable to plain text.
CBDF achieves this by:
- Using a 2-byte Layout ID (65,536 predefined page layouts in a client-side catalogue vs. hundreds of bytes of CSS/HTML)
- Limiting colors to 65,536 (2 bytes vs. 7 bytes for CSS
#RRGGBB) - Using a fixed font table of 4,096+ fonts (2 bytes vs. font-family strings)
- Encoding all formatting as compact binary style records referenced by 1-byte indices
- Using ASCII control characters (
0x00–0x1F) as inline commands instead of verbose HTML tags - Placing binary resources (images, fonts) in a separate skippable section after Text
- Optional compression of Styles+Text (zlib mandatory to implement in Phase II)
2. Design Principles
- One canonical encoding. Strict parsers; no HTML-style quirks repair.
- Degrade to readable text. Stripping bytes
0x00–0x1F(keeping TAB and LF) from Text yields clean UTF-8. - Tables over self-description. Layouts, fonts, and styles live in the codec/catalogue; the wire carries indices.
- Fixed sizes and explicit lengths. No delimiter sniffing for style records or section boundaries.
- Static documents are safe. Phase II has no executable Logic. AI prompts are receiver-evaluated requests.
- User owns the final render. Themes and accessibility outrank document chrome.
- Claims vs attestations. Meta is sender claim; QMail Tell/RAIDA data is network attestation (see Meta receiver annotations).
Registries (meta keys, feature bits, layout catalogue, fonts, named style sets) are open-standard, append-only, jointly governed by the CloudCoin Consortium, the Perfect Money Foundation, and the RAIDA Group.
3. Use Cases
- QMail: Quantum-safe email (
.qmailfiles) - QWeb: Web pages (
.qwebfiles) - Presentation / form documents: reserved Meta File Type values 4 and 5
- RAIDA: Client-server data exchange
- Text messaging: Ultra-compact meta-only messages (on the order of 14–50 bytes for short SMS-class content)
4. Document Structure
[Meta] FS [Styles] FS [Text] FS [Resources] FS [Logic]
[ optional: FS [SectionID:1][Len:4 LE][payload] ... ]| Section | Compressed? | Description |
|---|---|---|
| Meta | Never | Envelope: identity, routing, preview, feature flags, version. Always readable. In QMail, may ship as file_type=0 separate from the body. |
| Styles | With Text if enabled | LayoutID + visual formatting lookup tables. |
| Text | With Styles if enabled | UTF-8 body + control codes. Before Resources for abortable download. |
| Resources | Never (already-compressed codecs) | Binary blobs (images, fonts). Slot always present in Phase II; payload may be empty. |
| Logic | — | Executable code. Phase II: always zero length. Phase III: BEAM/Elixir (or successor). |
All multi-byte integers in CBDF are little-endian. Core sections are identified by position, not by a per-section file-ID byte.
5. Versioning
| Version | Detection | Body shape |
|---|---|---|
| 0 (Phase I) | Meta key 30 absent | FS FS STX [plain text…EOF] — implemented in qmail_cbdf.c |
| 1 (Phase II) | Meta key 30 = 1 | Length-prefixed Styles, Text, Resources, Logic; full style/control language |
| 2+ | Key 30 ≥ 2 | Future (e.g. Logic). Bump only when old parsers cannot safely skip new constructs. |
No leading magic byte before the Meta pair count — that would break deployed Phase I files.
6. Specification Documents
| Document | Description |
|---|---|
00-Overview | This document |
01-Document-Structure | Section layout, compression, empty tails, QMail packaging, parallel parse notes |
02-Meta-Section | KLV format, key table, feature flags, Tell annotations, mailbox format |
03-Styles-Section | LayoutID, style sub-tables, record formats, layers |
04-Text-Section | Control codes in text, tables, plain-text extraction |
05-Resources-Section | Binary resource format, abortable downloads |
06-Logic-Section | Phase III placeholder |
07-Control-Characters | 32 ASCII control assignments |
08-Color-System | R5G6B5 encoding, transparency codes |
09-Font-System | Font IDs, effects, custom fonts |
10-Layout-Catalogue | LayoutID registry, pane indices, mobile pairs, nav bar rules, JSON data file |
7. Phases
| Phase | Description | Status |
|---|---|---|
| Phase I | Plain text only (qmail_cbdf.c) | Implemented |
| Phase II | Styled text, LayoutID catalogue, images, nav, tables, layers, Tell annotations, feature flags | Current phase |
| Phase III | Logic section, forms, interactive features, optional separate large resources, semantic encoding | Planned |
Semantic encoding (compression type 5) is experimental and not required for Phase II implementers until a model registry exists.
8. Parallel Parsing (summary)
CBDF supports coarse-grained parallelism: section split via FS + lengths, packed style tables (indexable after one pass), resource decode on a thread pool, pane paint after a serial Text walk. The Text control stream remains sequential (style stack). Full details: Document Structure § parallel parse.