Schemas / brew-methods
Open Coffee brew methods v0.4.0 latest
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.4.0.json- Latest alias
https://schema.roastbook.coffee/brew-methods/brew-methods.schema.latest.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
Stable readable slug, e.g. v60, french-press. Never reused.
Defined in
common.schema.v0.4.0.json#/$defs/idCommon English name of the method, for example Pour-over or French press.
aliaseslist of textOther names in any language, e.g. Filterkaffee, drip.
parenttextThe more general method, e.g. pour-over for v60.
Defined in
common.schema.v0.4.0.json#/$defs/idFamily 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).
Physical principle; matches equipment brewer.mechanism.
Short neutral explanation in our own words.
introduced_yearwhole numberYear the method or device was invented or first sold.
ISO 3166-1 alpha-2 code in upper case.
Defined in
common.schema.v0.4.0.json#/$defs/country_codeequipment_typeslist of one of a fixed setEquipment types needed, from the equipment schema's type list.
Defined in
equipment.schema.v0.4.0.json#/$defs/typetypical_parametersobjectCommon starting ranges, not rules.
10 fields in
typical_parametersA 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.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/range3 fields in
dose_gLowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for brew_temperature_celsius).
Highest common value, in the unit named by the parameter.
A good starting value, in the unit named by the parameter.
Grams of brew water per gram of coffee, for example 16 for 1:16. Used for filter, immersion and cold brew. A journal that keeps one ratio and a basis puts the ratio here when the basis is brew water (Roastbook: ratioBasis brew_water).
Defined in
brew-methods.schema.v0.4.0.json#/$defs/range3 fields in
brew_ratioLowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for brew_temperature_celsius).
Highest common value, in the unit named by the parameter.
A good starting value, in the unit named by the parameter.
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. A journal that keeps one ratio and a basis puts the ratio here when the basis is the yield (Roastbook: ratioBasis target_yield).
Defined in
brew-methods.schema.v0.4.0.json#/$defs/range3 fields in
yield_ratioLowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for brew_temperature_celsius).
Highest common value, in the unit named by the parameter.
A good starting value, in the unit named by the parameter.
Temperature of the brew water, in degrees Celsius.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/range3 fields in
brew_temperature_celsiusLowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for brew_temperature_celsius).
Highest common value, in the unit named by the parameter.
A good starting value, in the unit named by the parameter.
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.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/range3 fields in
brew_time_secondsLowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for brew_temperature_celsius).
Highest common value, in the unit named by the parameter.
A good starting value, in the unit named by the parameter.
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.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/range3 fields in
brew_pressure_barLowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for brew_temperature_celsius).
Highest common value, in the unit named by the parameter.
A good starting value, in the unit named by the parameter.
Descriptive grind size; extra_fine is Turkish, fine espresso, medium filter, coarse French press and cold brew.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/grind_sizeMedian particle size in micrometres, comparable across grinders.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/range3 fields in
grind_d50_micronsLowest common value, in the unit named by the parameter (for example grams for dose_g, degrees Celsius for brew_temperature_celsius).
Highest common value, in the unit named by the parameter.
A good starting value, in the unit named by the parameter.
Paper filter positions commonly used with this method.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/paper_filter_positionDistribution methods commonly used with this method.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/distribution_method
recorded_parameterslist of one of a fixed setParameters a coffee journal should offer when logging a brew with this method.
Defined in
brew-methods.schema.v0.4.0.json#/$defs/parametertypical_drinkslist of textDrinks usually made with this method, in plain lowercase English, for example espresso, cappuccino or flat white.
xrefobjectIdentifiers of the method in other datasets and apps.
2 fields in
xrefWikidata item id of the method, for example Q180289 for espresso.
Beanconqueror PREPARATION_TYPES key, for app imports.
imageobjectAn openly licensed image. Each image carries its own licence, author and source.
Defined in
common.schema.v0.4.0.json#/$defs/image7 fields in
imageWhere the file is served from (our assets folder or the original host).
Defined in
common.schema.v0.4.0.json#/$defs/urlSPDX identifier, for example CC-BY-4.0, CC-BY-SA-4.0 or CC0-1.0.
Name of the photographer or creator, as the licence requires it to be credited.
Page describing the original file and its licence.
Defined in
common.schema.v0.4.0.json#/$defs/urlShort caption describing what the image shows.
Width of the image file in pixels.
Height of the image file in pixels.
RFC 3339 timestamp with time zone, for example 2026-11-05T14:00:00Z.
Defined in
common.schema.v0.4.0.json#/$defs/datetimefilter_typeslist of one of a fixed setFilters 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).
File structure
Canonical URL of the schema version this file follows.
File-level facts that are not records. The schema version is the $schema URL; the data version is the release tag.
Defined in
common.schema.v0.4.0.json#/$defs/dataset_meta1 fields in
metaLicence 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.
Brew method
Defined in
brew-methods.schema.v0.4.0.json#/$defs/brew_method
Examples
examples/brew-methods/valid/methods.json
Open this example in Playground
{
"$schema": "https://schema.roastbook.coffee/brew-methods/brew-methods.schema.v0.4.0.json",
"meta": {
"licence": "MIT"
},
"brew_methods": [
{
"id": "pour-over",
"name": "Pour-over",
"aliases": [
"Hand brew",
"Filterkaffee"
],
"category": "filter",
"extraction": "percolation",
"description": "Hot water is poured by hand over ground coffee in a filter, and the brew drips through into a cup or carafe.",
"equipment_types": [
"brewer",
"filter",
"kettle",
"grinder",
"scale"
],
"typical_parameters": {
"dose_g": {
"min": 12,
"max": 30,
"typical": 15
},
"brew_ratio": {
"min": 14,
"max": 18,
"typical": 16
},
"brew_temperature_celsius": {
"min": 88,
"max": 96,
"typical": 93
},
"brew_time_seconds": {
"min": 150,
"max": 240,
"typical": 180
},
"grind_size": [
"medium_fine",
"medium"
]
},
"recorded_parameters": [
"dose_g",
"brew_water_g",
"brew_ratio",
"grind_setting",
"brew_temperature_celsius",
"bloom_time_seconds",
"bloom_water_g",
"brew_time_seconds",
"pour_count"
],
"checked_at": "2026-11-05T12:00:00Z"
},
{
"id": "example-cone",
"name": "Example cone dripper",
"parent": "pour-over",
"category": "filter",
"extraction": "percolation",
"description": "Pour-over with a cone-shaped dripper and a paper filter; the single large hole lets the pouring speed control the flow.",
"equipment_types": [
"brewer",
"filter",
"kettle"
],
"typical_parameters": {
"brew_ratio": {
"typical": 16
},
"grind_size": [
"medium_fine"
]
},
"checked_at": "2026-11-05T12:00:00Z"
},
{
"id": "espresso",
"name": "Espresso",
"category": "espresso",
"extraction": "percolation",
"description": "Hot water is pushed at about 9 bar through a compact puck of finely ground coffee, giving a small, concentrated drink.",
"equipment_types": [
"espresso_machine",
"grinder",
"tamper",
"scale"
],
"typical_parameters": {
"dose_g": {
"min": 14,
"max": 22,
"typical": 18
},
"yield_ratio": {
"min": 1.5,
"max": 3,
"typical": 2
},
"brew_temperature_celsius": {
"min": 90,
"max": 96,
"typical": 93
},
"brew_time_seconds": {
"min": 22,
"max": 35,
"typical": 28
},
"brew_pressure_bar": {
"typical": 9
},
"grind_size": [
"fine"
],
"paper_filter_position": [
"none",
"bottom"
],
"distribution_method": [
"wdt"
]
},
"recorded_parameters": [
"dose_g",
"yield_g",
"yield_ratio",
"grind_setting",
"brew_time_seconds",
"brew_temperature_celsius",
"uses_puck_screen",
"paper_filter_position",
"distribution_method"
],
"checked_at": "2026-11-05T12:00:00Z"
}
]
}
Raw JSON
Show brew-methods.schema.v0.4.0.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schema.roastbook.coffee/brew-methods/brew-methods.schema.v0.4.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.4.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 brew_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",
"brew_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",
"uses_puck_screen",
"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). brew_temperature_celsius is the temperature of the brew water. uses_puck_screen records whether a puck screen sat on top of the espresso puck (true or false). paper_filter_position takes a paper_filter_position value and distribution_method a distribution_method value."
},
"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."
},
"paper_filter_position": {
"title": "Paper filter position",
"enum": [
"none",
"top",
"bottom",
"both"
],
"description": "Where paper filter discs sit in an espresso basket. none: no paper filter; top: on top of the coffee, under the shower screen; bottom: under the coffee, at the basket floor; both: one disc on top and one at the bottom."
},
"distribution_method": {
"title": "Distribution method",
"enum": [
"wdt",
"blind_shaker",
"distribution_tool",
"stockfleth_move"
],
"description": "How ground coffee is spread evenly in the basket before tamping. wdt: stirring with fine needles (Weiss Distribution Technique); blind_shaker: grinding into a closed cup, shaking it and tipping the coffee into the basket; distribution_tool: a spinning leveller set on the basket; stockfleth_move: sweeping the coffee level with a finger while turning the portafilter."
},
"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.4.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.4.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.4.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.4.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. A journal that keeps one ratio and a basis puts the ratio here when the basis is brew water (Roastbook: ratioBasis brew_water)."
},
"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. A journal that keeps one ratio and a basis puts the ratio here when the basis is the yield (Roastbook: ratioBasis target_yield)."
},
"brew_temperature_celsius": {
"$ref": "#/$defs/range",
"description": "Temperature of the brew water, in degrees Celsius."
},
"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."
},
"paper_filter_position": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/paper_filter_position"
},
"description": "Paper filter positions commonly used with this method."
},
"distribution_method": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/distribution_method"
},
"description": "Distribution methods commonly used with this method."
}
}
},
"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.4.0.json#/$defs/image"
},
"checked_at": {
"$ref": "https://schema.roastbook.coffee/common/common.schema.v0.4.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)."
}
}
}
}
}