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
environment: my-env

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	`active` or `inactive`. An inactive flow will not invoke.
`environment:`	optional	Default environment this flow runs against (overridable at invocation).
`using:`	optional	Imports operator families and/or bare connections (see Connections).
`input:`	optional	The typed input signature. Tag + optional default.
`output:`	required where the flow returns	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 is in the flow language reference.

What goes where

The rest of this section walks each part in depth:

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