3.1: wort clarity and krausen handling on the fermentation procedure #279

What cannot be represented today

Hosom's SMPH model (IBUs and the SMPH model) estimates IBUs from the whole brew day, not only the boil. It needs two observations that brewers make but the format cannot carry:

• Wort clarity: "how visually clear or cloudy the wort is when it is transferred to the fermentation vessel". Cloudy wort (a short vorlauf, brew in a bag) ends up with more bitterness than clear wort.
• Krausen handling: whether the krausen falls back in, dries on the vessel walls, is skimmed, or leaves through a blow-off tube. Isomerized alpha acids collect in the krausen, so the last three lose bitterness.

Every other SMPH input already has a home:

Proposed change

FermentationProcedureType, both optional:

• wort_clarity: enum "very clear", "clear", "somewhat cloudy", "cloudy", "very cloudy". How clear the wort looks, judged by eye, when it is transferred to the fermenter.
• krausen_handling: enum "mixed in", "left on walls", "skimmed", "blown off". What happens to the krausen during fermentation. "mixed in" also covers an anti-foam that keeps it from forming.

Both describe the wort and the fermentation rather than the calculation, so a program that doesn't estimate IBUs can still record them.

Example

{
  "beerjson": {
    "version": 3.1,
    "fermentations": [
      {
        "name": "Ale, blow-off tube",
        "wort_clarity": "somewhat cloudy",
        "krausen_handling": "blown off",
        "fermentation_steps": [
          {
            "name": "Primary",
            "start_temperature": { "unit": "C", "value": 19 },
            "step_time": { "unit": "day", "value": 10 }
          }
        ]
      }
    ]
  }
}

I applied the change to a copy of the schemas, with 3.1 added to VersionType, and checked it with Ajv (draft 2020-12): this example validates, an unknown krausen_handling value is rejected, and every document under tests/ still validates. I have not run the jest suite.

Compatibility

• Additive. Every 3.0 document stays valid. As with any minor version (ADR-0004), a 3.0 validator rejects a 3.1 document that uses the new fields.
• Breaking.

Alternatives

• A measured turbidity (NTU or EBC haze units) instead of a visual scale: more precise, but homebrewers don't measure wort haze, and SMPH takes a visual judgment. A measurement can sit next to the scale later if software needs it.
• On each fermentation step instead of the procedure: the krausen forms during primary only, and the clarity is a single observation at transfer, so per-step fields would be repeated or empty.
• Notes: not machine-readable, so an IBU estimate cannot use them.

Software support

• Werb: needs both for its SMPH work (IBU model: adopt the full SMPH (Specific-Model-of-IBU) calc engine werb-dev/werb#27), which waits on the format. I can implement reading and writing there.
• Other programs that don't model post-boil losses can ignore them.

Checklist

• I have searched existing issues and discussions
• I have checked whether measureable_units.json already has a suitable measurement type (both are categorical, so no measurement type applies)
• I have read SCHEMA_STYLE.md