A document format from The Augmented Text Company and the Future Text Lab.
Origami Text is a way of publishing documents that keeps two promises at once. The first promise is to every reader: an Origami Text document is an ordinary EPUB, deliberately kept plain, so it opens in Apple Books, calibre, or any other EPUB reader and simply looks like a clean, well-set book. The second promise is to software: folded inside that plain book is rich, structured metadata that any program can extract in a few lines of code — who wrote the document, how to cite it, what its headings, references, glossary terms and notes are, and even where its ideas sit in space.
The name reflects the idea. Like a sheet of paper, the document gains its structure from its folds — and unfolds back into something simple.
What a reader sees
A book. Nothing more. Origami Text restricts itself to a small set of familiar elements — headings, paragraphs, quotations, figures, lists, tables, footnotes — precisely so that there are no rendering surprises between reading systems. The document ships with one minimal stylesheet, and reading apps are expected to replace it entirely with their own themes, including dark mode. Footnotes appear as popovers in readers that support them, and as visible notes after the paragraph in readers that don’t. Nothing is ever hidden or unreachable.
What software sees
Inside the EPUB sits a single file, origami.json, holding everything the document knows about itself. The same data is embedded a second time inside the first page’s HTML, so even if someone unzips the EPUB and keeps only one file, the document still carries its own metadata. The two copies are always equal in value.
The metadata covers, in one place: the document’s identity — its title, authors, date, a persistent document ID, and a ready-to-copy BibTeX self-citation so citing the document is one paste; its structure — every heading with its level and a stable ID; its references — full BibTeX and CSL data for every citation in the text, keyed so a program can connect the citation in the prose to its source; its glossary — the defined terms and their definitions; its notes — footnotes and endnotes with the paragraphs they belong to; and its spatial layout — normalized positions from the Map view in Author, so a document’s concept map travels with it and can be reconstituted on a flat screen or in spatial computing.
Extracting all of this takes very little. Unzip the EPUB and parse one file:
const zip = await JSZip.loadAsync(epubBytes);
const meta = JSON.parse(await zip.file("OEBPS/origami.json").async("string"));
console.log(meta.document.title, meta.document.bibtex);
And if all you have is the HTML file, the embedded copy is written so that even the crudest extraction works — a regular expression and JSON.parse yield exactly the same data:
const m = html.match(/<script[^>]*id="origami-metadata"[^>]*>([\s\S]*?)<\/script>/);
const meta = JSON.parse(m[1]);
Identity that survives editing
Every Origami Text document carries three levels of identity, and the difference between them is what makes links durable. The document ID names the document itself and never changes, no matter how many times it is edited and re-exported. The digest is a fingerprint of the text of one particular revision, computed by a precisely defined algorithm, so software can tell whether two files contain the same words. And every heading and paragraph carries its own stable IDthat survives edits elsewhere in the document.
Together these make addresses that outlive both edits and file moves: a link to a paragraph records the document ID, the revision it was made against, and the paragraph’s ID. If the document has since been revised, the reader is told so — and the link still resolves, because the paragraph’s identity persists. A citation should point at an idea, not at the accident of where a file happened to live on the day the link was made.
An open format
Origami Text is deliberately unfinished at the edges. The specification defines what the metadata blocks mean, but unknown blocks and extension data are accepted and reported, never rejected — new kinds of information can be added to documents without anyone’s permission. Annotations follow the same spirit in a different direction: they are overlays that point at a document rather than marks inside it, aligned with the emerging W3C EPUB Annotations standard, so notes and highlights can be private, shared, or published without ever altering the text they discuss.
The format is currently an unversioned draft: it will change freely until we are happy with it, and only then be released.
Check a document
The Origami Text Validator on this site checks any file against the format, entirely in your browser — nothing is uploaded. Errors mean a file cannot be read as Origami Text at all; warnings mean it is valid but missing some of the riches; everything unknown is merely noted, because openness is the rule. The validator also shows you the metadata it extracted, including the copyable citation — a small demonstration of the format’s central claim.
For implementers
The normative specification is the Origami Text Profile, published alongside the validator, a fully conforming sample document, and a set of digest test vectors that any implementation must reproduce byte-for-byte. Origami Text export is being built into Author, our writing application, and import into Reader. If you build your own tools on the format, we would genuinely like to hear about it.