Versioning & conformance
What you can rely on today
The format and its SDKs run on different clocks, and the rules in this
chapter govern only the first. A document's coffeejson version says nothing
about a package's API version.
| Surface | Status | What that means for you |
|---|---|---|
The wire format (coffeejson: "1.1") |
Early, one implementation | The shape is settled and validated against a fixture corpus. Fields may still be added; the meaning of a defined field will not quietly change. |
The JSON Schema at its $id |
Stable address | https://coffeejson.org/schema/1.0 keeps resolving, re-published in place as 1.x grows — see The published schema. |
@coffeejson/core, @coffeejson/react, coffeejson-swift |
Semver, versioned apart | Reference implementations that track the format while it can still change in place. Each releases on its own number, which its registry and its changelog name. A breaking API change is a major bump; a format change in place ships as a package release. Each package states its own coverage in its README. |
While CoffeeJSON has one implementation the format may still change shape in place. See Evolving 1.x in place for what that latitude covers and when it ends. If you build during that window, pin a copy of the schema. The changelog and the dated schema snapshots are the signal.
Versioning
The coffeejson envelope field carries the semantic version
of the specification a document conforms to.
While the format evolves in place, the rules in this section describe where 1.x is going, not what binds today. Read that section first. From first outside adoption these rules bind unconditionally.
- Within a major version, every change is additive and optional.
New optional fields and new enum values can be introduced. Consumers ignore
what they do not recognize (the forward-compatibility
contract). A document valid against
1.0remains valid against1.x. - A breaking change bumps the major version. Removing a field, changing a
field's type, repurposing a value, or making an optional field required are
all breaking and would produce
2.0. - The minor version increments when additive features are introduced.
- The specification text carries a patch component as well, as in
1.1.0. A patch release fixes wording only and never changes the data model. A document declaresmajor.minoronly, so a patch release does not change the version a document declares.
The required-unit trap. A new unit is only
additive for optional measurements. A consumer treats an unrecognized
unit as absent (Conformance). That is harmless on an
optional field like water_temp, but on a required measurement it
deletes the field. If a 1.2 added kilogram and a producer emitted it for
coffee, every 1.1 consumer would read that recipe as having no dose at
all, which is unusable despite "additive" versioning. So a minor can add
units usable on optional measurements. A unit intended for a required
measurement (coffee, water, yield) is a breaking change in effect and
waits for a major. The alternative, a producer that emits the 1.0 unit beside its
preferred one, is not modeled. Emit required measurements in the units 1.0
defines. milliliter on water is the one such unit 1.0 itself defines.
The required-quantity trap. basis
generalizes the same hazard to structure. A new basis value changes which
required quantity a recipe states, so an older consumer reads such a recipe
as missing its brew quantity entirely. A new basis value is breaking in
effect and waits for a major. A consumer that meets an unknown one anyway
derives the effective basis from the quantities present
(Vocabularies § basis).
Evolving 1.x in place
CoffeeJSON 1.x has a single known implementer and no second consumer to keep
compatible. While that holds, the format can change shape in place, and that
includes relocating or removing a field. No back-compatibility shim ships with
the change. A breaking change ships as the next minor, and its
changelog entry says Breaking. 2.0 is kept for a
fundamental change to the format. The schema $id stays
https://coffeejson.org/schema/1.0, because it names the major line. This
latitude ends at first outside adoption. After that, the rules above apply
unconditionally.
Documents minted by that implementer exist in the wild. A change in place costs a migration of whatever that producer serves, and the cost grows with every document minted. It is still the right call while a better design is available.
The published schema
The JSON Schema published at its
$id is a producer gate for the current minor. It validates what a
producer can emit today, which includes rejecting vocabulary values a newer
minor may later define. Each minor re-publishes the schema at the same
$id with the union of that major line's values, so the producer-visible
gap is bounded by release cadence. It is never an inbound import gate. A
consumer MUST NOT reject a document because it fails schema validation on
vocabulary values introduced by a newer minor. The fallback
rules govern import.
An authoring variant
(coffeejson-1.0.authoring.schema.json)
is generated from this schema and published at its own $id
https://coffeejson.org/schema/authoring/1.0. It closes every object except
the reserved ext member, which a
localization refuses too, requires optional
arrays to be non-empty, requires
bean_ref on every recipe once a document carries
more than one bean, and rejects brand and model on a
Gear object whose id the gear registry carries.
It catches four producer mistakes: a typo'd field name, which the open runtime
schema accepts silently; an empty emission that a producer omits instead; a
recipe left unlinked when a second coffee joined the document and
co-location stopped associating
anything; and a brand or model copied beside a known gear id, which a
producer SHOULD omit because the registry is authoritative for both and
the copy only drifts from it. Each of those is a document the runtime schema
accepts, and an unreferenced recipe is a state the envelope defines. It is a strict
producer lint, never a conformance or import gate.
Reserved extensions
Some growth areas are named but not defined in v1.1. Naming them means each can be added within the 1.x line without a breaking change. A producer MUST NOT emit reserved fields as if they were defined in v1.1. A consumer that meets an unknown member ignores it, per the forward-compatibility contract.
A professional cup-scoring module. The consumer half of this is in v1.1. The Tasting entity carries a drinker's rating, the perceived extraction/strength axes, flavor descriptors and a measured
tds. That completes the small composable graph (recipe ↔ bean ↔ tasting). A tasting is distinct frombean.roaster_notes. Notes are the roaster's attributed claim. A tasting is one drinker's evaluation of one cup.What stays reserved is the professional layer: a panel that scores coded samples on a named system. That system is the 2004 cupping form, the 2024 Coffee Value Assessment, or a house scale. It is not a field the Tasting object is missing but a different artifact, with a different author, cardinality and audience. It also cannot be carried honestly as a bare number. The same attribute scores 6–10 in quarter points on one system and 1–9 on another. A score without a declared system is a number a consumer can only misread. A scoring module names its system, its attributes and its scale, or it does not ship.
Pressure / flow profiling. The espresso model itself is whole in v1.1: method id,
basis,yield,pressure,preinfusion_s,basket, and thedistribute/tamp/pullstep kinds (Recipe § Espresso). What stays reserved is the dynamic layer: a named, multi-phase, machine-executable pressure or flow profile (Decent-style shot files, a roaster's named preset). v1.1 carries the nominal numbers and free-text phase instructions. A structured profile object waits for real consumer pull.Descriptor normalization. Aligning
roaster_notes(and a futuretasting) to the Coffee Taster's Flavor Wheel lexicon — the Specialty Coffee Association and World Coffee Research artifact, which names both bodies on its face — so sensory descriptors become comparable across producers instead of free strings.A water profile. A structured brew-water specification: TDS/hardness targets or a named mineral profile ("60 ppm", Third Wave Water). It is the one brew variable recipes state that v1.1 does not model. Water travels only as mass and temperature. Waits for a producer/consumer that exchanges it.
A vendor-extension member
ext. The named home for third-party data, distinct from every other entry here, which reserves a future first-party shape. An application with private data that belongs in the document SHOULD NOT invent bare members on entities this specification defines. It SHOULD carry the data underext, keyed by a vendor identifier ("ext": { "app.example": { … } }), or propose the field for the format itself.extcontents are vendor-defined by construction, so it is the one reserved name whose use is permitted today. Emitting it does not pretend a v1.1 definition exists. The payoff is a clean growth path. A vendor field that proves out can be promoted to a defined optional field in a later minor, while the originalextdata stays valid vendor data. Nothing renames. The full mechanism (identifier grammar, promotion process) is defined when a real adopter needs it. Until then the reservation is the convention.
The version gate
A consumer decides support by the major component of coffeejson:
| Document major | Consumer behavior |
|---|---|
| Older or equal, supported | Process normally; ignore unknown fields. |
| Same major, newer minor | Accept; rely on forward-compatibility. |
| Newer major | MAY reject. SHOULD show a clear "unsupported version — please update" message rather than failing opaquely. |
A consumer MUST NOT silently misinterpret a newer major version as if it were its own.
Media type
The reserved media type for a CoffeeJSON document is:
application/vnd.coffeejson+json
The +json structured-syntax suffix signals that the payload is JSON and can
be processed by generic JSON tooling. Registration of this media type is
reserved for when the format is published. Until then it is the recommended
type for Content-Type headers and file associations.
File extension
CoffeeJSON reserves no dedicated file extension. A CoffeeJSON file is a
plain .json file that contains exactly one CoffeeJSON
document, in any envelope shape: a recipes array, a
beans array, or both. Type association happens through the
media type, not the extension. See
Transport for file, URL, and QR bindings.
Conformance
Conformant document
A document is conformant to CoffeeJSON 1.1 if:
- It is a JSON object with a
coffeejsonstring whose major version is1. - It contains at least one of
beansorrecipes, present and non-empty (the envelope rule). - Every Recipe in
recipeshas the requiredtitleandcoffee, plus itsbasis's stated brew quantity. That iswaterorratioforbasis: "water"(or absent, the default) — each fixes the other against the dose. Forbasis: "yield"it isyieldinstead, with neitherwaternorratio(Recipe § Espresso). Each typed field that is present matches the type given in Recipe / Bean.
Unknown members at any level do not make a document non-conformant. The forward-compatibility contract explicitly permits them.
The smallest conformant document is the minimal valid document.
Conformant producer
A producer is conformant if every document it emits is conformant and it
obeys five rules. It emits required fields. It emits URL-valued fields in
URI form (punycode hostname, percent-encoded path, the form a browser's
address bar copies out). It emits the linking members — id, bean_ref,
recipe_ref — in Unicode NFC normalization, which is load-bearing for the
byte-exact bean_ref ↔ id match, and SHOULD emit human-text strings in NFC
too (Envelope §
Association). It serializes
derived step labels as absent. It does not emit reserved
fields (Reserved extensions) as if they were defined
in v1.1.
Conformant consumer
A consumer is conformant if it:
- accepts every conformant document of a supported major version;
- ignores unknown members and maps unknown enum values per each vocabulary's rule, and never rejects a document because it fails schema validation on values from a newer minor (The published schema);
- converts any recognized unit to its own canonical store and treats an unrecognized unit as absent;
- preserves step array order and shows, rather than fails on, step kinds it does not model;
- never depends on the informational
generatorfield.
While the format evolves in place, a consumer that stores documents SHOULD record the minor it read them under. A minor can still relocate a field during that window, and the changelog marks such a release Breaking.
A consumer MAY also validate against the JSON Schema, but the prose specification is authoritative where the two differ.
Two RECOMMENDED behaviors complete the picture. When a consumer re-emits a document it did not author, it SHOULD preserve the members it did not recognize. See Overview § Preservation on re-share for the round-trip / re-author distinction. A consumer that scans QR codes or accepts links SHOULD attempt payload extraction on any host's URL, not only its own. See Transport § Accepting links from any host, which the fixture corpus backs with executable scan vectors.
Registry governance
The open registries (gear, varietal, addition type,
producer role) are curated data maintained beside this specification as plain
JSON (registries/gear.json, registries/varietals.json,
registries/addition-types.json, registries/producer-roles.json, each served
from the canonical host). Their governance is lightweight by design:
- Adding an entry is a data change, not a spec change. A new gear slug, a
varietal alias or a recommended token does not bump the
coffeejsonversion. Producers and consumers that have not yet synced the registry fall back per the vocabulary's rule, so nothing breaks. - Ids are stable. A published slug never changes its meaning, and a removed slug is never used again. A correction for a misspelled or misnamed slug adds the right slug and keeps the old one as its alias. A per-variant slug that is folded into its family is removed. It does not become an alias of the family slug, because the family slug does not identify the variant (Gear registry). A consumer treats a removed slug as an unknown id.
- Country codes are not curated here. They track ISO 3166-1 directly.
If CoffeeJSON becomes a shared standard, extracting these registries into a neutral, contribution-friendly repository is the natural first governance step.
Reporting a problem
Ambiguity in this specification is a bug. If two reasonable implementers could read a sentence differently, that is worth an issue. The fixture corpus exists so a disagreement can be settled by a test rather than by an argument.