Cookpit v3.2 — Canonical Unit Vocabulary

The unit vocabulary referenced by cookpit.ingredients[].unit, cookpit.ingredients[].metricUnit, ingredient.alternative.unit, ingredient.alternative.metricUnit, ingredient.choices[].unit, ingredient.choices[].metricUnit and similar fields.

The schema currently treats unit as a free-text string. This document publishes the canonical vocabulary so that two implementations consuming unit: "tbsp" interpret it identically. Future revisions of the schema MAY add enum validation against this vocabulary.

---

1. Unit classes

The vocabulary partitions into seven classes. Within a class, units are interchangeable for arithmetic (g and kg for mass; ml, cl and l for volume); across classes, they are not.

1.1 Standard metric mass

Unit	Meaning	Notes
g	gram	base unit
kg	kilogram	1 kg = 1000 g
mg	milligram	1 g = 1000 mg (rarely used)

1.2 Standard metric volume

Unit	Meaning	Notes
ml	millilitre	base unit
cl	centilitre	1 cl = 10 ml; recur in wine refs
l	litre	1 l = 1000 ml

1.3 UK measure

Unit	Meaning	Notes
tbsp	tablespoon (15 ml UK)
tsp	teaspoon (5 ml UK)
heaped tbsp	heaped tablespoon	"heaped" is a usage modifier
heaped tsp	heaped teaspoon
level tbsp	level tablespoon	for explicit level measurement
level tsp	level teaspoon
dsp	dessertspoon (10 ml UK)	uncommon in modern UK recipes

1.4 Imperial mass

Unit	Meaning	Notes
oz	ounce	1 oz ≈ 28.35 g
lb	pound	1 lb = 16 oz
stone	stone	1 stone = 14 lb (almost never in cooking)

1.5 Imperial volume

Unit	Meaning	Notes
fl oz	fluid ounce (UK ≈ 28.4 ml; US ≈ 29.6 ml)	UK fl oz is the default in the corpus
pint	pint (UK ≈ 568 ml; US ≈ 473 ml)	UK pint is the default
cup	cup (US ≈ 240 ml; UK occasionally)	mostly US-source recipes

1.6 Count and structural

Unit	Meaning
count	discrete countable item ("3 large eggs", "1 onion")
clove	garlic clove
sprig	herb sprig
bunch	bunch (parsley, watercress, etc.)
cube	cube (stock cube, sugar cube)
slice	slice (bread, ham, prosciutto)
head	head (lettuce, garlic — a whole bulb)
pod	pod (vanilla pod, broad bean pod)
stick	stick (celery, butter where blockwise)
leaf	leaf (bay leaf, gold leaf)
pinch	pinch (qualitative seasoning)
dash	dash (qualitative liquid seasoning)
splash	splash (qualitative liquid)
knob	knob (butter — about 25 g)
handful	handful (qualitative volume)
cm	length-scaled (e.g. 2 cm piece of ginger)
inch	length-scaled imperial (e.g. 2 in piece)

1.7 Semantic (cook-role)

Unit	Meaning
toTaste	quantity is determined by the chef's taste at finish (salt, pepper, lemon juice). Pair with quantity omitted.
toServe	quantity is determined by the diner's preference at table (parmesan, pepper, soured cream). Pair with quantity omitted, and consider optional: true.
asNeeded	quantity is determined by the dish's runtime state (extra pasta water, more oil between sears). Pair with quantity omitted.
forGreasing	quantity is determined by the surface area being greased ("plus extra for greasing"). Use alongside the primary quantity rather than on a separate ingredient.

---

2. Combining mass and volume on one ingredient

Source recipes routinely express the same quantity in both metric mass and imperial mass, or both metric volume and imperial volume. The schema's pattern is:

{
  "id": "i...",
  "text": "Pork belly",
  "quantity": 500,           // canonical value
  "unit": "g",                // canonical unit
  "metricQuantity": 500,      // optional duplicate of canonical (skipped where canonical is metric)
  "metricUnit": "g",
  "metricApproximate": false  // true if rounded
}

When the source carries both metric and imperial (500g/1lb 2oz), the canonical pair is metric. The imperial value is preserved in the source pass-through (recipeIngredient[]) and may also appear in the alternative or choices[] sub-objects if it represents a true alternative form.

---

3. Examples from the active corpus

Source phrase	Canonical encoding
1.6kg/3lb 8oz braising steak (boeuf)	quantity: 1.6, unit: "kg"
4–5 tbsp sunflower oil (boeuf)	quantity: 5, unit: "tbsp" (chef-detective takes upper bound for closed-world plan; range preserved in recipeIngredient[])
75cl bottle red wine (boeuf)	quantity: 75, unit: "cl"
2 garlic cloves, crushed (boeuf)	quantity: 2, unit: "clove"
2 heaped tbsp cornflour (boeuf)	quantity: 2, unit: "heaped tbsp"
1/2 cauliflower (pork-fillet-braised-cheeks-and-pork-belly)	quantity: 0.5, unit: "count"
salt and freshly ground black pepper (carbonara)	(split into two ingredients) unit: "toTaste" (no quantity)
chopped fresh parsley, to garnish (boeuf)	unit: "toServe", optional: true

---

4. Conformance

A v3.2 file is conformant with this vocabulary when every unit / metricUnit value in the file appears in the tables in §1. Files using non-vocabulary values (e.g. "jar", "can", "tin", "packet") should migrate to the structural container field already in the schema:

{
  "id": "i...",
  "text": "Lemon curd",
  "quantity": 325,
  "unit": "g",
  "container": { "type": "jar", "quantity": 1 }
}

The container field is the right place for packaging-as-context rather than unit.

---

5. Future revisions

This is the v3.2.0 vocabulary. Future revisions add units (Indian mug, Spanish cazo, US stick of butter if the corpus needs it). Implementations SHOULD treat unknown units as soft warnings rather than hard rejections, allowing the corpus to grow without breaking older files.