An open specification for documents that unify viewing and editing, with modern security and machine readability.
Status: Draft Specification (v0.1)
The document landscape is fundamentally divided:
- View-optimized formats (PDF, DJVU) offer layout fidelity but poor editability
- Edit-optimized formats (DOCX, ODF, Markdown) enable rich editing but render inconsistently
- No existing format excels at both viewing and editing
This divide creates workflow friction, format conversion overhead, and lost fidelity. Additionally:
- PDF's security model is broken: 21 of 22 desktop viewers vulnerable to signature attacks
- Machine readability is an afterthought: 73-96% accuracy even with state-of-the-art extraction
- Compression is outdated: PDF uses 30-year-old DEFLATE, missing modern algorithms
- No clear "frozen" semantics: Signatures don't truly lock documents
- No verifiable history: Document lineage and provenance are external concerns, not built-in
- Appearance varies by viewer: Even PDF renders differently across implementations
- Unified View/Edit Mode: One format from draft to archive, no conversion step
- Semantic-First: Content stored as meaning, presentation derived
- Modern Security: Algorithm-agile cryptography, post-quantum ready
- Machine Readable: AI/ML extraction works reliably by design
- Content-Addressable: Document hash is its identity; modifications create new versions
- Verifiable Provenance: Built-in hash chains and Merkle trees for tamper-evident history
- Efficient compression using modern algorithms (Zstandard, AVIF)
- Clear document state machine (draft → review → frozen/signed)
- State-aware presentation (reactive for drafts, precise for frozen/published)
- Block-level proofs (prove a section exists without revealing the whole document)
- Timestamp anchoring (RFC 3161, blockchain)
- Accessibility built-in (WCAG-aligned)
- Replacing PDF for legacy/archival use cases
- Supporting scripting/executable content (security risk)
- Achieving 100% PDF import fidelity
┌─────────────────────────────────────────────────────────────┐
│ DOCUMENT CONTAINER │
│ (ZIP archive, content-addressable hash = identifier) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────────────────────┐ │
│ │ MANIFEST │ │ CONTENT STREAMS │ │
│ │ - Version │ │ ┌────────────────────────────┐ │ │
│ │ - State │ │ │ Semantic Document Layer │ │ │
│ │ - Signatures[] │ │ │ (JSON blocks + Merkle tree)│ │ │
│ │ - Lineage │ │ └────────────────────────────┘ │ │
│ │ - Merkle root │ │ ┌────────────────────────────┐ │ │
│ └──────────────────┘ │ │ Presentation Layer(s) │ │ │
│ │ │ - Reactive (hints/styles) │ │ │
│ ┌──────────────────┐ │ │ - Precise (exact coords) │ │ │
│ │ SECURITY LAYER │ │ └────────────────────────────┘ │ │
│ │ - Signatures │ │ ┌────────────────────────────┐ │ │
│ │ - Encryption │ │ │ Assets │ │ │
│ │ - Timestamps │ │ │ (images, fonts, embeds) │ │ │
│ └──────────────────┘ │ └────────────────────────────┘ │ │
│ └──────────────────────────────────┘ │
│ ┌──────────────────┐ │
│ │ PROVENANCE │ ← Links to parent document hash │
│ │ - Parent hash │ (documents form a hash chain) │
│ │ - Ancestors │ │
│ │ - Timestamps │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Codex documents form a cryptographic hash chain — each document's identity IS its content hash, and each document can reference its parent by hash:
doc-v1 (sha256:aaa) ←── doc-v2 (sha256:bbb) ←── doc-v3 (sha256:ccc)
│ │ │
└── parent: null └── parent: aaa └── parent: bbb
This enables:
- Tamper-evident history: Forging an intermediate version is computationally infeasible
- No external infrastructure: Documents themselves ARE the chain
- Block-level Merkle proofs: Prove a specific section exists without revealing the whole document
- Selective disclosure: Share redacted documents with cryptographic proof of what was removed
- Timestamp anchoring: Anchor document hashes to RFC 3161 TSAs or public blockchains
Codex uses progressive enhancement for presentation — the level of layout precision evolves with document maturity:
| Document State | Presentation Requirement | What's Frozen |
|---|---|---|
| DRAFT | Reactive only (hints/styles) | Nothing — content flows freely |
| REVIEW | Reactive (precise optional) | Nothing — still editing |
| FROZEN | Reactive + precise required | Content immutable; appearance locked |
| PUBLISHED | Same as FROZEN | Authoritative, immutable record |
When a document reaches FROZEN or PUBLISHED state, its precise layout (exact coordinates for every element) becomes part of the immutable record:
- Semantic content is the hash: The document ID covers semantic content only — what it says, not how it looks
- Appearance is locked alongside content: Precise layouts are immutable when frozen, but separate from the content hash. Use scoped signatures (Security Extension) for appearance attestation
- Citations are reliable: "Page 7, line 23" means the same thing in every viewer
- Legal/archival integrity: Frozen documents render pixel-perfectly, forever
- No viewer inconsistency: Unlike PDF, whose appearance varies by renderer
This is the key insight: the state machine isn't just about workflow — it enforces the relationship between content stability and presentation precision. You can't freeze a document without committing to exactly how it looks.
DRAFT FROZEN/PUBLISHED
┌─────────────────┐ ┌─────────────────┐
│ Semantic content│ │ Semantic content│ ← Document ID
│ (JSON blocks) │ │ (JSON blocks) │ (content hash)
├─────────────────┤ ├─────────────────┤
│ Reactive hints │ → │ Reactive hints │
│ (optional) │ │ + Precise layout│ ← Required, immutable
└─────────────────┘ │ (exact coords) │ (scoped signatures
└─────────────────┘ for attestation)
The specification is modular:
- Container Format - ZIP-based packaging
- Manifest - Document metadata and structure
- Content Blocks - Semantic content model
- Presentation Layers - Rendering instructions
- Asset Embedding - Images, fonts, files
- Document Hashing - Content-addressable identity
- State Machine - Draft/frozen lifecycle
- Metadata - Dublin Core and extensions
- Provenance and Lineage - Hash chains, Merkle trees, timestamping
- Security Extension - Signatures, encryption, access control
- Collaboration Extension - CRDT hooks, comments, change tracking
- Presentation Extension - Advanced layout, print styling
- Forms Extension - Input fields, validation
- Semantic Extension - JSON-LD, knowledge graphs, citations
A Codex document is a ZIP archive with this structure:
document.cdx
├── manifest.json # Document manifest (includes lineage, Merkle root)
├── content/
│ ├── document.json # Semantic content blocks
│ └── block-index.json # Block hashes for Merkle proofs
├── presentation/
│ ├── defaults.json # Base styles
│ ├── paginated.json # Print hints (reactive)
│ ├── continuous.json # Screen hints (reactive)
│ └── layouts/ # Precise layouts (required for FROZEN/PUBLISHED)
│ ├── letter.json # US Letter format coordinates
│ └── a4.json # A4 format coordinates
├── assets/
│ ├── images/
│ ├── fonts/
│ └── embeds/
├── security/
│ └── signatures.json # Digital signatures
├── provenance/
│ └── record.json # Lineage, timestamps, derivations
└── metadata/
└── dublin-core.json # Standard metadata
{
"codex": "0.1",
"id": "sha256:a1b2c3...",
"state": "draft",
"content": {
"blocks": [
{
"type": "heading",
"level": 1,
"children": [{ "type": "text", "value": "Hello, World" }]
},
{
"type": "paragraph",
"children": [
{ "type": "text", "value": "This is a " },
{ "type": "text", "value": "Codex", "marks": ["bold"] },
{ "type": "text", "value": " document." }
]
}
]
}
}- Extension:
.cdx - MIME Type:
application/vnd.codex+json(canonical JSON form) - Alternative:
application/vnd.codex(binary/packed form)
- Complete core specification documents
- JSON Schema for validation
- Example documents
- Security extension (signatures, encryption)
- Collaboration extension (CRDT integration)
- Presentation extension (advanced layout)
- Forms extension (input fields, validation)
- Semantic extension (JSON-LD, citations)
- TypeScript parser/writer library
- Web-based viewer
- Basic editor integration
- Conversion tools (PDF, DOCX import/export)
- CLI tools (validate, sign, verify)
- Standards body submission
See CONTRIBUTING.md for guidelines.
This specification and all associated code are licensed under the Apache License 2.0. See LICENSE for details.
This specification draws inspiration from:
- PDF (ISO 32000) for document packaging concepts
- Portable Text (Sanity) for semantic content modeling
- EPUB for reflowable document structure
- CRDTs (Yjs, Automerge) for collaboration patterns
- Git for content-addressable storage and hash chain lineage
- Merkle trees for efficient integrity proofs
- OpenTimestamps for decentralized timestamp anchoring
