Recipe
A Recipe describes the parameters of a brew. It is the primary entity of
CoffeeJSON v1.1. It and the Bean are the two co-equal entities at
the top level of a document, each carried in its own array
(recipes, beans). A Tasting evaluates a brew of one and is
carried in a third.
{
"title": "Sunday V60",
"method": "pour_over",
"brewer": { "id": "hario-v60", "brand": "Hario", "model": "V60", "label": "Hario V60" },
"coffee": { "value": 15, "unit": "gram" },
"water": { "value": 250, "unit": "gram" },
"ratio": 16.7,
"water_temp": { "value": 94, "unit": "celsius" },
"grind": { "grinder": { "id": "comandante-c40", "label": "Comandante C40" }, "setting": "22 clicks" },
"steps": [ /* … */ ],
"finish_s": 150
}
Fields
| Field | Type | Req? | Notes |
|---|---|---|---|
id |
string | no | Document-local name for this recipe, so one of several can be addressed. See id. |
title |
string | yes | Human text, as written by the author. Never empty. Language hinted by lang. |
description |
string | no | One- or two-sentence summary — the preview/snippet text. Distinct from notes. Human text — see lang. See description. |
method |
string (enum) | no | Brewing technique — see method vocabulary. Omit if unknown. |
basis |
string (enum) | no | Which quantity the recipe is stated in: water (default when absent — requires water or ratio) · yield (requires yield, forbids water/ratio). The structural switch; method stays descriptive. See Espresso (dose : yield) and Vocabularies § basis. |
brewer |
Gear | no | The device (V60, Origami, AeroPress…). Omit if unknown. |
coffee |
Measurement | yes | Coffee dose (mass). Recommended unit gram. |
water |
Measurement | cond.¹ | Total brew water. Recommended unit gram. Present on a water-basis recipe (basis:"water", or absent — the default); not on a yield-basis recipe. |
yield |
Measurement | cond.¹ | Beverage mass out, in the cup — the beverage a brew produces, meaningful for any method (distinct from input water). REQUIRED when basis is yield; optional otherwise. |
ratio |
number | cond.¹ | Water-to-coffee ratio (dimensionless, for example 16.7). See Ratio. |
water_temp |
Measurement | no | Brew-water temperature. Recommended unit celsius. |
grind |
Grind | no | Structured grind specification. |
pressure |
Measurement | no | Nominal peak brew pressure. Recommended unit bar. See Espresso. |
preinfusion_s |
number | no | Seconds of low-pressure pre-wetting before full pressure. |
basket |
Gear | no | The filter basket (espresso) — for example an 18 g precision basket. |
filter |
Filter | no | The brew filter — what the water passes through. See Filter. |
steps |
array of Step | no | Ordered, typed brew steps. Omit or empty for a recipe with no step guide. |
finish_s |
number | no | Seconds from start to the cue to draw down / remove the brewer — for espresso, the target shot time. |
lang |
string (BCP-47) | no | Language of the human text fields (title, custom labels), as a well-formed BCP-47 tag — en, en-US, zh-Hant-TW; hyphen-separated, so en_US is invalid. A hint only. |
author |
Party | no | Who authored this recipe — a person or organization. See Attribution. |
based_on |
string (URI) | no | Where this recipe was originally published, for a transcribed recipe. See Attribution. |
images |
array of string (URI) | no | Image URLs for the recipe/brew. Always an array; omit or empty when none. See Images & publication date. |
date_published |
string (ISO 8601 date) | no | When this recipe was first published. See Images & publication date. |
bean_ref |
string | no | The id of the bean in this document that this recipe is for. See bean_ref. |
recommended |
boolean | no | true marks this recipe as the producer's recommended brew. Omit rather than emit false. See recommended. |
notes |
string | no | Free-text prose about the whole recipe (character, tips, troubleshooting). Human text — see lang. See notes. |
additions |
array of Addition | no | Liquids added beyond the brew water — ice, milk, sugar, syrup, and more. See Additions. |
localizations |
object | no | The publisher's own translations of this recipe's human text, keyed by BCP-47 tag. Requires lang. See Localizations. |
¹ The stated brew quantity switches with basis. See
Espresso (dose : yield). A water-basis recipe
(basis:"water", or absent, the default) REQUIRES water or ratio, and
MAY add yield. A basis:"yield" recipe REQUIRES yield and MUST NOT
carry water or ratio.
coffee is always required, so water and ratio each fix the other. One of
them is enough. Recipes are commonly published as a dose and a ratio ("20 g at
1:15") with no total printed. A required water would force a producer to
compute and assert a figure the source never gave. A consumer that needs the
total when only ratio is stated derives it as coffee × ratio. A producer
that knows both SHOULD state both.
coffee is the dose, the mass of coffee. The coffee's identity (where it
is from, how it is processed) lives in the top-level Bean entity,
never in the recipe.
Ratio
ratio is the water-to-coffee ratio as a bare dimensionless number (water ÷
coffee by mass), for example 16.7 for a 1:16.7 brew.
- If
ratiois omitted, a consumer computes it fromwater/coffee. Both operands come to one mass unit — grams — before they divide, so 15 g of coffee to 8 oz of water is 1:15.1 and never 1:0.5. An operand stated by volume, or in a unit the consumer does not recognize, yields no ratio, and a window is reduced only under Stated windows. - If
ratiois present but inconsistent withcoffeeandwater, a consumer SHOULD prefer the explicitcoffee/watermeasurements and MAY recomputeratio. The measurements are authoritative. The ratio is a convenience.
ratio describes water, so it never appears on a yield-basis recipe. See the
next section.
Two further rules follow from what ratio is:
- It is a mass ratio, so it is absent when
wateris a volume. A recipe that states 13 g of coffee to 225 mL of water states no mass ratio. The format does not compute one, because that needs the density conversion Water quantity declines to define. A consumer that shows "1:17" there is showing its own arithmetic. - It is often what couples two windows. A French press guide can state
25–45 g of coffee to 375–675 g of water, because the recipe scales with the
press. When both are windows, the single ratio of 15
holds across the range.
ratiois the only field that says so. Emit it.
Scaling
A consumer that lets the user brew a recipe at a different batch size
SHOULD scale by multiplying every mass by one factor: coffee, water
(or yield), each addition's amount, and each step's cumulative to_water.
ratio is a mass quotient, so it stays invariant. Nothing else scales.
Timings (at_s, action_duration_s, finish_s), water_temp, grind, and
pressure are the author's technique, not functions of batch size, and the
format defines no rule for them. A consumer that re-times a scaled brew applies
its own brewing model. It MUST NOT present the result as the author's
schedule. A scaled document is a re-authored one. Emit the scaled masses as
ordinary values. There is no scale-factor field.
Espresso (dose : yield)
basis: "yield" switches the recipe's stated brew quantity. An espresso recipe
sets it, because espresso states what lands in the cup, not the water that
goes in. The puck retains roughly twice its dry mass, and no espresso recipe
states input water.
coffeeremains the dose in, andyieldis REQUIRED: the beverage mass out, for example 19 g in → 47 g out.waterandratioMUST NOT be present. Their definitions (total brew water, water ÷ coffee) have nothing true to say about a shot, and the schema rejects them. A yield can never masquerade as water.- A consumer shows the espresso ratio as dose : beverage, derived from the
measurements. 19 g → 47 g reads as 1 : 2.5 (
yield ÷ coffee). finish_sis the target shot time.water_tempis the brew temperature, as for any method.pressure(nominal peak, recommended unitbar),preinfusion_s(seconds of low-pressure pre-wetting), andbasket(a Gear for the filter basket) complete the shot's parameters. The espresso machine is the recipe'sbrewer, as usual.- The espresso step kinds are
distribute(WDT),tamp, andpull. See Step. The shot's numbers live at the recipe level. Apullstep carries instructions, never measurements.
{
"coffeejson": "1.1",
"recipes": [
{
"title": "Roaster's espresso",
"method": "espresso",
"basis": "yield",
"coffee": { "value": 19, "unit": "gram" },
"yield": { "value": 47, "unit": "gram" },
"water_temp": { "value": 93, "unit": "celsius" },
"pressure": { "value": 9, "unit": "bar" },
"preinfusion_s": 3.5,
"finish_s": 26.5,
"steps": [
{ "kind": "distribute", "instruction": "WDT, level the bed" },
{ "kind": "tamp" },
{ "kind": "pull", "instruction": "line pressure to 3.5 s, then 9 bar" }
]
}
]
}
For every water-basis recipe (the default) the model is unchanged. water
is required, and yield MAY also state the beverage mass out. yield is the
same universal quantity, not an espresso-specific field: a filter brew's output
is its water minus what the bed retains. A yield-basis recipe is the one that
requires yield, because it alone has no input-water figure to state.
Espresso is the motivating case.
Multi-phase pressure / flow profiles, a named machine-executable curve
(Decent-style shot files, Fellow Aiden profiles), are not modeled in v1.1. A
producer describes phases in step instruction text. Structured profiling is
reserved by name in Versioning § Reserved
extensions.
Localizations
A document is written in one language, named by lang. Some
publishers write in two. A roaster prints a Japanese bag and its own English
beside it. A barista publishes a method in their language and in English.
localizations carries those, keyed by BCP-47 tag:
{
"title": "4:6メソッド",
"lang": "ja",
"coffee": { "value": 20, "unit": "gram" },
"water": { "value": 300, "unit": "gram" },
"steps": [
{ "at_s": 0, "to_water": { "value": 60, "unit": "gram" }, "instruction": "1投目 — 甘さを決める" },
{ "at_s": 90, "to_water": { "value": 300, "unit": "gram" }, "instruction": "2投目 — 濃度を決める" }
],
"localizations": {
"en": {
"title": "4:6 Method",
"steps": [
{ "instruction": "first pour — sets sweetness" },
{ "instruction": "second pour — sets strength" }
]
}
}
}
Only wording varies. A localization carries title, description,
notes, and per-step instruction / label, and nothing else. Every
quantity, unit, enum, piece of gear, and reference belongs to the recipe
itself and is the same in every language. A translation that changed a dose
would be a different recipe with a language tag. The authoring
schema rejects any other
member. The runtime schema is open like every other object here, so a future
minor can add a text field.
lang is required when localizations is present. An overlay overrides a
base, so the base's language has to be stated. Otherwise nothing says what is
translated from. The schema enforces this.
Step wording is positional. Entry i of a localization's steps
translates step i. An empty object {} leaves that step untranslated, which
is how a publisher who translated two of four steps says so. The array
MUST be the same length as the base steps. On any other length a
consumer MUST ignore the whole array rather than pair an instruction with
the wrong pour. A misaligned instruction is worse than an untranslated one,
because it is confidently wrong. A validator SHOULD warn. JSON Schema
cannot express length equality, so this is a semantic rule.
Only the publisher's own translation belongs here. This is the same rule
that governs the rest of the format: a document states what its source stated.
A consumer or transcriber that translates text itself is authoring. It makes
word choices the publisher never made, and placing them in the publisher's
document does not make them the publisher's words. An application can
translate for display. It must not write the result back into
localizations and re-share it.
Matching. A consumer that chooses a locale SHOULD use BCP-47 lookup
(RFC 4647 §3.4) rather than exact
string equality. Then a request for en-US is satisfied by an en overlay.
With no match it renders the base fields. A consumer that ignores
localizations entirely does the same, so the field costs nothing to skip.
Attribution (author, based_on)
author credits who devised the recipe: a person or organization, in the
Party shape ({ name, url? }). It travels inside the document
itself, not as an out-of-document sidecar. Attribution must survive a
re-share. Once a recipe is copied between apps or pasted into a share URL,
only what the JSON carries is still attached to it.
based_on cites where the recipe was originally published: a URL, for a
recipe transcribed from a roaster's brew guide, a competition write-up, or a
video. Unlike author, it names a publication, not a person or
organization. So it is a bare string in format: uri, not a Party.
Three provenance surfaces answer three different questions, and none stands in
for another. author is who devised it. based_on is where it was first
published. The envelope's generator is what
software wrote this file, informational only. The first two vary from recipe
to recipe, so they live on the Recipe. generator cannot vary within a
document, so it lives on the envelope. One document can carry all three: a
recipe authored by a competition barista, based on the write-up where they
published it, exported by whatever app wrote this copy.
Images & publication date
images carries absolute image URLs for the recipe: the resulting brew,
the method in progress. It is always an array. A single image is an array of
one, and an empty array is equivalent to absent, like the other optional
arrays. The URLs are reference metadata. A consumer can render, proxy, or
ignore them, and nothing else in the document depends on them.
date_published is the ISO 8601 calendar date the recipe was first
published. It is publication metadata about the recipe as a work. It is
distinct from the coffee's roast_date and from
based_on (where it was published).
Together these map to schema.org image and datePublished. With the
recipe's name, they are the properties search-engine rich results require.
{
"coffeejson": "1.1",
"recipes": [
{
"title": "4:6 Method",
"method": "pour_over",
"coffee": { "value": 20, "unit": "gram" },
"water": { "value": 300, "unit": "gram" },
"author": { "name": "Tetsu Kasuya", "url": "https://en.philocoffea.com" },
"based_on": "https://en.philocoffea.com/blogs/blog/coffee-brewing-method"
}
]
}
- Distinct from
author.url.author.urlis the author's own page (a profile, a site, a channel).based_onis the specific place this recipe was published. That can be a different page on the same site, as above, or somewhere else entirely (a video, a third party's write-up of a competition routine). - Distinct from
generator.generatorrecords what software emitted the JSON. It is informational, a property of the whole document rather than of any one recipe. A consumer MUST NOT depend on it.based_onrecords where the recipe was first published, regardless of which app later transcribed or exported it. See Attribution for how the three surfaces relate. - Licensing is not a per-recipe field. It is handled at the corpus level,
with a repository
LICENSEplus a page declaration. It is not attached to individual recipe documents. - For structured-data consumers:
authormaps to schema.org'sauthor(PersonorOrganization), andbased_onmaps to schema.org'sisBasedOn.
id
id is a document-local name for one recipe, so that something outside
the recipes array can say which one it means. It is the recipe-side
counterpart to a bean's id: any non-empty string, unique
within the document's recipes array, compared exactly and
case-sensitively. It is never a global identifier, an account, or an
inventory key.
It exists because array position is not an identity. A publication that carries three brew methods is often re-published with them reordered. One can be added in the middle. Everything that named a recipe by its position then silently names a different one. That includes the things a reader keeps: a share link to one method of a bag, a page anchor, a re-shared import. None of those can be made durable by counting.
- Optional, and worth emitting whenever a document carries more than one recipe. A single-recipe document needs no id. There is nothing to disambiguate, and the document itself is the address.
- Producers SHOULD keep an id stable across re-publication of the same recipe. An id that changes every time the document is regenerated provides nothing that position did not.
- Uniqueness is a semantic rule JSON Schema cannot express. A validator SHOULD show a duplicate as a warning. Duplicate ids make every reference to them ambiguous. A consumer that resolves one SHOULD treat the reference as unresolved rather than guess which it meant.
- A consumer that does not care which recipe is which can ignore
id, as it can ignore any member it does not use.
bean_ref
bean_ref names the coffee this recipe is for. Its value is the
id of one element of the document's beans array, matched
exactly and case-sensitively. It is a document-local reference, never a
global identifier, an account, or an inventory key. It is only needed when a
document carries several beans. With a single co-located bean the
association is implicit. The full resolution rules, including unresolved
references, are defined in
Envelope § Association (explicit reference).
recommended
recommended: true marks this recipe as the producer's suggested starting
point. On a bag, it is the roaster's recommended way to brew that coffee.
Several recipes MAY carry it, for example one per method: the recommended V60
and the recommended AeroPress.
- It is a declared claim (Overview, principle 1): the producer's stated suggestion, never a quality assertion about the recipe.
- Absent and
falseare equivalent. Both mean no statement. A producer SHOULD omit the field rather than emitfalse. - It is document-scoped like every CoffeeJSON field. It says nothing about recipes in other documents or in a consumer's library.
description
description is the recipe's one- or two-sentence summary: what it is and
why you would brew it ("A relaxed weekend pour-over — bright, sweet, and
forgiving."). It is the preview a directory, share card, or search snippet
shows (schema.org Recipe.description).
The recipe carries four human-text surfaces, and each has one job. title
names it. description summarizes it. notes carries
long-form guidance (character, tips, troubleshooting). Each step's
instruction says what to do right now. Text that answers "should I brew
this?" belongs in description. Text that answers "how do I get it right?"
belongs in notes. All four are hinted by lang. The Bean's
description is different in kind: the roaster's
own attributed prose about the coffee.
notes
notes is free-text prose about the recipe as a whole: its character, tips,
or troubleshooting ("bright and tea-like; if it tastes sour, grind finer or
nudge the water hotter"). It is author→reader content that travels with the
recipe, and its language is hinted by lang.
- It is distinct from
title(a short label) and from a step'sinstruction(a single step's how-to). Usenotesfor anything about the whole brew. - It is human text. A consumer shows it verbatim and MUST NOT parse it
for data. Structured parameters always belong in their own fields, never
mined from
notes. - There is no separate "private" notes field. CoffeeJSON carries the recipe's shareable identity, not a consumer's personal log.
Additions
additions lists liquids that join the beverage beyond the brew water:
ice for flash-brew, milk or a sweetener stirred into a finished drink, bypass
water for an americano-style dilution. Each entry is an
Addition: a type, an optional amount, and two further
optional members, temperature and note. type is an open registry,
not a closed enum. See Vocabularies § Addition
type for the recommended set and how an
unrecognized value is handled.
The motivating v1.0 case is ice, for Japanese-style flash brew: hot coffee brewed directly onto ice, which chills it at once and melts into the cup.
An addition without a quantity
amount is optional. The reason is worth stating, because this is the one
place in the format where a missing quantity would silently delete a fact the
source did state.
Sources list ice on the ingredient line without a mass, and some print an
unfilled placeholder where the number should be. The presence of an ice
addition is what marks the whole recipe iced. A required amount would
mean an unquantified ice could not be recorded at all, and the recipe could
not be marked iced either. A required quantity would take a semantic flag
down with it.
"additions": [{ "type": "ice", "note": "listed without a quantity" }]
This is the opposite call from water, where the requirement is load-bearing.
A water-basis recipe with no water states nothing useful. An addition with no
amount still states something true and worth carrying. A consumer renders the
addition and its note, and shows no mass.
{
"coffeejson": "1.1",
"recipes": [
{
"title": "Tetsu Kasuya 4:6 Iced",
"method": "pour_over",
"coffee": { "value": 20, "unit": "gram" },
"water": { "value": 150, "unit": "gram" },
"ratio": 7.5,
"water_temp": { "value": 90, "unit": "celsius" },
"additions": [
{ "type": "ice", "amount": { "value": 80, "unit": "gram" } }
],
"steps": [
{ "at_s": 0, "to_water": { "value": 30, "unit": "gram" } },
{ "at_s": 40, "to_water": { "value": 60, "unit": "gram" } },
{ "at_s": 70, "to_water": { "value": 90, "unit": "gram" } },
{ "at_s": 100, "to_water": { "value": 120, "unit": "gram" } },
{ "at_s": 130, "to_water": { "value": 150, "unit": "gram" } }
],
"finish_s": 180,
"notes": "Flash brew: brew hot over 80 g ice so the coffee chills instantly and keeps its aromatics. Half the water of the hot 4:6; the ice melts to dilute. First pour trades sweetness (less) for brightness (more)."
}
]
}
- The presence of an
iceaddition marks the recipe as iced. There is no separateicedflag. No othertypecarries a defined structural effect.milk,sugar,syrup,water(bypass), andcreamare informational, shown but not acted on. waterandratiodescribe the brew, not the finished drink.wateris what is poured through the bed (150 g above).ratiostayswater / coffee(7.5), the concentrate ratio. A consumer MAY compute the effective dilution as(water + Σ addition amounts) / coffee(≈ 11.5 above) for display. The format does not store it.- Additions are independent of
basis. An iced pour-over is a water-basis recipe (water) plusadditions. Additions never require or forbidwater/yield/ratio. - A consumer that does not model additions MUST NOT fail. It ignores the field and, without ice, presents a stronger, un-chilled brew. Iced behavior is best-effort, never required.
- A consumer that does model additions but meets a
typeit does not recognize MUST still showamount(andtemperature/noteif present) rather than drop the entry. This is the same forward-compatibility contract as every other field in the format.
Measurement object
A quantity with an explicit unit. Used for coffee, water, yield,
water_temp, pressure, and an addition's amount / temperature. Bean
altitude uses the same unit-identifier principle with a range-capable
Altitude object.
When a quantity is a Measurement, and when it is a bare number. A quantity
travels as a {value, unit} Measurement when producers state it in different
units (mass, temperature, pressure, length), because the unit choice is real
information. A quantity with a single canonical unit travels as a bare
number whose name carries the unit. Durations are seconds (at_s,
finish_s, preinfusion_s, action_duration_s). Approximate particle size
is microns (microns_approx). ratio is dimensionless. A unit object there
would be ceremony with exactly one possible value.
{ "value": 250, "unit": "gram" }
{ "min": 18.5, "max": 19, "unit": "gram" }
| Field | Type | Req? | Notes |
|---|---|---|---|
value |
number | one of | A single stated magnitude. |
min |
number | one of | Lower bound, when the source states a window. |
max |
number | one of | Upper bound, when the source states a window. |
unit |
string | yes | Mass: gram, ounce. Volume (brew water and a step's to_water only): milliliter. Temperature: celsius, fahrenheit. Pressure: bar. See Water quantity. |
A Measurement MUST carry unit and at least one of value, min, or
max. This is the same rule as Altitude, which
carries ranges because origins are commonly listed as elevation bands.
Stated windows
Brewing guidance is often published as a window rather than a point: an espresso yield of 32–34 g, a dose of 25–45 g for a recipe that scales with the press, a brew temperature of 92–94 °C. A window is what the author stated. The format carries it rather than force a producer to invent a point.
- State the window or the point, never both. A Measurement that carries
valuebesidemin/maxis contradictory. Producers MUST NOT emit it, and the schema rejects it (dependentSchemas: a presentvalueforbidsmin/max). The one contradiction the schema cannot express ismingreater thanmax. Validators SHOULD warn on that. - One-sided windows are legal.
{ "min": 25, "unit": "gram" }says "at least 25 g" and nothing about an upper bound, which is what some sources state. - A consumer that needs a single number derives one and says so. It can
take the midpoint for display, or
minfor a schedule. It MUST NOT present a derived point as the author's number. This is the same rule as Scaling: a consumer that applies its own model owns the result. ratiois unaffected. It remains a bare dimensionless number that describes the relationship betweenwaterandcoffee. When both are windows it is often the thing that couples them. A French press guide that states 25–45 g of coffee to 375–675 g of water states one ratio of 15 across the range.ratiocarries that coupling without loss, where two independent windows would not.- Durations do not take windows.
at_s,finish_s,preinfusion_sandaction_duration_sare bare numbers by design (see above). A published time window belongs innotesor the step'sinstruction.
Water quantity
Brew water is the one input publishers state either by mass or by volume,
because it is a liquid of known density. A guide that prints お湯 92℃ 225cc
beside a dose in grams is ordinary, not exotic. So water and a
step's to_water accept milliliter in addition to gram
and ounce. The ounce is the avoirdupois mass ounce. A source that states
fluid ounces states a volume, which belongs in milliliter (see
Units). Everything else stays a mass. A dose, a
beverage yield, and an addition's amount are masses in every source the
format has met.
{ "value": 225, "unit": "milliliter" }
No conversion between the two is defined. Water's density varies with temperature. 225 mL is 225 g only near 4 °C, and at a stated 92 °C it is ≈216.8 g, a 3.6 % error, coarser than the precision such a guide is written to. A consumer that needs the other kind applies its own model. It MUST NOT present the result as the author's figure, exactly as under Scaling. Producers emit what their source stated.
A recipe whose water is a volume states no mass ratio, so it omits
ratio. See there.
- Producers MUST emit canonical unit identifiers, not localized display
symbols (
gram, notg;celsius, not°CorC). - Consumers MUST convert any unit they recognize into their own canonical store.
- Consumers MUST NOT show the wire
unitstring directly. They render localized labels and symbols with platform measurement APIs or their own locale tables. - If a consumer does not recognize the
unit, it MUST treat the measurement as absent. It MUST NOT guess. A value silently stored in the wrong unit is worse than nothing. - A Measurement's
valueis strictly positive for mass and pressure. A zero-gram dose or a zero-bar pressure states nothing, and the schema rejects it. Temperatures can be zero or below, and a zero-secondat_soffset is real data.
The full unit vocabulary, including conversion factors, is in Vocabularies § Units.
Filter object
What the water passes through on its way out of the bed. Publishers state it on brew guides far more often than on product pages, and it changes the cup. Paper retains oils and fines, metal lets them through, and cloth sits between.
{ "material": "paper", "label": "Chemex bonded — 3-ply on one side" }
| Field | Type | Req? | Notes |
|---|---|---|---|
material |
string (enum) | yes | paper · metal · cloth · other. Unknown → other. See Vocabularies § Filter material. |
label |
string | no | The filter as the source names it, when that says more than the material. Human text; language hinted by lang. |
material is the queryable, portable part. label carries what the enum
flattens: a product ("V60-02"), a form (a tea bag), or the brewer's own part
(a plunger mesh). The specific product is usually implied by the brewer,
which is why the label is free text rather than a registry.
Three things that look like filter data and are not:
- Rinsing is a step, not a property of the filter. It is a
prepstep with an instruction, where a guide can say what to do with the rinse water. - A negation ("this brewer doesn't use a paper filter, so the cup is rich
with oils") is prose for
notes. State the filter positively, for example the metal one in a French press, and let the prose keep the why. - A choice ("either paper or mesh") is a guide that describes a family
rather than one brew. Omit
filterand say so innotes. A recipe states the filter it calls for, not the options.
Gear object
One shape for any piece of equipment: a grinder, a brewer, or a basket. It carries a canonical id for matching, a variant naming which one of that family was used, normalized brand / model for off-registry gear, and a display label for fallback.
{ "id": "hario-v60", "variant": "02" }
{ "id": "custom", "brand": "Modbar", "model": "AV", "label": "Modbar AV" }
The registry entry names the family; variant names which one of it.
That split is why hario-v60 covers every V60 ever made without the registry
growing a row per size, material and generation.
| Field | Type | Req? | Notes |
|---|---|---|---|
id |
string | yes | Canonical registry slug — lowercase kebab-case, schema-enforced — or the literal "custom" for off-registry gear. This is the field other apps match on (byte-exact), which is why the grammar is strict: a mis-cased id would validate yet match nothing. |
brand |
string | no | Normalized brand, for example Hario. |
model |
string | no | Normalized model, for example V60. |
variant |
string | no | The maker's own variant designation for this instance, as printed — a size (02, 185, MDN-41), a material (ceramic), a generation (Gen 2). Free text, never an enum: the varying axis differs per family, so no closed list fits the next one. Same call grind.setting makes. |
label |
string | no | Display string / fallback. Required when id is "custom", and schema-enforced there, since there is no registry entry to localize. |
Consumer behavior:
- For a known
id, a consumer SHOULD prefer its own localized label over the producer'slabel, so the same gear reads consistently in the consumer's locale — and SHOULD rendervariantbeside it, since the registry cannot supply it and dropping it loses what the document knew. - With a known
id, a producer SHOULD omitbrandandmodel: the registry is authoritative for both, and repeating them only drifts from it. - For
id: "custom", a consumer shows the producer'slabelverbatim, and SHOULD rendervariantbeside it when the label does not already name it. A source often writes the variant into the label it states. - An unknown (non-
"custom")idis treated like"custom": fall back tolabel, then tobrand/model, then to theiditself. A consumer MUST NOT fail on an unrecognizedid, and showing the id it cannot resolve says more than showing nothing.
The registry of known slugs is curated, open, and non-exhaustive by design.
id: "custom" plus label always works, so missing coverage never blocks a
share. See Vocabularies § Gear registry.
method vocabulary
method is the brewing technique, distinct from the brewer device.
A V60 (device) is used with a pour_over (technique). An AeroPress (device)
can be used immersion or pour_over. Keeping them separate prevents
conflating "what I used" with "how I used it."
The v1.1 values are stable machine ids. Consumers localize them:
pour_over · immersion · aeropress · french_press · moka ·
cold_brew · siphon · cezve · drip · capsule · espresso · other
Notes: drip is a batch / filter machine. capsule is a pod system. cezve
is ibrik / Turkish. A consumer that meets an unrecognized value MUST treat
it as other. New methods can be added in a minor version. The full table is
in Vocabularies § method.
espresso sets basis: "yield". method is descriptive. The recipe's
basis carries the structural rule: a basis: "yield" recipe (espresso's
basis) REQUIRES yield and MUST NOT carry water or ratio, so its
required numbers always mean what they say. See
Espresso (dose : yield).
Grind object
setting, microns_approx, and size are three views of one target
grind at different precisions and portabilities. A consumer shows the most
specific axis it understands: setting when the reader has the sender's
grinder, else microns_approx, else size. It need not reconcile them. They
are independent expressions, not derivations of each other.
{
"grinder": { "id": "comandante-c40", "brand": "Comandante", "model": "C40", "label": "Comandante C40" },
"setting": "22 clicks",
"microns_approx": 700,
"size": "medium_fine"
}
| Field | Type | Req? | Notes |
|---|---|---|---|
grinder |
Gear | no | The grinder used. |
setting |
string | no | The setting as expressed on that grinder ("22 clicks", "6.5", "stepless 1.4 turns"). Free text. |
microns_approx |
number | no | Approximate particle size in microns (strictly positive). Explicitly approximate — the only roughly-portable axis. |
size |
string (enum) | no | Qualitative coarseness on the standard seven-level scale (ordered). See Grind size vocabulary. Unknown → ignore the field, preferring setting / microns_approx when present. |
Grind is the one place CoffeeJSON refuses to be clever:
settingis free text and MUST NOT be coerced to a number. Grinder scales are not portable. "22 clicks" means nothing on a different grinder, so the setting is preserved exactly as the sender expressed it.microns_approxis the only axis that is even loosely comparable across grinders, and it is explicitly approximate. A consumer MUST NOT automatically apply it to a different grinder's dial.sizesits besidesettingandmicrons_approx, not above them. It is the qualitative read ("medium-coarse") on a standard scale, comparable across grinders in a waysettingnever is, and coarser-grained thanmicrons_approx. A consumer that meets an unrecognizedsizevalue, or nosizeat all, falls back tosetting/microns_approxfor display.- No cross-grinder conversion is defined or expected in v1.1. A consumer
shows the sender's
grinder/setting/microns_approx/sizeas stated and lets the user dial in their own equipment.
Structured grind data means a conversion layer can be added later with no format change, and the format never produces a confidently-wrong number today.
Step object
A brew is an ordered sequence of actions. Most steps are timed pours, but
a step can be an untimed prep action or a manipulation. Array order is
authoritative. at_s is an optional timing annotation, and to_water
applies only to pour-type steps. See The data-guard
rule for exactly how a consumer tells the difference.
Across the steps that carry them, a producer SHOULD emit at_s and
to_water non-decreasing in array order: time runs forward and the scale
reading only rises. A consumer MUST NOT reorder steps to repair a schedule
that does not — it keeps array order and shows the numbers it was given, so a
recipe never plays differently in two apps.
The everyday pour-over step is { "at_s", "to_water" }. kind defaults to
pour, so a common recipe is a simple list of (time, target weight).
{ "kind": "pour", "at_s": 30, "to_water": { "value": 150, "unit": "gram" }, "instruction": "slow circle pour" }
{ "kind": "bloom", "at_s": 0, "to_water": { "value": 45, "unit": "gram" }, "instruction": "saturate, swirl gently" }
{ "kind": "prep", "instruction": "rinse filter, preheat dripper" }
{ "kind": "flip", "instruction": "invert the AeroPress" }
{ "kind": "press", "at_s": 90, "instruction": "press gently over ~20s" }
{ "kind": "distribute", "instruction": "WDT until the bed is level" }
{ "kind": "pull", "instruction": "line pressure to 3.5 s, then 9 bar" }
| Field | Type | Req? | Notes |
|---|---|---|---|
kind |
string (enum) | no | Default pour; unknown → other. bloom is pour-type — see Bloom. The value list lives in one place: Vocabularies § Step kind. |
at_s |
number | no | Seconds from brew start to cue this step. Absent = sequential / user-paced (prep, flips). |
to_water |
Measurement | no | Cumulative water in the cup by the end of this step — the scale's target reading. Same {value,unit} shape as water. Pour-type steps only. |
instruction |
string | no | Free-text how-to ("center then circle", "agitate", "shake the dripper"). Human text — see lang. |
label |
string | no | Present only if the author explicitly customized it. See the rule below. |
action_duration_s |
number | no | How long this step's action takes, in seconds. See Action duration. |
Cumulative water
to_water is cumulative, not per-step. It is the total water in the cup
by the end of the step, the weight the scale should read at that point. A
bloom to 30 g followed by a pour to 150 g means the second pour ends
at 150 g, having added 120 g. A consumer shows the cumulative target and, if
it likes, the per-pour amount (the difference from the previous step).
Cumulative targets are how scale-based pour-over is executed: pour until the
scale reads the number.
The data-guard rule
Whether a step is water-bearing (belongs in the pour schedule) is decided
by its data, not its kind. Any step that carries both at_s and a
usable to_water is water-bearing, whatever kind says. A consumer MUST
schedule water off that pair and MUST NOT gate scheduling on a kind
allowlist.
This is what makes new pour-type kinds forward-compatible for free. bloom
(below) carries at_s + to_water exactly like pour, so a consumer that
follows this rule already schedules it correctly with no code change. The
same holds for any pour-type kind a future minor version adds. The corollary
is the safety net. A consumer that does not recognize a kind has nothing to
consult but the data. An unrecognized pour-type kind can at most degrade to
label-only (shown through its instruction, not scheduled). It can never
produce broken or miscounted water math, because kind is never part of how
the number is computed.
Bloom
bloom is a pour-type step kind for the initial pre-wet: a short pour
(usually around twice the coffee's mass in water) that saturates the grounds
and lets trapped CO₂ escape before the main pour schedule continues. It
carries at_s + to_water exactly like pour:
{ "kind": "bloom", "at_s": 0, "to_water": { "value": 45, "unit": "gram" } }
Any consumer that follows the data-guard rule picks it up with no special-casing.
An ordinary pour (or kind-defaulted) step at at_s: 0 is also valid for the
same pre-wet. Naming it bloom lets a producer state the step's purpose. A
consumer can then render its own localized "Bloom" label from the kind rather
than the author serializing one. This is the same principle as the
derived-label rule below.
Action duration
action_duration_s states how long the step's action itself takes, in
seconds. It is a single value, distinct from at_s (when the step starts).
It applies to any step whose action has a duration worth recording: a slow
controlled pour, a press (the plunge), a stir.
Paired with the water delta between this step and the previous one (this
step's to_water minus the previous step's), action_duration_s yields the
pour rate in g/s. That is useful when cadence matters as much as total
volume. A consumer that does not compute rate ignores the field. Deriving it
is optional presentation, never required to render the schedule.
The derived-label rule
label carries a customized name only. A derived or default label
("Bloom", "Pour 2", "Drawdown") MUST be serialized as absent, so that each
consumer renders its own localized default from the step's position and kind.
Emitting "Bloom" would freeze one language into the data. Omitting it lets a
consumer show "Bloom", "ブルーム", or "Floração" as appropriate. This rule is a
direct consequence of principle 2 (locale-neutral on the wire).
Mixed-capability consumers
Array order MUST be preserved by every consumer. A consumer that only
models timed pours builds its schedule with the data-guard
rule: every step with at_s + a usable to_water,
whether pour, bloom, or a kind it has never heard of. It shows every other
step read-only instead, for example its instruction shown but
unscheduled. Such a consumer MUST NOT fail on a step kind it does not
implement. An unmodeled step is shown, never an error.
The espresso kinds (distribute (WDT), tamp, pull) are steps like any
other. None of them carry to_water, because the shot's numbers (yield,
pressure, time) live at the recipe level, never on a step. So the data-guard
rule surfaces them read-only, and a consumer that does not model espresso
needs no espresso-specific check to get that right.
Addition object
A liquid added to the brew beyond the brew water. type is an open
registry (recommended: ice, milk, sugar, syrup, water, cream),
not a closed enum. The object stays small on purpose, and a new kind of
addition is a new string, never a schema change. temperature and note are
optional members for when something beyond the amount is worth recording.
{ "type": "ice", "amount": { "value": 80, "unit": "gram" } }
{
"type": "milk",
"amount": { "value": 100, "unit": "gram" },
"temperature": { "value": 65, "unit": "celsius" },
"note": "oat"
}
| Field | Type | Req? | Notes |
|---|---|---|---|
type |
string | yes | What is added — an open registry, not a closed enum: any value is valid. Recommended: ice · milk · sugar · syrup · water · cream. See Addition type vocabulary. |
amount |
Measurement | no | How much is added, by mass. Recommended unit gram. Omitted when the source lists an addition without a quantity — see An addition without a quantity. |
temperature |
Measurement | no | Temperature of the added liquid, where meaningful (for example steamed milk). Recommended unit celsius. |
note |
string | no | Free-text detail — brand, prep, sweetener kind. Human text — see lang. |
icedenotes coffee brewed onto ice (Japanese-style flash brew). The ice both chills the brew and melts into the beverage, and its presence marks the recipe iced. See Additions.- Additions do not change the meaning of
waterorratio. No cross-field arithmetic is implied. A consumer that wants a total-dilution figure derives it. - A consumer that does not recognize a
typevalue handles it generically: it showstypeandamount(andtemperature/noteif present) without special-casing it, and it MUST NOT fail. Onlyicecarries a defined behavioral effect (marking the recipe iced). Every other value, known or not, is informational.
Party object
A person or organization credited on a document. One shape for every credit:
recipe author, bean
roaster, and each entry of an origin item's
producers. A consumer renders a producer with
the code it already uses for a roaster or an author, and a structured-data
exporter emits the same Person / Organization node.
{ "name": "Tetsu Kasuya", "url": "https://en.philocoffea.com" }
| Field | Type | Req? | Notes |
|---|---|---|---|
name |
string | yes | Display name, as the source writes it. Never empty. |
url |
string (URI) | no | The party's own page — a profile, site, or channel. |
type |
string (enum) | no | person · organization, when known. Absent/unknown → infer from the crediting field. See Party type. |
role |
string | no | The part this party played, on any credit. An open registry. |
Field mapping summary
| Concept | Field | Canonical form |
|---|---|---|
| Coffee dose | coffee |
gram measurement |
| Brew water | water |
gram measurement (not on a yield-basis recipe) |
| Beverage yield | yield |
gram measurement (required when basis is yield) |
| Ratio | ratio |
bare number (water ÷ coffee; not on a yield-basis recipe) |
| Brew pressure | pressure |
bar measurement |
| Pre-infusion | preinfusion_s |
seconds (number) |
| Basket | basket |
Gear |
| Water temperature | water_temp |
celsius measurement |
| Technique | method |
machine id (vocabulary) |
| Stated-quantity basis | basis |
machine id — water (default) · yield (vocabulary) |
| Device | brewer |
Gear |
| Grinder + setting | grind |
Grind |
| Pour schedule | steps |
ordered Step array |
| Recipe author | author |
Party |
| Original publication | based_on |
URI string (schema.org isBasedOn) |
| Linked coffee | bean_ref |
the id of a bean in this document |
| Producer's pick | recommended |
boolean; omitted unless true |
| Recipe notes | notes |
free-text prose (human text) |
| Added liquids | additions |
Addition array — open type registry |