scaling@1

Scaling

Depends On

Resources

Documentation

#scaling@1

Purpose

The scaling@1 stack standardizes how ingredient quantities change when a recipe is scaled, so independent implementations produce consistent results.

This stack is intended to support the Scalable profile.

Requirements

A document that declares scaling@1:

• MUST declare quantified@1. • SHOULD declare structured@1 (recommended for stable ingredient IDs). • MUST satisfy all structural rules enabled by this stack. • MUST satisfy the semantic rules described below.

Data Model

When scaling@1 is declared, quantified ingredients MAY include an optional scaling field.

Field ingredient.scaling : ScalingRule

ScalingRule is defined in defs/scalingRule.schema.json and is a closed object with a required mode.

Scaling Modes

linear

Multiply the ingredient quantity by the scale factor.

mode = "linear"

If scaling is omitted, implementations MUST treat the ingredient as linear by default.

fixed

Do not scale this ingredient quantity.

Examples: • 1 bay leaf • 1 cinnamon stick • 1 pan

mode = "fixed"

discrete

Scale using discrete increments (for example, whole eggs), with optional rounding and bounds.

Fields • mode = "discrete" • step (optional, > 0): discrete increment size • rounding (optional): nearest | ceil | floor • min (optional): minimum allowed result • max (optional): maximum allowed result

Semantic defaults • If step is not present, default is 1 • If rounding is not present, default is nearest

toTaste

Quantity is informational and MUST NOT be mechanically scaled.

Examples: • salt to taste • pepper to taste

mode = "toTaste"

bakersPercent

Represents the ingredient quantity as a baker’s percentage of a base ingredient (typically flour).

Fields • mode = "bakersPercent" • percent (> 0): percentage value (for example, 70 for 70%) • of (string): ingredient id of the base ingredient

Scale Factor

Scaling is applied using a scale factor F.

How F is selected depends on the consumer implementation:

• Some consumers may accept an explicit factor (for example, “2x”). • Some consumers may compute F from yield changes (for example, “scale from 4 servings to 6 servings”).

This stack standardizes how ingredient rules respond to F, not how F is chosen.

Semantic Validation Rules (Normative)

Validators MUST enforce the following rules:

  1. Prerequisite If scaling@1 is declared, quantified@1 MUST also be declared.

  2. Baker’s percent reference For mode = "bakersPercent", the of field MUST resolve to an existing ingredient id.

  3. Discrete sanity For mode = "discrete", if both min and max are present, min MUST be less than or equal to max.

  4. Closed rule objects ScalingRule MUST NOT contain unspecified fields. This is enforced by schema.

Consumers MUST apply the following semantic defaults:

• Missing scaling ⇒ treat as linear • discrete.step default = 1 • discrete.rounding default = nearest

Scaling Behavior (Normative)

Given an ingredient with base quantity amount A and scale factor F:

• linear scaled amount = A × F

• fixed scaled amount = A

• toTaste scaled amount = A (informational only) Consumers MAY hide numeric scaling UI for this item.

• discrete

  1. raw = A × F
  2. if step is present, units = raw ÷ step
  3. apply rounding to units
  4. scaled = units × step
  5. clamp to min / max if present

• bakersPercent

  1. let B be the amount of the ingredient referenced by of
  2. scaled amount = B × (percent ÷ 100)

Examples

Linear (default)

Ingredient id: i_sugar name: Sugar quantity: 100 g (no scaling field → treated as linear)

Fixed

Ingredient id: i_bayleaf name: Bay leaf quantity: 1 leaf scaling: mode = fixed

Discrete (eggs)

Ingredient id: i_eggs name: Eggs quantity: 2 egg scaling: mode = discrete, rounding = ceil

To taste

Ingredient id: i_salt name: Salt quantity: 1 tsp scaling: mode = toTaste

Baker’s percent

Ingredient A id: i_flour name: Flour quantity: 500 g

Ingredient B id: i_water name: Water quantity: 350 g scaling: mode = bakersPercent, percent = 70, of = i_flour

Fixtures

Implementations SHOULD include fixtures covering:

Valid cases • linear default (no scaling rule) • discrete with rounding • fixed • toTaste • bakersPercent with resolvable of

Invalid cases • scaling declared without quantified • bakersPercent with missing or invalid of • invalid rounding value • discrete with min greater than max