Schemas / brew-methods

Open Coffee brew methods v0.3.0

Ways of brewing coffee (espresso, pour-over, V60, AeroPress, cold brew…), their typical parameters and what a coffee journal should record for each. Methods form a tree: a device-specific method such as v60 has the general method pour-over as parent. Part of Roastbook Open Coffee.

$id: https://schema.roastbook.coffee/brew-methods/brew-methods.schema.v0.3.0.json
Records: Listed under brew_methods. Field links such as #field-… are relative to one record.
Check a file: Open in the Playground

Brew method record

idtextrequired
Stable readable slug, e.g. v60, french-press. Never reused.
at least 3 characters · at most 64 characters
Pattern ^[a-z0-9][a-z0-9_.-]*[a-z0-9]$
Example: v60
Defined in common.schema.v0.3.0.json#/$defs/id
nametextrequired
Common English name of the method, for example Pour-over or French press.
at least 1 character
aliaseslist of text
Other names in any language, e.g. Filterkaffee, drip.
no duplicates · each entry: at least 1 character
parenttext
The more general method, e.g. pour-over for v60.
at least 3 characters · at most 64 characters
Pattern ^[a-z0-9][a-z0-9_.-]*[a-z0-9]$
Example: cp-7k2m9x4qvd
Defined in common.schema.v0.3.0.json#/$defs/id
categoryone of a fixed setrequired
Family used for grouping: espresso (9-bar style pressure), filter (percolation through a filter), immersion (steep, then separate), pressure (non-espresso pressure such as AeroPress or moka pot), vacuum (siphon), boiling (cezve/ibrik), cold (cold water over hours).
Values: espresso filter immersion pressure vacuum boiling cold
extractionone of a fixed setrequired
Physical principle; matches equipment brewer.mechanism.
Values: percolation immersion hybrid
descriptiontextrequired
Short neutral explanation in our own words.
at least 20 characters · at most 600 characters
introduced_yearwhole number
Year the method or device was invented or first sold.
at least 1000 · at most 2100
origin_country_codetext
ISO 3166-1 alpha-2 code in upper case.
Pattern ^[A-Z]{2}$
Defined in common.schema.v0.3.0.json#/$defs/country_code
equipment_typeslist of one of a fixed set
Equipment types needed, from the equipment schema's type list.
Values: espresso_machine espresso_machine_with_grinder grinder brewer kettle scale tamper wdt basket filter roaster milk_frother accessory
no duplicates
Defined in equipment.schema.v0.3.0.json#/$defs/type
typical_parametersobject
Common starting ranges, not rules.
No other fields allowed.
8 fields in typical_parameters
- dose_gobjecttypical_parameters.dose_g
  A starting range. When several values are given they must be ordered: min ≤ typical ≤ max. JSON Schema cannot compare two values, so this repository checks it in its examples and data repositories check it in their data.
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.3.0.json#/$defs/range
  3 fields in dose_g
  - minnumbertypical_parameters.dose_g.min
    Lowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for water_temperature_celsius).
    at least 0
  - maxnumbertypical_parameters.dose_g.max
    Highest common value, in the unit named by the parameter.
    at least 0
  - typicalnumbertypical_parameters.dose_g.typical
    A good starting value, in the unit named by the parameter.
    at least 0
- brew_ratioobjecttypical_parameters.brew_ratio
  Grams of brew water per gram of coffee, for example 16 for 1:16. Used for filter, immersion and cold brew.
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.3.0.json#/$defs/range
  3 fields in brew_ratio
  - minnumbertypical_parameters.brew_ratio.min
    Lowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for water_temperature_celsius).
    at least 0
  - maxnumbertypical_parameters.brew_ratio.max
    Highest common value, in the unit named by the parameter.
    at least 0
  - typicalnumbertypical_parameters.brew_ratio.typical
    A good starting value, in the unit named by the parameter.
    at least 0
