CoffeeJSON documentation
The normative specification, the transport binding, and the guides that apply them. Where a guide, an example, or the JSON Schema disagrees with the specification prose, the prose wins.
Specification
Read in order; each chapter is self-contained enough to cite on its own.
- Overview — scope, the three entities, design principles, and the conformance language (MUST / SHOULD / MAY).
- Document envelope — the
coffeejsonversion marker plus thebeans,recipes, andtastingscollections. - Recipe — the brew-parameters entity: Measurement, Gear, Grind, and Step.
- Bean — the coffee-identity entity: Origin, OriginItem, process, varietals, and roast attributes.
- Tasting — how a brewed cup turned out: attributed impression and instrument reading, kept apart.
- Vocabularies & registries — every controlled vocabulary, the two open registries (gear, varietals), and the fallback rules.
- Versioning & conformance — versioning, media type, conformance targets, registry governance.
Transport binding
- Transport — a document as a file, inside a share URL,
or in a QR code. Normative for the binding only. The data model defines no
transport, and an implementation may ignore the binding entirely. Its share-URL
rules are executable as
fixtures/transport/scan-vectors.json.
Guides (non-normative)
- Integration guide — the consumer and producer checklists, in build order.
Schema
schema/coffeejson-1.0.schema.json— JSON Schema (Draft 2020-12). It permits unknown properties, because consumers MUST ignore unknown fields (Overview § Forward compatibility).schema/coffeejson-1.0.authoring.schema.json— the strict, generated producer-lint variant (Integration guide § Lint your output). Never an import gate.../fixtures/— the conformance corpus.pnpm testvalidates it, and every complete JSON example in these docs, against the schema.