Document envelope

A CoffeeJSON document is a JSON object with a single version marker plus three OPTIONAL array collections: beans, recipes and tastings. At least one of beans or recipes must be present and non-empty.

{ "coffeejson": "1.1", "recipes": [ /* one or more Recipe */ ] }
{ "coffeejson": "1.1", "beans": [ /* one or more Bean */ ] }

Fields

Field Type Req? Notes
coffeejson string yes The schema version of the format itself (semver). See below.
beans array of Bean cond.¹ Zero or more Bean objects. One element shares a single coffee; several form a catalog / lineup. Omit when empty.
recipes array of Recipe cond.¹ Zero or more Recipe objects. One element is a share; several are a library export. Omit when empty.
tastings array of Tasting no Zero or more Tasting objects — how a brewed cup actually turned out. Each rides with the recipe it evaluates. Omit when empty.
generator object no The software that wrote this document: { "name": string, "version": string, "url": string (URI) }, name required. Informational; consumers MUST NOT depend on it. See below.

¹ A document MUST contain at least one of beans or recipes, present and non-empty. A document with neither, or with only empty arrays, is invalid, and a consumer SHOULD reject it. There is no singular bean or recipe key. A single coffee or recipe is an array of one element.

tastings does not satisfy that rule. A tasting evaluates something, so a document that carries only tastings describes nothing a consumer can act on. It is invalid for the same reason an empty document is.

Every element of beans, recipes and tastings MUST be a JSON object. A collection holding anything else — null, a number, a string, a nested array — is malformed. Such an element is not an unknown member the forward-compatibility contract tells a consumer to ignore; it is a slot that claims to hold an entity and does not. What a consumer does next depends on its role. One that imports into a store SHOULD reject the document and name the collection. One that only renders MAY skip the element and render the rest. Both are conformant, and a consumer picks by its role.

Why always-array, not singular + plural

CoffeeJSON exposes each collection as only an array. There is no singular key beside a plural one, and no field that is sometimes an object and sometimes an array. A shape that varies by cardinality forces every consumer to branch (is it one or many?) before it can use the data, the known rough edge of HAL's _embedded. With one fixed shape, a strongly-typed consumer decodes the document as a plain three-collection structure (beans: [Bean], recipes: [Recipe], tastings: [Tasting]) with no discriminator and no polymorphism. "The single one" is the first element. This also follows BeerJSON, whose collections are only arrays and whose only scalar is the version marker.

coffeejson

coffeejson names the version of the specification a document conforms to. This follows the convention, shared with OpenAPI and BeerJSON, where the root marker names the spec and its version. It is not a per-recipe revision number, and it is not a property of any individual recipe.

The value is a semantic version with a major and a minor component only. A document that uses a member added in 1.1, such as variant on the Gear object, declares "1.1". A document that uses only 1.0 members can declare "1.0" or "1.1". A marker outside the MAJOR.MINOR form, such as a bare major ("1"), a patch component ("1.0.0") or a leading zero on the major ("01.0"), names no major, and a consumer reports it as an unsupported version. A consumer determines support by the major component:

While the format evolves in place, a minor can still relocate a field, so a consumer that stores documents SHOULD record the minor it read them under.

generator

generator records what software emitted this JSON: its name, its version, and optionally its own URL. name is required, because a generator that does not name the software states nothing. version and url are optional. url must be a well-formed URI.

The emitter need not be an application. A hosted service, a build script, a command-line tool, or a language model can write a CoffeeJSON document. Each of them names itself in the same member.

{
  "coffeejson": "1.1",
  "generator": { "name": "ExampleBrewApp", "version": "2.3.0", "url": "https://example.com/brewapp" },
  "recipes": [
    { "title": "Weekday V60", "coffee": { "value": 15, "unit": "gram" }, "water": { "value": 250, "unit": "gram" } }
  ]
}

It is informational only. A consumer MUST NOT change how it imports a document based on generator. It MAY show it, for example as an "Imported from …" marker. Nothing in the format depends on it. A document that omits it is in no way lesser, and most are written by hand.