- yield_ratioobjecttypical_parameters.yield_ratio
  Grams of drink in the cup per gram of coffee, for example 2 for a 1:2 espresso. Used where the drink is weighed, mainly espresso.
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.3.0.json#/$defs/range
  3 fields in yield_ratio
  - minnumbertypical_parameters.yield_ratio.min
    Lowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for water_temperature_celsius).
    at least 0
  - maxnumbertypical_parameters.yield_ratio.max
    Highest common value, in the unit named by the parameter.
    at least 0
  - typicalnumbertypical_parameters.yield_ratio.typical
    A good starting value, in the unit named by the parameter.
    at least 0
- water_temperature_celsiusobjecttypical_parameters.water_temperature_celsius
  A starting range. When several values are given they must be ordered: min ≤ typical ≤ max. JSON Schema cannot compare two values, so this repository checks it in its examples and data repositories check it in their data.
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.3.0.json#/$defs/range
  3 fields in water_temperature_celsius
  - minnumbertypical_parameters.water_temperature_celsius.min
    Lowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for water_temperature_celsius).
    at least 0
  - maxnumbertypical_parameters.water_temperature_celsius.max
    Highest common value, in the unit named by the parameter.
    at least 0
  - typicalnumbertypical_parameters.water_temperature_celsius.typical
    A good starting value, in the unit named by the parameter.
    at least 0
- brew_time_secondsobjecttypical_parameters.brew_time_seconds
  A starting range. When several values are given they must be ordered: min ≤ typical ≤ max. JSON Schema cannot compare two values, so this repository checks it in its examples and data repositories check it in their data.
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.3.0.json#/$defs/range
  3 fields in brew_time_seconds
  - minnumbertypical_parameters.brew_time_seconds.min
    Lowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for water_temperature_celsius).
    at least 0
  - maxnumbertypical_parameters.brew_time_seconds.max
    Highest common value, in the unit named by the parameter.
    at least 0
  - typicalnumbertypical_parameters.brew_time_seconds.typical
    A good starting value, in the unit named by the parameter.
    at least 0
- brew_pressure_barobjecttypical_parameters.brew_pressure_bar
  A starting range. When several values are given they must be ordered: min ≤ typical ≤ max. JSON Schema cannot compare two values, so this repository checks it in its examples and data repositories check it in their data.
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.3.0.json#/$defs/range
  3 fields in brew_pressure_bar
  - minnumbertypical_parameters.brew_pressure_bar.min
    Lowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for water_temperature_celsius).
    at least 0
  - maxnumbertypical_parameters.brew_pressure_bar.max
    Highest common value, in the unit named by the parameter.
    at least 0
  - typicalnumbertypical_parameters.brew_pressure_bar.typical
    A good starting value, in the unit named by the parameter.
    at least 0
- grind_sizelist of one of a fixed settypical_parameters.grind_size
  Descriptive grind size; extra_fine is Turkish, fine espresso, medium filter, coarse French press and cold brew.
  Values: extra_fine fine medium_fine medium medium_coarse coarse extra_coarse
  at least 1 entry · no duplicates
  Defined in brew-methods.schema.v0.3.0.json#/$defs/grind_size
- grind_d50_micronsobjecttypical_parameters.grind_d50_microns
  Median particle size in micrometres, comparable across grinders.
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.3.0.json#/$defs/range
  3 fields in grind_d50_microns
  - minnumbertypical_parameters.grind_d50_microns.min
    Lowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for water_temperature_celsius).
    at least 0
  - maxnumbertypical_parameters.grind_d50_microns.max
    Highest common value, in the unit named by the parameter.
    at least 0
  - typicalnumbertypical_parameters.grind_d50_microns.typical
    A good starting value, in the unit named by the parameter.
    at least 0
