CoffeeJSON v1.1 — Overview

CoffeeJSON is a JSON document format for a coffee brew and the coffee it was made from. A document travels between applications, languages, and locales without loss.

This text is version 1.1.0 of the specification. A document declares "1.1", because the wire value carries the major and the minor only (Envelope § coffeejson). The format is early and still open to change in place (Versioning § What you can rely on today). The format is small on purpose. Reserved areas for future growth are named in Versioning § Reserved extensions.

Why CoffeeJSON exists

CoffeeJSON rests on a simple belief: coffee gets better for everyone when brewing knowledge can travel. A good recipe — a roaster's, a champion's, a friend's — stops being useful the moment it is trapped in a screenshot, a blog post, or one app's private database. When the same recipe moves cleanly between apps, languages, and even the bag of beans it was written for, more people brew well and more people enjoy what they drink; drinkers, roasters, cafés, app makers, and gear makers build on each other's work instead of re-typing it. The format is the small, shared, boring thing that makes this possible — and growing it is meant as a contribution to the coffee industry, not a land grab inside it.

Scope

CoffeeJSON defines two co-equal top-level entities, plus a third that evaluates them. Each is carried as an array collection:

A document carries a beans array, a recipes array, or both. At least one of the two is present and non-empty. tastings does not satisfy that rule, because a tasting evaluates something the document must also carry. There is no singular key. A single coffee or recipe is an array of one. The envelope wraps the collections with a version marker.

When a beans array holds one coffee beside one or more recipes, those recipes are for that coffee by co-location. This is the bag-to-brew case, and it needs no identifier. A multi-coffee catalog pairs each recipe with its coffee explicitly: the bean carries an id and the recipe a bean_ref (see Envelope § Association).

CoffeeJSON does not define a transport. A document is JSON, and you can save it to a file, embed it in a URL, or encode it in a QR code. Recommended bindings are described in the supporting document Transport. They are not part of the core data model.

What CoffeeJSON is not

Design principles

Two kinds of principle run through CoffeeJSON: how the data is modeled, and how the format is adopted and grown. The first four drive nearly every field-level decision. The last five drive what gets added, what gets refused, and how easy the format is to adopt.

How the data is modeled

  1. Fact, claim, and opinion are distinct. Every piece of information is one of three tiers, and each tier is encoded differently:

    Tier What it is Where it lives Encoding
    Measured fact reproducible with a scale, a thermometer, and a timer Recipe quantities, times, per-step to_water; a Tasting's measured values with canonical units
    Declared claim what the roaster states Bean identity fields; the recipe's recommended normalized to queryable forms (ISO country, meters, Agtron, ISO date) — claimed, never verified
    Attributed opinion a sensory impression, a rating roaster_notes and description; a Tasting's rating, perceived, descriptors always attributed to its source; never asserted as bare fact

    A descriptor is never promoted to a claim, and a consumer MUST NOT merge one source's descriptors with another's. A rating attaches to a cup (Tasting), never to a coffee. A Tasting carries fact (measured) beside opinion (perceived) in separate members, so neither is rendered as the other. A field that is none of the three is personal state and does not belong in the format (principle 4).

  2. Locale-neutral on the wire, localized at the edges. Everything enumerable travels as a stable, language-independent machine id: methods, processes, roast levels, countries, gear, varietals. Each consuming application renders its own localized display string from that id. Human free text, such as a title or a custom step note, travels as written with an optional lang hint.

  3. Canonical unit identifiers. Measurement units travel as semantic, locale-neutral identifiers such as gram, ounce, celsius, fahrenheit, meter, and foot. They never travel as display symbols such as g, oz, °C, or °F. Producers MUST emit these canonical identifiers, and consumers MUST localize display at the edges.

  4. Identity, not inventory. The format carries a coffee's identity (origin / process / roast) and a brew's parameters. Three kinds of thing stay out, and roasters publish all three:

    • Personal and inventory state — a bag's weight, a purchase date, a drinker's own rating. If a field only makes sense for one owner at one moment, it does not belong here.
    • Commercial state — price, green cost, lot size, stock status, cups per bag, a supplier-pay grade. These are facts about a transaction, not about the coffee, and they go stale the moment the bag is sold.
    • Third-party judgments — a cup score, a competition placement, a traceability grade. They are someone's evaluation rather than the coffee's identity. A scored cup evaluation is a separate entity, reserved by name in Versioning § Reserved extensions.

    The test that decides all three: would this still be true, and still about this coffee, a year from now in someone else's hands?

How the format is adopted and grown

  1. Portable and drop-in. A document is just JSON: no backend, no account, nothing that has to phone home. It saves to a file, rides inside a share URL, or prints as a QR code. A typical recipe is a few hundred bytes, small enough to travel inside the link itself, compressed or not (transport). CoffeeJSON defines no transport of its own, so it drops into whatever channel an application already has.

  2. Incremental to adopt. Implement a little or a lot. The smallest valid document is a title and two measurements. Everything richer is optional: method, grind, steps, a beans collection beside the recipes. A useful integration is an afternoon's work, and it can deepen later without a rewrite of what came first.

  3. Extensible, never breaking. The format grows additively. New optional fields and reserved areas (Versioning § Reserved extensions) arrive within a major version. Consumers MUST ignore what they do not recognize rather than fail, so a document that is valid today stays valid as the format grows. The precise consumer obligation is the forward-compatibility contract. (While there is one implementation the format may still evolve in place — Versioning § Evolving 1.x in place. From first outside adoption this principle binds unconditionally.)

  4. No lock-in. CoffeeJSON is CC0 public domain: the spec, the schema, the fixtures, the registries, and the corpus's structure and transcription. Quoted roaster prose in corpus documents remains the quoted source's, attributed. The registries are open, and the ids are vendor-neutral, so nothing in a document encodes one implementation's private scheme. What one implementation writes, any other can read. What a user shared, they can always get back. The format traps no one.

  5. Minimal — resist overengineering and overgeneralization. Model what is real, common, and verifiable. Reserve the rest by name (principle 7) instead of half-building it. Refuse abstractions that would emit confidently-wrong data. The format captures a grind setting as stated. It does not convert one grinder's scale to another's. A small format that ships and interoperates beats a general one that does neither. When in doubt, leave it out. An optional field can always be added later, but it can never be cleanly removed.

Conformance language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in RFC 2119 and RFC 8174. They carry their special meaning only when in ALL CAPITALS.

Two roles are referenced throughout:

A single application is usually both. Requirements are stated against the role they constrain. Where a requirement is unqualified, it applies to both.

The forward-compatibility contract (summary)

The rule from principle 7 (extensible, never breaking) governs how every consumer behaves, so it is restated here as a contract:

Preservation on re-share

The contract above governs reading. On the way back out, when an application emits a document that carries data it did not author, two cases differ. The rule is to be honest about which one is happening: