Schemas / brew-methods

Open Coffee brew methods v0.1.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.1.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_.-]+$
Example: v60
Defined in common.schema.v0.1.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_.-]+$
Example: cp-7k2m9x4qvd
Defined in common.schema.v0.1.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.1.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.1.0.json#/$defs/type
typical_parametersobject
Common starting ranges, not rules.
No other fields allowed.
7 fields in typical_parameters
- dose_gobjecttypical_parameters.dose_g
  Range
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.1.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
- ratioobjecttypical_parameters.ratio
  Range
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.1.0.json#/$defs/range
  3 fields in ratio
  - minnumbertypical_parameters.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.ratio.max
    Highest common value, in the unit named by the parameter.
    at least 0
  - typicalnumbertypical_parameters.ratio.typical
    A good starting value, in the unit named by the parameter.
    at least 0
- water_temperature_celsiusobjecttypical_parameters.water_temperature_celsius
  Range
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.1.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
  Range
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.1.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
  Range
  not empty
  No other fields allowed.
  Defined in brew-methods.schema.v0.1.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.1.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.1.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 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.1.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.1.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 ^https?://
  Defined in common.schema.v0.1.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 ^https?://
  Defined in common.schema.v0.1.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.1.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.1.0.json#/$defs/dataset_meta
1 fields in meta
- licenceexactly "MIT"requiredmeta.licence
  Licence of the file: MIT, with the copyright notice “Roastbook Open Coffee contributors”.
  Always MIT
brew_methodslist of objectrequired
Brew method
Each entry is one Brew method record, described above.
Defined in brew-methods.schema.v0.1.0.json#/$defs/brew_method

Raw JSON

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schema.roastbook.coffee/brew-methods/brew-methods.schema.v0.1.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.1.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."
        }
      }
    },
    "parameter": {
      "title": "Brew parameter",
      "enum": [
        "dose_g",
        "brew_water_g",
        "yield_g",
        "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. ratio is brew water to coffee (16 means 1:16); for espresso it is yield to dose (2 means 1:2)."
    },
    "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.1.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.1.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.1.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.1.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"
            },
            "ratio": {
              "$ref": "#/$defs/range"
            },
            "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.1.0.json#/$defs/image"
        },
        "checked_at": {
          "$ref": "https://schema.roastbook.coffee/common/common.schema.v0.1.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)."
        }
      }
    }
  }
}