recorded_parameterslist of one of a fixed set
Parameters a coffee journal should offer when logging a brew with this method.
Values: dose_g brew_water_g yield_g brew_ratio yield_ratio grind_setting brew_time_seconds target_time_seconds water_temperature_celsius bloom_time_seconds bloom_water_g preinfusion_time_seconds preinfusion_pressure_bar brew_pressure_bar flow_rate_ml_per_second tamp_force_kg paper_filter_position distribution_method pour_count steep_time_seconds
no duplicates
Defined in brew-methods.schema.v0.3.0.json#/$defs/parameter
typical_drinkslist of text
Drinks usually made with this method, in plain lowercase English, for example espresso, cappuccino or flat white.
no duplicates · each entry: at least 1 character
xrefobject
Identifiers of the method in other datasets and apps.
No other fields allowed.
2 fields in xref
- wikidatatextxref.wikidata
  Wikidata item id of the method, for example Q180289 for espresso.
  Pattern ^Q[1-9][0-9]*$
- beanconquerortextxref.beanconqueror
  Beanconqueror PREPARATION_TYPES key, for app imports.
  Pattern ^[A-Z0-9_]+$
imageobject
An openly licensed image. Each image carries its own licence, author and source.
No other fields allowed.
Defined in common.schema.v0.3.0.json#/$defs/image
7 fields in image
- urlURLrequiredimage.url
  Where the file is served from (our assets folder or the original host).
  a full web address
  Pattern ^[Hh][Tt][Tt][Pp][Ss]?://
  Defined in common.schema.v0.3.0.json#/$defs/url
- licencetextrequiredimage.licence
  SPDX identifier, for example CC-BY-4.0, CC-BY-SA-4.0 or CC0-1.0.
  at least 2 characters
- authortextrequiredimage.author
  Name of the photographer or creator, as the licence requires it to be credited.
  at least 1 character
- source_urlURLrequiredimage.source_url
  Page describing the original file and its licence.
  a full web address
  Pattern ^[Hh][Tt][Tt][Pp][Ss]?://
  Defined in common.schema.v0.3.0.json#/$defs/url
- titletextimage.title
  Short caption describing what the image shows.
- widthwhole numberimage.width
  Width of the image file in pixels.
  at least 1
- heightwhole numberimage.height
  Height of the image file in pixels.
  at least 1
checked_attimestamprequired
RFC 3339 timestamp with time zone, for example 2026-11-05T14:00:00Z.
a timestamp with time zone like 2026-11-05T14:00:00Z
Defined in common.schema.v0.3.0.json#/$defs/datetime
filter_typeslist of one of a fixed set
Filters the method can use. paper: paper filters; metal: metal mesh or perforated metal; cloth: cloth filters; none: no filter (for example cezve or cold brew in a jar).
Values: paper metal cloth none
no duplicates

File structure

