v1.0 Field Reference
What's in the schema.
Every field BrewSpec defines: type, constraints, and what it's for. All fields are optional. Record what you measure.
Top-Level
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
brewspec_version | string | Yes | const: "1.0" | Must be the literal string "1.0". |
brews | array | Yes | minItems: 1 | Array of brew objects. At least one brew required. |
Brew
All fields in the brew object are optional.
| Field | Type | Constraints | Description |
|---|---|---|---|
date | string | YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ | Brew date or datetime (UTC). |
type | string | Enum: immersion, pour_over, espresso, hybrid | Brew method category. |
dose_g | number | > 0 | Coffee dose in grams. |
water_g | number | > 0 | Recipe target water in grams. |
brew_ratio | number | > 0 | Water-to-coffee ratio as a float (e.g. 15.5 = 15.5:1). |
method | string | maxLength: 100 | Freeform brewer description (e.g. "Hario V60"). |
water_temp_c | number | 0–100, multipleOf: 0.1 | Water temperature in celsius. |
coffee | object | Coffee ingredient descriptor. | |
water | object | Water ingredient descriptor. | |
equipment | object | Equipment descriptor. | |
grind | string | Enum: turkish, espresso, fine, medium_fine, medium, medium_coarse, coarse | Grind size (finest to coarsest). |
duration_s | number | > 0 | Brew duration in seconds. |
yield_g | number | > 0 | Recipe target yield in grams (intended output weight). |
process_notes | string | maxLength: 2000 | Operational observations about preparation. |
result | object | Brew outcome measurements and sensory evaluation. |
Coffee
Entire object optional. All nested fields optional.
| Field | Type | Constraints | Description |
|---|---|---|---|
name | string | maxLength: 100 | Branded product name or descriptive label. |
roaster | string | maxLength: 100 | Who roasted the coffee. |
roast_level | string | Enum: light, medium, dark | Roast level category. |
roast_date | string | YYYY-MM-DD | Roast date. |
type | string | Enum: single_origin, blend | Single origin or blend. |
origins | array | minItems: 1 | Structured origin records. |
cupping_notes | string | maxLength: 2000 | Sensory notes for the coffee (bag description or pre-brew cupping). |
Origin
All fields optional. Each object in the origins array follows this shape.
| Field | Type | Constraints | Description |
|---|---|---|---|
name | string | maxLength: 100 | Descriptive name for this origin. |
country | string | maxLength: 100 | Country of production. |
region | string | maxLength: 100 | State, province, or growing region. |
subregion | string | maxLength: 100 | District or sub-area within the region. |
producer | string | maxLength: 100 | Farm, cooperative, or washing station. |
process | string | maxLength: 100 | Green coffee processing method (e.g. washed, natural, honey). |
lot | string | maxLength: 100 | Lot or batch identifier. |
harvest_year | integer | 1900–2100 | Year the crop was harvested. |
varietal | string | maxLength: 100 | Coffee varietal (e.g. Heirloom, Gesha, Bourbon). |
elevation_masl | integer | > 0 | Growing elevation in meters above sea level. |
cupping_notes | string | maxLength: 2000 | Per-component sensory notes for this origin. |
Water
Entire object optional.
| Field | Type | Constraints | Description |
|---|---|---|---|
ppm | number | ≥ 0 | Total dissolved solids in parts per million. |
Equipment
Entire object optional. All nested fields optional.
| Field | Type | Constraints | Description |
|---|---|---|---|
grinder | string | maxLength: 100 | Grinder model. |
brewer | string | maxLength: 100 | Brewer or brewing vessel. |
grinder_setting | number | > 0 | Dial position or click setting. Integer or decimal tenths. |
pressure_bar | number | > 0 | Line or lever pressure in bars (primarily espresso). |
flow_rate_ml_s | number | > 0 | Volumetric flow rate in ml/s (espresso profiling and pour-over). |
notes | string | maxLength: 2000 | Equipment state observations (burr age, filter type, etc.). |
Result
Entire object optional. All nested fields optional.
| Field | Type | Constraints | Description |
|---|---|---|---|
tds | number | > 0 | TDS percentage of finished brew. |
ey | number | > 0 | Extraction yield as a percentage. |
brix | number | ≥ 0 | Dissolved sugar content in degrees Brix. |
yield_g | number | > 0 | Actual output weight in grams (espresso: liquid in cup). |
water_g | number | > 0 | Actual water used in grams (captures deviation from recipe target). |
tasting_notes | string | maxLength: 2000 | Sensory description of the brew. |
ratings | object | Multi-dimensional sensory ratings. |
Ratings
All fields are optional integers 1–9, aligned to the SCA Coffee Value Assessment hedonic scale (SCA-104, 2024).
| Field | Type | Range | Description |
|---|---|---|---|
overall | integer | 1–9 | Holistic impression. |
fragrance | integer | 1–9 | Dry grounds aroma before water is added. |
aroma | integer | 1–9 | Wet aroma after water is added. |
flavour | integer | 1–9 | Taste and aroma experienced during drinking. |
aftertaste | integer | 1–9 | Length and quality of positive flavour after swallowing. |
acidity | integer | 1–9 | Quality of acidity; brightness. |
sweetness | integer | 1–9 | Perceived sweetness. |
mouthfeel | integer | 1–9 | Tactile sensation; body and texture. |
CVA Hedonic Scale
1 Dislike extremely
2 Dislike very much
3 Dislike moderately
4 Dislike slightly
5 Neither like nor dislike
6 Like slightly
7 Like moderately
8 Like very much
9 Like extremely