The Shape of a Flow

Every flow file has the same skeleton. Most blocks are optional — a one-step flow only needs steps:.

version: "1.0.0"
status: active

using:
  - zenvara/http
  - zenvara/jira

input:
  city: !str Berlin

output:
  temperature: !float

steps:
  - $weather:
      invoke: http.get
      with:
        Url: "https://api.example.com/weather?city=${city}"
  - return:
      temperature: "${weather.body.temp}"

Read top to bottom: declare what the flow imports, what it accepts, what it produces, and how to get from one to the other.

The top-level blocks

Block	Required?	Purpose
`version:`	optional	Flow-format version for forward-compat; only the major is checked at load.
`status:`	optional	One of `draft`, `active`, `disabled`, `archived` (defaults to `active`). `inactive` is not a valid value and is rejected at runtime. Use `disabled` to deactivate a flow without invoking.
`using:`	optional	Imports connector families and environments (`- environment/prod`) — the first environment entry is the flow default; a step picks another with `on:`. See Connections.
`input:`	optional	The typed input signature. Tag + optional default.
`output:`	required	The typed output contract — both docs and a runtime check.
`let:` / `vars:` / `persist:`	optional	State blocks — see State.
`triggers:`	optional	What fires the flow — see Triggers.
`steps:`	required	The pipeline itself.

Typed inputs

Inputs are declared with a type tag; the value after the tag is the default. Omit the value to make the field required.

input:
  city: !str Berlin     # optional, defaults to "Berlin"
  limit: !int           # required — no default
  verbose: !bool false
  tags: !str-list

Common tags: !str, !int, !float, !bool, !obj, !str-list, !obj-list. The full tag set — including !enum, the ? optional suffix, and defaults — is in the Flow Language Reference.

What goes where

The rest of this section walks each part in depth:

Steps & the with: block — actions, bindings, step-level overrides.
Values & Expressions — ${path}, ${= expr}, ${secret:path}.
State — let:, vars:, persist:.
Control Flow — if:, for-each:, switch:, stop:.
Transformers — join:, delta:, filter:.
Output Contract — output: and return:.
Composing Flows — calling one flow from another.
Common Pitfalls — the rakes flow authors step on.