$schematextrequired
Canonical URL of the schema version this file follows.
Pattern ^https://schema\.roastbook\.coffee/brew-methods/brew-methods\.schema\.v[0-9]+\.[0-9]+\.[0-9]+\.json$
metaobjectrequired
File-level facts that are not records. The schema version is the $schema URL; the data version is the release tag.
No other fields allowed.
Defined in common.schema.v0.3.0.json#/$defs/dataset_meta
1 fields in meta
- licencetextrequiredmeta.licence
  Licence of the file as an SPDX licence expression, for example MIT, CC0-1.0, CC-BY-4.0, ODbL-1.0 or "MIT OR Apache-2.0". Use identifiers from the SPDX licence list (https://spdx.org/licenses/) or LicenseRef-<name> for others.
  Pattern ^$*[A-Za-z0-9][A-Za-z0-9.-]*\+?(?: WITH [A-Za-z0-9][A-Za-z0-9.-]*\+?)?$*(?: (?:AND|OR) $*[A-Za-z0-9][A-Za-z0-9.-]*\+?(?: WITH [A-Za-z0-9][A-Za-z0-9.-]*\+?)?$*)*$
  Examples: MIT, CC-BY-4.0
brew_methodslist of objectrequired
Brew method
Each entry is one Brew method record, described above.
Defined in brew-methods.schema.v0.3.0.json#/$defs/brew_method

Raw JSON

Show brew-methods.schema.v0.3.0.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schema.roastbook.coffee/brew-methods/brew-methods.schema.v0.3.0.json",
  "title": "Open Coffee brew methods",
  "description": "Ways of brewing coffee (espresso, pour-over, V60, AeroPress, cold brew…), their typical parameters and what a coffee journal should record for each. Methods form a tree: a device-specific method such as v60 has the general method pour-over as parent. Part of Roastbook Open Coffee.",
  "type": "object",
  "required": [
    "$schema",
    "meta",
    "brew_methods"
  ],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "pattern": "^https://schema\\.roastbook\\.coffee/brew-methods/brew-methods\\.schema\\.v[0-9]+\\.[0-9]+\\.[0-9]+\\.json$",
      "description": "Canonical URL of the schema version this file follows."
    },
    "meta": {
      "type": "object",
      "$ref": "https://schema.roastbook.coffee/common/common.schema.v0.3.0.json#/$defs/dataset_meta",
      "unevaluatedProperties": false
    },
    "brew_methods": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/brew_method"
      }
    }
  },
  "$defs": {
    "range": {
      "title": "Range",
      "type": "object",
      "additionalProperties": false,
      "minProperties": 1,
      "properties": {
        "min": {
          "type": "number",
          "minimum": 0,
          "description": "Lowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for water_temperature_celsius)."
        },
        "max": {
          "type": "number",
          "minimum": 0,
          "description": "Highest common value, in the unit named by the parameter."
        },
        "typical": {
          "type": "number",
          "minimum": 0,
          "description": "A good starting value, in the unit named by the parameter."
        }
      },
      "description": "A starting range. When several values are given they must be ordered: min ≤ typical ≤ max. JSON Schema cannot compare two values, so this repository checks it in its examples and data repositories check it in their data."
    },
    "parameter": {
      "title": "Brew parameter",
      "enum": [
        "dose_g",
        "brew_water_g",
        "yield_g",
        "brew_ratio",
        "yield_ratio",
        "grind_setting",
        "brew_time_seconds",
        "target_time_seconds",
        "water_temperature_celsius",
        "bloom_time_seconds",
        "bloom_water_g",
        "preinfusion_time_seconds",
        "preinfusion_pressure_bar",
        "brew_pressure_bar",
        "flow_rate_ml_per_second",
        "tamp_force_kg",
        "paper_filter_position",
        "distribution_method",
        "pour_count",
        "steep_time_seconds"
      ],
      "description": "Parameter keys shared with coffee journals such as Roastbook. brew_ratio is grams of brew water per gram of coffee (16 means 1:16); yield_ratio is grams of drink in the cup per gram of coffee (2 means a 1:2 espresso)."
    },
    "grind_size": {
      "title": "Grind size",
      "enum": [
        "extra_fine",
        "fine",
        "medium_fine",
        "medium",
        "medium_coarse",
        "coarse",
        "extra_coarse"
      ],
      "description": "Descriptive grind size; extra_fine is Turkish, fine espresso, medium filter, coarse French press and cold brew."
    },
    "brew_method": {
      "title": "Brew method",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "name",
        "category",
        "extraction",
        "description",
        "checked_at"
      ],
      "properties": {
        "id": {
          "$ref": "https://schema.roastbook.coffee/common/common.schema.v0.3.0.json#/$defs/id",
          "description": "Stable readable slug, e.g. v60, french-press. Never reused.",
          "examples": [
            "v60"
          ]
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Common English name of the method, for example Pour-over or French press."
        },
        "aliases": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Other names in any language, e.g. Filterkaffee, drip."
        },
        "parent": {
          "$ref": "https://schema.roastbook.coffee/common/common.schema.v0.3.0.json#/$defs/id",
          "description": "The more general method, e.g. pour-over for v60."
        },
        "category": {
          "enum": [
            "espresso",
            "filter",
            "immersion",
            "pressure",
            "vacuum",
            "boiling",
            "cold"
          ],
          "description": "Family used for grouping: espresso (9-bar style pressure), filter (percolation through a filter), immersion (steep, then separate), pressure (non-espresso pressure such as AeroPress or moka pot), vacuum (siphon), boiling (cezve/ibrik), cold (cold water over hours)."
        },
        "extraction": {
          "enum": [
            "percolation",
            "immersion",
            "hybrid"
          ],
          "description": "Physical principle; matches equipment brewer.mechanism."
        },
        "description": {
          "type": "string",
          "minLength": 20,
          "maxLength": 600,
          "description": "Short neutral explanation in our own words."
        },
        "introduced_year": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 2100,
          "description": "Year the method or device was invented or first sold."
        },
        "origin_country_code": {
          "$ref": "https://schema.roastbook.coffee/common/common.schema.v0.3.0.json#/$defs/country_code"
        },
        "equipment_types": {
          "type": "array",
          "uniqueItems": true,
          "description": "Equipment types needed, from the equipment schema's type list.",
          "items": {
            "$ref": "https://schema.roastbook.coffee/equipment/equipment.schema.v0.3.0.json#/$defs/type"
          }
        },
        "typical_parameters": {
          "title": "Typical parameters",
          "type": "object",
          "additionalProperties": false,
          "description": "Common starting ranges, not rules.",
          "properties": {
            "dose_g": {
              "$ref": "#/$defs/range"
            },
            "brew_ratio": {
              "$ref": "#/$defs/range",
              "description": "Grams of brew water per gram of coffee, for example 16 for 1:16. Used for filter, immersion and cold brew."
            },
            "yield_ratio": {
              "$ref": "#/$defs/range",
              "description": "Grams of drink in the cup per gram of coffee, for example 2 for a 1:2 espresso. Used where the drink is weighed, mainly espresso."
            },
            "water_temperature_celsius": {
              "$ref": "#/$defs/range"
            },
            "brew_time_seconds": {
              "$ref": "#/$defs/range"
            },
            "brew_pressure_bar": {
              "$ref": "#/$defs/range"
            },
            "grind_size": {
              "type": "array",
              "uniqueItems": true,
              "minItems": 1,
              "items": {
                "$ref": "#/$defs/grind_size"
              }
            },
            "grind_d50_microns": {
              "$ref": "#/$defs/range",
              "description": "Median particle size in micrometres, comparable across grinders."
            }
          }
        },
        "recorded_parameters": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/parameter"
          },
          "description": "Parameters a coffee journal should offer when logging a brew with this method."
        },
        "typical_drinks": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Drinks usually made with this method, in plain lowercase English, for example espresso, cappuccino or flat white."
        },
        "xref": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "wikidata": {
              "type": "string",
              "pattern": "^Q[1-9][0-9]*$",
              "description": "Wikidata item id of the method, for example Q180289 for espresso."
            },
            "beanconqueror": {
              "type": "string",
              "pattern": "^[A-Z0-9_]+$",
              "description": "Beanconqueror PREPARATION_TYPES key, for app imports."
            }
          },
          "description": "Identifiers of the method in other datasets and apps."
        },
        "image": {
          "$ref": "https://schema.roastbook.coffee/common/common.schema.v0.3.0.json#/$defs/image"
        },
        "checked_at": {
          "$ref": "https://schema.roastbook.coffee/common/common.schema.v0.3.0.json#/$defs/datetime"
        },
        "filter_types": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "enum": [
              "paper",
              "metal",
              "cloth",
              "none"
            ]
          },
          "description": "Filters the method can use. paper: paper filters; metal: metal mesh or perforated metal; cloth: cloth filters; none: no filter (for example cezve or cold brew in a jar)."
        }
      }
    }
  }
}