Tasting
A Tasting is how one brewed cup turned out: the outcome of following a
recipe, not the recipe itself. It is the third top-level entity of CoffeeJSON
v1.1, carried as an element of the tastings array in the document
envelope beside Recipe and
Bean. It points back at what it evaluates: a
recipe_ref at the brew, a bean_ref at the coffee.
Both are optional and both resolve independently. See
Envelope § Association (a tasting's recipe and coffee).
Unlike beans and recipes, a tastings array does not on its own make
a valid document. A tasting evaluates something, so a document that carries
only tastings describes nothing a consumer can act on.
{
"recipe_ref": "morning-v60",
"rating": 4,
"perceived": { "extraction": -0.2, "strength": 0.1 },
"descriptors": ["blackberry", "floral"],
"note": "best one this week",
"measured": { "tds": 1.38 }
}
Every field is optional. A tasting can be as thin as a single refractometer reading or as rich as a full impression with a note in the drinker's own words.
A tasting is not a journal entry. It carries no timestamp, no personal identity, and no inventory state. It says how a cup was, not who drank it or when.
Fields
| Field | Type | Req? | Notes |
|---|---|---|---|
id |
string | no | Document-local name for this tasting, so something outside the tastings array can say which one it means. Unique within tastings, compared exactly. See Tasting id. |
recipe_ref |
string | no | The id of a recipe in this document — the brew this cup came from. Exact, case-sensitive. An unresolved reference leaves the tasting unlinked; consumers MUST NOT fail. |
bean_ref |
string | no | The id of a bean in this document — the coffee that was brewed. Same matching and failure rules. |
rating |
integer | no | 1–5, how much the drinker liked this cup. See rating. |
perceived |
object | no | How the cup was perceived, on the two dial-in axes. See Perceived. |
descriptors |
array of string | no | What the drinker tasted, in the drinker's own words. Free strings, displayed verbatim — see Flavor descriptors for the comparison rule. |
note |
string | no | The drinker's own words. Producers that treat notes as private SHOULD omit the field rather than emit an empty string. |
lang |
string (BCP-47) | no | Language of this tasting's human text (note, descriptors), as a well-formed BCP-47 tag. A hint only. See Tasting lang. |
measured |
object | no | What an instrument read. See Measured. |
Impression and measurement are kept apart
The split down the middle of this object is by design. rating, perceived
and descriptors are attributed opinion: one drinker, one cup, one
occasion. measured is measured fact: an instrument reading anyone with
the same instrument would reproduce. They are never mixed, and a consumer
MUST NOT present one as the other.
This is why a rating is permitted at all. CoffeeJSON does not carry quality
scores for a coffee. rating is not "this coffee is a 4". It is "the person
who wrote this file liked this cup" — the impression belongs to whoever
produced the document, scoped to one brew, and never comparable across
producers. generator is optional and names
software, not a drinker: a consumer MAY show it as a courtesy and MUST
NOT read it to decide whose impression this is.
Tasting id
A document-local name for one tasting, exactly as a recipe's
id is for one recipe. It is any non-empty string, unique
within the document's tastings array, compared exactly and
case-sensitively. It is never a global identifier, an account, or an
inventory key.
It exists for the same reason: array position is not an identity. Three
tastings of one recipe are otherwise an unordered bag. Only their position
tells them apart. This specification never declares position authoritative for
tastings, as it does for steps. A document
regenerated with one cup added in the middle silently renames every tasting
after it.
- Optional, and worth emitting whenever a document carries more than one tasting. A single tasting needs no id.
- Producers SHOULD keep an id stable across re-publication of the same cup.
- Uniqueness is a semantic rule JSON Schema cannot express. A validator SHOULD show a duplicate as a warning. A consumer that resolves a reference to a duplicated id SHOULD treat it as unresolved.
An id is not a timestamp. A tasting still carries no time of brewing
and no drinker identity. Naming a cup is not dating it.
Tasting lang
The BCP-47 tag that hints what language this tasting's human text is in: its
note and its descriptors, both the drinker's own words. It has
the same form and the same status as a recipe's
lang: a well-formed tag, hyphen-separated, and a
hint only.
A tasting has no localizations counterpart, and will not get one. A
recipe's localizations exist because a publisher translates work meant for an
audience. A tasting is one person's account of one cup, and nobody publishes
translations of their own tasting note. A producer with the same cup
described in two languages has two tastings, not one with an overlay.
rating
An integer 1–5. The scale is declared here rather than left to the schema's bounds. A score whose system is unstated is a number a consumer can only misread.
Importing from another scale. A producer whose own rating runs on a
different system maps to the nearest whole value in 1–5. A 10-point score
halves and rounds. A half-star scale rounds away from zero. A three-tier
like/neutral/dislike takes 5, 3 and 1. Some scales cannot be mapped: an
unbounded score, or a scale with no "worse" and "better". Such a producer
MUST omit rating rather than emit a value that reads as a comparable
star count.
The field stays an integer. Widening it to accept halves later is additive and costs no existing document. Narrowing a number back to an integer would break every document that used a fraction. So the tighter shape is the one that keeps the choice open.
Perceived
Both axes run -1 to 1 with 0 meaning "about right":
| Axis | -1 | 0 | +1 |
|---|---|---|---|
extraction |
sour, acidic, under-extracted | balanced | bitter, harsh, over-extracted |
strength |
weak, watery, thin | about right | strong, heavy, muddy |
These are impressions, not readings. perceived.extraction is what the
drinker tasted. It is not an extraction yield and MUST NOT be derived
from one or rendered as a percentage.
The member is named for its provenance, perceived, as against
measured, and not for its shape. So it can hold a third
dimension without its name becoming false. One consequence is worth stating
rather than designing away: the -1 to 1 bipolar scale is a property of
these two dimensions, not of the member. extraction and strength are
directions with a correct middle. A perceived intensity (body, sweetness)
would be a magnitude with no such middle, so it would carry its own scale. A
consumer MUST NOT assume every member of perceived runs -1 to 1.
Why not axes. The two dimensions are still axes, and this document
still calls them that. But a member named for them describes its shape, which
is the half that will not survive. The day a perception arrives that is not a
dial-in axis, it either goes somewhere else or makes the member's name a lie.
The first gives "how it tasted" two homes. perceived says what the values
are, which is what every consumer needs to know before rendering one.
Measured
| Field | Type | Req? | Notes |
|---|---|---|---|
tds |
number | no | Total dissolved solids in the beverage, as a percentage by mass, as read by a refractometer. Greater than 0. |
yield |
Measurement (mass) | no | Beverage mass actually weighed out of this brew. A scale reading of this cup, not the recipe's target. See below. |
Filter coffee usually lands near 1.2–1.6 and espresso near 8–12. The schema
does not bound tds to those ranges. Concentrates and cold brew exceed them,
and a schema that rejected a true reading would be worse than one that
accepts a surprising one.
Two beverage masses, and which one wins. A recipe's
yield is the mass the brew aimed at.
measured.yield is the mass that came out, weighed. They are different
facts, and the format carries both. A cup that landed at 258 g against a
262 g target is a 258 g cup, and only the tasting can say so. That matters
most where a recipe has no yield at all, the normal case for immersion
brewing stated by water.
Extraction yield is not a field. It is derived. Carried as well, the same quantity would have two homes that can disagree:
extraction yield % = (beverage mass × TDS %) ÷ dose
A consumer that computes it takes the beverage mass from measured.yield
when the tasting carries one, and the recipe's yield
otherwise: the measurement of this cup before the target it was brewed
against. The dose is the recipe's coffee. A consumer
that lacks any of the three MUST NOT guess. Beverage mass and dose come to
one mass unit — grams — before they divide; an operand stated by volume, or in
a unit the consumer does not recognize, yields no number; and a window is
reduced only under Recipe § Stated
windows.
Example
{
"coffeejson": "1.1",
"recipes": [
{
"id": "morning-v60",
"title": "Morning V60",
"method": "pour_over",
"coffee": { "value": 18, "unit": "gram" },
"water": { "value": 300, "unit": "gram" },
"yield": { "value": 262, "unit": "gram" }
}
],
"tastings": [
{
"recipe_ref": "morning-v60",
"rating": 4,
"perceived": { "extraction": -0.2 },
"descriptors": ["blackberry", "floral"],
"measured": { "tds": 1.38 }
}
]
}
That cup: liked it, tasted slightly under-extracted, measured 1.38 % TDS. With 262 g of beverage from 18 g of coffee that works out to about 20.1 % extraction yield, a number the document does not state and any consumer can compute.