Conventions

These conventions keep .food.yaml files consistent and machine-friendly. None are enforced by the parser, but tools and exporters work best when you follow them.

File naming

Use the .food.yaml extension. Name files in kebab-case after the dish: simple-latte.food.yaml, tomato-sauce.food.yaml.

Ingredient names

Use lowercase, human words: coffee grounds, not CoffeeGrounds.
Keep names stable — transformations and the robot action graph reference ingredients by name, so renaming an ingredient means updating its references too.

States and processing

processing on a base ingredient lists how it arrives: [ground], [cold], [diced].
state on a transformation input/output describes the ingredient at that point in the process: ground, brewed, steamed, simmered.

A transformation is read as inputs:state -> outputs:state:

milk:cold -> steamed milk:steamed + microfoam:foamed

Amounts vs. measured values

Two amount shapes exist, on purpose:

Base recipe ingredients use { amount, unit } (ORF style):
```
amounts:
  - amount: 220
    unit: mL
```
X-foodlang transformations use the measured { value, unit } form:
```
amount: { value: 220, unit: mL }
```

Units

Prefer unambiguous unit tokens: g, mL, Cel, bar, s. These map cleanly to UCUM/OPC UA and survive round-tripping better than °C or ml.

Transformation and action ids

ids are snake_case and unique within a recipe: extract_espresso.
Robot action ids are referenced by depends_on; dangling references are flagged as warnings during validation.

Exports block

The exports map documents intent — which outputs the author cares about. The compiler can still produce any target regardless of these flags.

exports:
  cooklang: true
  schema_org_jsonld: true
  robot_action_graph: true