Why it sits on the envelope. A file is written once, by one program. Which software serialized it is a fact about the document, not about any recipe or coffee inside it. A three-recipe export would otherwise repeat an identical value three times. A document that carries only beans would have nowhere to put it. This follows Atom's <generator>, which identifies the agent that produced a feed and sits on the feed rather than the entry. It also follows schema.org, which attaches document provenance to the top-level CreativeWork.

Distinct from the two attribution fields. Both stay on the Recipe because they vary between recipes in one document. based_on is where a recipe was published, and author is who devised it. generator is neither. Software that exports someone else's recipe is not its author and not its publisher. See Recipe § Attribution.

Single vs. multiple recipes

The recipes array does two jobs. Only the number of elements tells them apart:

A consumer MUST parse the recipes array whatever its length. It SHOULD report how many recipes it found rather than fail silently.

Single vs. multiple beans

beans mirrors recipes exactly. It is the same array, told apart by length:

A blend is still one Bean, one element of beans. It is expressed as an origin of type: "blend" with several items. A multi-element beans array means several distinct coffees, never the components of one blend.

{
  "coffeejson": "1.1",
  "beans": [
    { "name": "Nano Challa", "roaster": { "name": "Example Roastery" }, "process": ["washed"], "roast_level": "light_medium" }
  ]
}

A beans catalog is the same Bean object, several times over:

{
  "coffeejson": "1.1",
  "beans": [
    { "name": "Nano Challa", "roaster": { "name": "Example Roastery" }, "process": ["washed"] },
    { "name": "Las Brisas",  "roaster": { "name": "Example Roastery" }, "process": ["natural"] }
  ]
}

Association (co-location)

When beans holds exactly one element beside a non-empty recipes array, every recipe without a bean_ref is for that one coffee: the bag together with the way to brew it. This is the bag-to-brew case. The association is by co-location alone. Because there is a single bean, no identifier and no reference are needed (beans.length == 1 is the trigger). An explicit bean_ref, when present, always takes precedence. See Association (explicit reference).

{
  "coffeejson": "1.1",
  "beans": [
    {
      "name": "Nano Challa",
      "roaster": { "name": "Example Roastery" },
      "process": ["washed"],
      "roast_level": "light_medium"
    }
  ],
  "recipes": [
    {
      "title": "Roaster's V60",
      "method": "pour_over",
      "coffee": { "value": 15,  "unit": "gram" },
      "water":  { "value": 250, "unit": "gram" }
    }
  ]
}

That single bean can carry several recommended recipes. They are all for that one coffee:

{
  "coffeejson": "1.1",
  "beans": [ { "name": "Nano Challa", "roaster": { "name": "Example Roastery" } } ],
  "recipes": [
    { "title": "V60",       "method": "pour_over", "coffee": { "value": 15, "unit": "gram" }, "water": { "value": 250, "unit": "gram" } },
    { "title": "AeroPress", "method": "aeropress",  "coffee": { "value": 14, "unit": "gram" }, "water": { "value": 220, "unit": "gram" } }
  ]
}

Association (explicit reference)

Co-location resolves the association only when beans has one element. A beans array of two or more elements together with recipes cannot be read from position. Which recipe belongs to which coffee needs an explicit reference: an id on each referenced bean, and a bean_ref on each recipe that belongs to a specific coffee.

{
  "coffeejson": "1.1",
  "beans": [
    { "id": "nano-challa", "name": "Nano Challa", "roaster": { "name": "Example Roastery" }, "process": ["washed"] },
    { "id": "las-brisas",  "name": "Las Brisas",  "roaster": { "name": "Example Roastery" }, "process": ["natural"] }
  ],
  "recipes": [
    { "title": "Nano Challa V60", "bean_ref": "nano-challa", "recommended": true,
      "method": "pour_over", "coffee": { "value": 15, "unit": "gram" }, "water": { "value": 250, "unit": "gram" } },
    { "title": "Las Brisas French Press", "bean_ref": "las-brisas",
      "method": "french_press", "coffee": { "value": 30, "unit": "gram" }, "water": { "value": 500, "unit": "gram" } }
  ]
}

