Recipe schema

A condensed field reference for recipe authors. For the narrative introduction, read Authoring recipes first.

#Envelope

{
  "recipe_id": "detect-deal-risk-hubspot",
  "version": 1,
  "ttl": 600,
  "metadata": {},
  "variables": {},
  "requires": [],
  "depends_on": [],
  "chat_exposed": false,
  "trigger": [],
  "event_triggers": [],
  "webhook_triggers": [],
  "auto_run": null,
  "trigger_steps": null,
  "run_mode": null,
  "provenance": true,
  "prefetch_steps": [],
  "steps": [],
  "output": {}
}

#metadata

#Steps

{
  "id": "risky",
  "transform": "filter",
  "array": "{{step.deals}}",
  "field": "stage",
  "operator": "equal",
  "value": "at_risk",
  "skip_when": "{{step.deals}} is_empty"
}

The step type is inferred from which field is present:

Execution flow, identical for every step:

skip_when? → compute → step.<id> = result → fail_on?

• skip_when true → the step stores null and the recipe continues.
• fail_on true (evaluated after compute) → the recipe halts.
• foreach iterates an array input, binding {{item.*}} per iteration; the step's output is one envelope per element, { ok, result?, error?, item }, in source order.
• Prefetch steps additionally accept "optional": true — a failure stores null instead of halting the run.

Trigger-phase steps (trigger_steps) use the same shape. Every one must return should_run: true for the reactive tick to proceed; their outputs land on {{trigger.<id>.*}} for downstream steps.

#Variables

Two forms. A bare value is a constant you tuned; its type is inferred and the one-shot run form leaves it alone. An object is a question for whoever runs the recipe, and gets its own field on that form.

"variables": {
  "recipient":  { "label": "Send to", "type": "text" },
  "window":     { "label": "Window", "type": "enum", "options": ["7d", "30d"] },
  "max_rows":   50,
  "deal_id":    null
}

A tuning constant stays editable everywhere tuning belongs — the install dialog, the recipe editor, and the Schedule and Trigger tabs, where "run nightly with window: 30d" is legitimate setup. Only the one-shot run form stops asking.

#Object-form fields

These are the only fields that exist. Anything else is refused when you install, so an invented field fails loudly instead of being quietly ignored.

There is no required field: optional is the one that exists, and leaving it out already means required. There is no pattern either — validate the shape of a value with a guard step, since a declaration says what a value is called and how it is collected, never what counts as valid.

#Types

Unlike the field list, type is open. These drive a specific control:

text · number · boolean · enum (with options) · datetime · url · secret · oauth · file_slug · file_ref · file_ref[]

These are admitted too and are widely used. connection and service_ref get their own pickers; the rest render as a plain text control:

string · array · object · json · connection · service_ref

string is by far the most common type in shipped recipes and behaves as text. Any other non-empty string installs and renders as text, so the set can grow without invalidating what you have already published — which is exactly why an unknown type is admitted while an unknown field is not. A type has a sensible fallback; a field nobody reads has none.

#A caller may only pass what you declared

If a chat request, an MCP call, a button, or a schedule overlay hands your recipe a name that is not in variables, the run is refused rather than ignoring it. So every argument you want to accept has to be declared, and a leftover name you no longer read has to go.

Give a default only where a sensible one exists. A required input with a placeholder default — an empty string, a zero, an empty list — is not required at all: the caller can omit it and the recipe runs with the placeholder.

#Value system

"literal"              → use as-is
"{{ref}}"              → resolve, preserve type
"{{ref:format}}"       → resolve; the hint applies only during interpolation
"text {{ref}} text"    → interpolate → string
10, true, false        → native JSON type
null                   → required from caller

Format hints: :currency, :number, :date, :relative, :percent.

#Conditions

Inline strings, one condition per field, one operator per condition. Literals are bare — equal closed_won, never equal 'closed_won'.

Object form for array values:

{ "field": "{{step.x}}", "operator": "in", "value": ["a", "b"] }

Compound logic is a transform step (any / all) whose stored boolean you check; and / or do not exist inside condition strings.

#Namespaces recipes can reference

{{vault.*}} is ingredient-only — recipes never see credential material. Vendor read-side aliases (data.hubspot.*, data.salesforce.*, data.crm.*) resolve enrichments on CRM records, with static ids only.

#Engine-injected context

#Transforms

Per-transform parameters live in the transforms reference. Tier 1 — atomic:

Tier 2 — compound conveniences: find, pluck, sum, min_by, max_by, percent, join, group_by with aggregate.

Notable modes: filter accepts mode: "all" | "any" with a conditions array for multi-condition filtering in one step; map accepts an expression over {{item.*}} (a single ref, a math expression, or an object template), with output_field to attach the computed value to each item instead of replacing it.

#AI functions

Batch mode: every function except ai-compare accepts an array llm.data plus a non-empty llm.id_field — one model call, returning a per-element array in input order, each element the source record merged with the result fields. Model hints: fast, quality, thinking.

#Output

"output": {
  "render": [
    { "type": "summary", "source": "step.overview", "label": "Overview" },
    { "type": "ai_analysis", "source": "step.analysis" }
  ]
}

Pure routing, no logic — a null source is not rendered. Section types:

render is the only channel by which a run's data reaches any reader. A step result that is not routed into a section is unreachable — by a person, and by a model. Reach for json when a reader needs to check the work behind a summary.

The filter block is the one section that is not { type, source, label }. It also carries fields (declared variable keys shown as controls), hidden (declared keys carried on submit but never displayed, a paging cursor being the usual case), and submit (the button text). Every control is derived from the variable's own declaration, so there is no per-field styling to write.

#When Recued refuses your recipe

Validation names what it rejected. The ones authors meet most:

orphan_step and ttl_below_floor are advisory rather than refusals: a step nothing reads, and a cache TTL below the practical floor.

#Naming

Recipe:      {action}-{entity}-{qualifier}-{platform}    detect-deal-risk-hubspot
Ingredient:  {action}-{entity}-{platform}                deal-reader-hubspot
AI:          ai-{function}                               ai-score
Vendor:      {action}-{vendor}                           search-exa

Platform always last — this is what lets variant_group collapse cross-platform families into one marketplace card.