equipment@1

Equipment

Resources

• Schema
• Back to Stacks Index

Documentation

#equipment@1

---

Purpose

The equipment@1 stack enables recipes to declare required equipment, with optional scaling-aware counts and upgrade paths for different scale factors.

This stack is adoption-first: equipment can be declared as simple strings for minimal friction, or as structured objects with IDs for cross-referencing from steps.

---

Requirements

A document that declares equipment@1:

• MUST satisfy all structural rules enabled by this stack. • MUST satisfy the semantic rules described below.

---

Data Model

When equipment@1 is declared, the document MUST include a top-level equipment array.

Equipment Array

The equipment array contains one or more items. Each item MAY be:

• A string (simple tool name) • A structured equipment object

Structured Equipment Object

Structured equipment objects support:

• id (required): unique identifier following pattern ^[A-Za-z0-9._-]+$ • name (required): human-readable name • count (optional): integer >= 1, default 1 • countScaling (optional): scaling behavior for count • upgrades (optional): array of upgrade rules

---

Scaling Behavior

Equipment scaling is defined in terms of a scale factor F. If no scaling factor exists in the document, implementations MUST treat F = 1.

countScaling

The countScaling field controls how equipment count changes with scale:

fixed

Count remains unchanged regardless of scale factor.

{
  "id": "pan",
  "name": "8-inch skillet",
  "count": 1,
  "countScaling": "fixed"
}

linear

Effective count = ceil(count × F)

{
  "id": "mixing_bowl",
  "name": "Mixing bowl",
  "count": 2,
  "countScaling": "linear"
}

threshold

Pick the first step where F <= maxFactor, otherwise use the last step.

{
  "id": "sheet_pan",
  "name": "Baking sheet",
  "count": 1,
  "countScaling": {
    "mode": "threshold",
    "steps": [
      { "maxFactor": 1.0, "count": 1 },
      { "maxFactor": 2.0, "count": 2 },
      { "maxFactor": 4.0, "count": 3 }
    ]
  }
}

The steps array MUST be non-empty. Steps SHOULD be in ascending order by maxFactor (semantic validation may enforce this in tooling).

upgrades

The upgrades array allows swapping to a different equipment item at higher scale factors.

Choose the upgrade with the highest minFactor where minFactor <= F. If no upgrade matches, use the base equipment item.

{
  "id": "skillet_small",
  "name": "8-inch skillet",
  "upgrades": [
    { "minFactor": 2.0, "use": "skillet_large" }
  ]
}

The use field MUST reference an equipment id that exists in the equipment array (semantic validation).

---

Step Usage

When structured@1 is present (steps are objects), steps MAY include an optional usesEquipment field.

Field step.usesEquipment : array of equipment ids

Each id in usesEquipment MUST exist in the equipment array (semantic validation when both stacks are present).

Example:

{
  "equipment": [
    { "id": "skillet", "name": "8-inch skillet" }
  ],
  "instructions": [
    {
      "id": "sear",
      "text": "Sear the meat",
      "usesEquipment": ["skillet"]
    }
  ]
}

---

Composition

The equipment stack is composable with other stacks:

• No hard dependency on scaling@1 (scaling behavior uses factor if present, but does not require scaling stack) • Works with structured@1 to enable step-level equipment references • Remains monotonic: does not close objects needed by other stacks

---

Semantic Validation Rules (Normative)

Validators MUST enforce the following rules:

1. Equipment id uniqueness All equipment object id values MUST be unique within the equipment array.

2. Step equipment references If both equipment@1 and structured@1 are present, and a step includes usesEquipment, all referenced ids MUST exist in the equipment array (as object ids, not string items).

3. Upgrade references If an equipment item includes upgrades, each upgrades[].use MUST reference an existing equipment object id.

4. Threshold steps ordering For countScaling.mode == "threshold", the steps array SHOULD be in ascending order by maxFactor (tooling may warn but not fail validation).

---

Examples

Simple strings

{
  "equipment": ["mixing bowl", "whisk", "oven"]
}

Structured with scaling

{
  "equipment": [
    {
      "id": "skillet",
      "name": "8-inch skillet",
      "count": 1,
      "countScaling": "fixed"
    },
    {
      "id": "bowl",
      "name": "Mixing bowl",
      "count": 2,
      "countScaling": "linear"
    }
  ]
}

With upgrades

{
  "equipment": [
    {
      "id": "skillet_small",
      "name": "8-inch skillet",
      "upgrades": [
        { "minFactor": 2.0, "use": "skillet_large" }
      ]
    },
    {
      "id": "skillet_large",
      "name": "12-inch skillet"
    }
  ]
}

Step usage

{
  "equipment": [
    { "id": "skillet", "name": "8-inch skillet" }
  ],
  "instructions": [
    {
      "id": "sear",
      "text": "Sear the meat in the skillet",
      "usesEquipment": ["skillet"]
    }
  ]
}