For each recipe, association resolves by one rule: an explicit reference wins, and co-location covers the single-bean case.

  1. If the recipe carries bean_ref, it is associated with the bean whose id equals that value, an exact, case-sensitive string match. If no bean matches, the recipe is associated with no bean. An unresolved reference is never an error, and there is no fall-back to co-location, because an explicit reference wins even when broken. A validator SHOULD warn. Because the match is byte-exact, producers MUST emit id and bean_ref in Unicode NFC normalization form. The same visible string in two normalization forms (a name with a combining accent, say) would otherwise silently fail to link. Producers SHOULD emit all human-text strings in NFC.
  2. Otherwise, if beans holds exactly one element, the recipe is associated with that bean by co-location.
  3. Otherwise, the recipe is associated with no bean.

Every id present MUST be unique within beans (Bean § id). If several beans share an id, the document is malformed. A consumer MUST NOT fail and SHOULD treat references to that id as unresolved.

A multi-element beans array whose recipes carry no bean_ref remains a valid document, and a consumer MUST NOT treat it as an error. It imports the beans and recipes as independent entities and draws no links between them, per the forward-compatibility contract.

Association (a tasting's recipe and coffee)

A Tasting points at what it evaluates. It resolves its recipe and its coffee independently.

The recipe is resolved by recipe_ref alone: the recipe whose id equals that value, an exact, case-sensitive match, with the same NFC requirement as every other reference in this format. An unresolved recipe_ref leaves the tasting unlinked. A consumer MUST NOT fail, and SHOULD warn. There is no positional fall-back. A tasting with no recipe_ref names no recipe.

The coffee resolves by the same two-step rule the recipes use: an explicit reference wins, and co-location covers the single-bean case.

  1. If the tasting carries bean_ref, it is associated with the bean whose id equals that value, exactly and case-sensitively. This holds even when the referenced recipe names a different bean. See below.
  2. Otherwise, if beans holds exactly one element, the tasting is associated with that bean by co-location.
  3. Otherwise, the tasting is associated with no bean.

A tasting's own bean_ref wins over its recipe's. When the two disagree, the document is not malformed, and a consumer MUST NOT report a conflict. It is "I brewed your recipe with my coffee", the ordinary case for a recipe someone else published. A consumer renders the tasting against the bean the tasting names, and leaves the recipe's own association untouched.

{
  "coffeejson": "1.1",
  "beans": [
    { "id": "nano-challa", "name": "Nano Challa", "roaster": { "name": "Example Roastery" } },
    { "id": "las-brisas",  "name": "Las Brisas",  "roaster": { "name": "Example Roastery" } }
  ],
  "recipes": [
    { "id": "roasters-v60", "title": "Roaster's V60", "bean_ref": "nano-challa",
      "method": "pour_over", "coffee": { "value": 15, "unit": "gram" }, "water": { "value": 250, "unit": "gram" } }
  ],
  "tastings": [
    { "recipe_ref": "roasters-v60", "bean_ref": "las-brisas", "rating": 4 }
  ]
}

That cup followed the Nano Challa recipe but was brewed with Las Brisas. The recipe is still for Nano Challa. The tasting is about Las Brisas.

Every id present MUST be unique within its own collection, and tastings is no different from beans and recipes. Duplicates make the document malformed. A consumer MUST NOT fail and SHOULD treat references to that id as unresolved.

Minimal valid document

The smallest conformant document is a recipes array of one recipe with a title and the two required measurements:

{
  "coffeejson": "1.1",
  "recipes": [
    {
      "title": "Everyday V60",
      "coffee": { "value": 15,  "unit": "gram" },
      "water":  { "value": 250, "unit": "gram" }
    }
  ]
}

Everything else in a Recipe is optional. See Recipe for the full field set and fixtures/valid/ for richer documents.