An open format for describing a coffee brew

Open format · v1.0 · Apache 2.0

Coffee brewing,
precisely described.

BrewSpec is a free, versioned data format for coffee brew records: method, dose, water, grind, extraction, result. Build tools on it, log brews locally, and move data between apps.

View the schema Browse examples

The complete brew record, field by field.

BrewSpec covers the full record: what went in, how it was made, and what came out.

Brew
  • Brew date (date-only or full datetime)
  • Brew type (espresso, pour over, immersion, hybrid)
  • Dose (g)
  • Water (g) and temperature (°C)
  • Brew method (freeform — "Hario V60", "AeroPress")
  • Grind setting (espresso through coarse)
  • Duration (seconds)
  • Process notes
Coffee
  • Origin
  • Elevation (meters above sea level)
  • Roaster
  • Roast level (light, medium, dark)
  • Roast date
  • Type (single origin, blend)
  • Varietal
  • Process (washed, natural, honey, etc.)
Water
  • Dissolved solids (ppm)
Equipment
  • Grinder model
  • Brewer model
  • Grinder setting (dial position)
  • Pressure (bar) — line or lever pressure
  • Flow rate (ml/s) — volumetric flow rate
Result
  • TDS and extraction yield
  • Brix
  • Yield weight (g) — output weight in the cup; primary espresso metric
  • Tasting notes (sensory description — kept separate from process notes)
  • Ratings: overall, fragrance, aroma, flavour, acidity, aftertaste, sweetness, mouthfeel — 1–9 scale aligned to CVA hedonic protocol

All fields are optional. Record what you measure.

See what a brew looks like.

A minimal record. A full espresso record with yield and ratings.

Pour over — minimal record
brewspec_version: "1.0"
brews:
  - date: "2026-02-25"
    type: "pour_over"
    dose_g: 18
    water_g: 280
Espresso — full record
brewspec_version: "1.0"
brews:
  - date: "2026-02-25T08:30:00Z"
    type: "espresso"
    dose_g: 18
    water_g: 36
    water_temp_c: 94
    grind: "espresso"
    duration_s: 28
    method: "La Marzocco Linea Mini"
    process_notes: "Re-calibrated grinder after three weeks"
    coffee:
      name: "El Paraiso Washed Castillo"
      roaster: "Onyx"
      roast_level: "medium"
      roast_date: "2026-02-10"
      type: "single_origin"
      origins:
        - country: "Colombia"
          region: "Huila"
          varietal: "Castillo"
          elevation_masl: 1800
    water:
      ppm: 120
    equipment:
      grinder: "Niche Zero"
      brewer: "La Marzocco Linea Mini"
      pressure_bar: 9.0
      flow_rate_ml_s: 1.8
    result:
      yield_g: 36
      tds: 9.2
      ey: 19.8
      brix: 4.6
      tasting_notes: "Dark chocolate, orange peel, long clean finish"
      ratings:
        overall: 7
        fragrance: 7
        aroma: 7
        flavour: 8
        acidity: 7
        aftertaste: 7
        sweetness: 6
        mouthfeel: 6

For the people who handle brew data.

For tool builders

Brew loggers, roasting apps, and recipe platforms all need a data format. BrewSpec is a shared format to build against: JSON Schema-validated, version-controlled, with documented migration paths between versions. Apache 2.0, usable in anything.

The schema lives at brewspec.coffee/schema/v1.0.json. The spec document covers every field, validation rules, and the expected validation pipeline.

For coffee professionals and home brewers

If you log brews, on paper, in a spreadsheet, or in an app, BrewSpec is the format your data travels in. Export from one tool and import into another without a proprietary lock-in.

BrewLog is the reference CLI implementation: free, local, no account required. Log a brew in under a minute and your data stays on your machine.

v1.0 Apache 2.0 JSON Schema Draft 2020-12

Open, versioned, and maintained.

BrewSpec is Apache 2.0. Free to use in commercial and open source projects. The schema is JSON Schema (Draft 2020-12), hosted at a stable URL, and versioned with a brewspec_version const inside every brew file.

Breaking changes follow a documented migration path. Every schema version is archived. A brew file states the exact version of the spec it was written against.

github.com/coffee-standards/brewspec →