Workflow YAML reference

Workflow YAML reference

A workflow is a YAML definition interpreted by Viat, not a script language or durable job engine. Seven native step variants exist: script, if, parallel, for_each, while, until, workflow. The variant is identified by the presence of its key, not a type: discriminator. Each entry must contain exactly one of those variant keys. There is no native approval, wait-event, durable checkpoint or external-job step.

Root grammar

Key	Type, required/default and meaning
inputs	Mapping, default {}. Keys declare names available under $inputs; values may be shorthand metadata (e.g. string) or mappings (e.g. {type: string, default: world}).
steps	Required sequence of entries, executed in declaration order except explicit fan-out. Empty sequence is valid; omitted steps is invalid.
outputs	Mapping, default {}. Recursively resolve values after successful execution; this mapping is the workflow return value. Omitting it returns {}, not the last step.
timeout	Optional unsigned seconds. Positive values select the total budget; absent/zero/unusable falls back at admission to project/deployment default; deployment ceilings apply. Not a separate timeout per step.
max_concurrent	Optional positive u32 background-run limit; no default target limit. Zero/invalid is not “paused.”
concurrency_key	Optional shared budget name [A-Za-z_][A-Za-z0-9_-]{0,63}; meaningful only with max_concurrent; absent uses workflow identity.

Input metadata is not a full runtime JSON Schema validator in this engine. A mapping’s default is explicitly applied to missing keys before any step; caller-supplied null is not overwritten. default: null allows a resolvable null rather than a missing-path error. Declared names and references are checked, but do not rely on {type: integer} alone to reject a string. Validate in a script or configure endpoint parameter bindings when strict validation is required. A workflow does not gain a script’s extracted main schema automatically.

Every named entry uses id: [a-z][a-z0-9_]*, globally unique across the entire definition including branches, catches and loops. Parallel blocks have no own output ID. References can use only inputs and outputs already visible in scope, not future steps. Unknown extra YAML fields are not a safe extension mechanism: an ignored type, timeout or retry on the wrong variant does not implement that feature.

Complete no-resource example

Create script asset wf_echo from scripts/wf_echo.py:

def main(value):
    return value

Save workflows/echo.yaml:

inputs:
  value:
    type: string
    default: world
steps:
  - id: echo
    script: wf_echo
    args:
      value: $inputs.value
outputs:
  value: $echo.output

viat script create --name wf_echo --language python --file scripts/wf_echo.py
viat workflow create echo_flow --file workflows/echo.yaml
viat workflow test echo_flow --input '{"value":"Ada"}'
viat workflow test echo_flow --input '{}'
viat workflow update echo_flow --file workflows/echo.yaml

Expected result bodies are {"value":"Ada"} and {"value":"world"}. Test runs the current saved draft, with real runtime/resource effects if your steps have any; this fixture has none. Python execution requires uv/Python. Needs project authoring/execution access; the authenticated test identity is not proof of public caller access.

Publish and cleanup

viat endpoint create --segment flow --method POST --workflow echo_flow
viat endpoint publish ENDPOINT_ID

Replace ENDPOINT_ID with the creation response’s ID. Endpoint authentication/parameter configuration still applies; method/path creation alone is not an auth policy. Publication bakes workflow YAML, step script main sources, nested definitions and endpoint configuration. Later draft edits do not change that endpoint until republish. Step uses modules remain live in 1.1.0, including nested steps; see limits and snapshots. Direct test/schedule targets build from live definitions. Resource values are resolved at run time rather than all credentials being embedded in the published YAML.

For a disposable example, unpublish and delete the endpoint, then viat workflow delete echo_flow and viat script delete wf_echo after confirming no other workflow depends on them. Deletion does not undo prior script side effects. No online run or cleanup was performed here.

Composition rules

Script/workflow args and final outputs resolve whole-value references recursively; there is no embedded string interpolation. If/catch wrappers return their chosen branch’s last entry value; inner IDs do not escape. Parallel makes successful child outputs visible under their child IDs. For_each returns an ordered result array; while/until return sequential result arrays. A parallel body itself has no aggregate output, so a wrapper ending in parallel yields null rather than an invented branch map. Expressions, error handling and the individual step pages give exact scopes, defaults and examples.