Layer 1
The deck format
JSON. The data. A flat, readable envelope: a title, a theme, and an ordered array of slides, each one naming its type. No server ids, no timestamps, no storage leftovers. You can open it in a text editor and understand it.
Format spec
A deck is a file you own, in a format anybody may implement
Deckyard stores presentations in a format that is written down, versioned, and free to implement. Not an export option bolted on afterwards; the shape the software works in.
Two layers, and the difference matters
The question people ask first is whether a deck is "some JSON" or "the zip". It is both, one inside the other, and each answers a different need.
Layer 2
The deck package
ZIP. The data plus its pixels. The same envelope with every local image carried alongside it, addressed by the hash of its own bytes. It renders offline, on a machine that has never seen the server it came from.
Why it is written down
A presentation tool that keeps your work in a shape only it understands has made a claim on your work. Everything follows from that: whether you can leave, whether a script can read your decks, whether an archive can keep them, whether anyone else could ever build something that opens them.
Deckyard is open source, so the implementation was always inspectable. That is a weaker promise than this one. Code tells you what a program does today; a spec tells you what a file means, which is what you need when the program is gone.
What is actually unusual about it
Plenty of tools export JSON. Three things here are harder to find, and each one is checkable rather than claimed.
-
01
One source for the editor, the validator, the schema and the agent
A slide type declares its fields once. That declaration builds the form in the editor, validates the content, generates the JSON Schema, and is what an LLM is handed over MCP. This is not a spec written alongside an implementation and drifting from it; it falls out of the implementation, and CI holds the two together.
-
02
Semantics, not geometry
A deck says "a timeline with four milestones", never "a text box at 312.88pt". That is why one deck can render responsively, export to HTML and PDF, and take a different theme without being redrawn. It is also why a machine can reason about it, and why the same type contract a human sees in the slide picker is what a model receives.
-
03
Degradation is specified, not accidental
An unknown slide type does not throw. It imports as a placeholder that names the type it could not find, says whether the type was retired and what replaced it, and carries the original content across as text. A missing image becomes a dangling reference, not a crash. That is what makes it safe to build a second implementation.
Status
What is settled, what is promised, and how far the conformance goes today.
- Envelope version
- Version 1. It has not changed, and a breaking change to the envelope shape would bump it and come with a migration path.
- Content shape
- Versioned separately, under its own schema version (4 today), with a migration runner and a lenient read contract. New keys are additive; old decks keep opening.
- Implementation
- The reference implementation is Deckyard itself, MIT-licensed. The specification text carries its own licence, CC0-1.0, so a second implementation can lift the wording into its own document without asking. Nothing about reading or writing this format requires permission, a key, or a fee.
- Conformance
- Two levels, written down: level 1 is the envelope and the six structure contracts, level 2 adds the nine normative slide types. Neither grows when a slide type is added.