YAML syntax reference

The machine-readable schema is at https://nika.sh/schema/workflow.json. Point your editor at it for live validation. See editor setup.

Top level

the envelope · illustration, not a runnable file

# <description> · prose about the workflow lives in a comment above the mark
nika: <identifier>           # required · the MARK and the NAME · kebab-case · no version, ever

model: <provider>/<name>     # optional · default model for infer/agent tasks

# the three value authorities · one role each · no other value namespace exists
inputs: { ... }              # optional · TYPED · the caller supplies at launch · ${{ inputs.* }}
const:  { ... }              # optional · fixed in the file · never caller-supplied · ${{ const.* }}
secrets: { ... }             # optional · vault/env/file references · masked · ${{ secrets.* }}

permits: { ... }             # optional KEY · but ABSENT = zero authority (see below)
run: { ... }                 # optional · the run's entropy + clock declaration

tasks: { ... }               # required · non-empty MAP · the key IS the task id

outputs: { ... }             # optional · the workflow's return value

Nine keys, closed. nika: is the type discriminant and the identity: a tasks: key makes the document a workflow, its absence makes it a project file (nika.yaml, whose mark is nika: <project-name> — a kebab-case identity, the same line nika init --project-file writes), and the filename carries no verdict — a registry blob, an HTTP body, a stdin pipe (nika check -) must say what they are by their bytes alone. nika: v1 on a project file is the retired schema tag (the reader refuses it: the tag became the name). nika: v1 + workflow: { id } is the previous workflow envelope (through 0.108): nika check --fix migrates it, moving the identity onto nika: and the description: prose into a comment above it.

The three value authorities

Every value a workflow declares lands under exactly one of three authorities. The family is closed — a value-namespace read outside it is NIKA-VALUES-003.

Authority	Who supplies it	Shape	Integrity
`inputs:`	the caller, at launch (`--var k=v` · an MCP `nika.run_workflow` argument) — a deployment knob is an input with a `default:`	`{ type, required?, default?, description? }` · `type:` required	untrusted
`const:`	the file · immutable across the run, never caller-supplied	a bare literal, or `{ type, value }`	trusted
`secrets:`	a governed store · masked everywhere	`{ source: vault\|env\|file, key\|path, egress? }`	trusted

inputs:
  topic:     { type: string, required: true, description: "Subject to research" }
  bullets:   { type: integer, default: 3 }
  log_level: { type: string, required: false, default: "info" }   # the deployment's knob
const:
  output_dir: "./output"                 # the file owns the destination
secrets:
  api_key: { source: env, key: OPENAI_API_KEY }

The integrity column is not decoration: under a permits: block an untrusted value that reaches a verb argument is re-gated on its canonical resolved form, and an escape is refused NIKA-AUTH-008. That is the practical reason a destination the boundary pins belongs in const: — a caller cannot move it out from under the permit. vars:, env: and config: are dead envelope fields (NIKA-VALUES-001 / NIKA-VALUES-002 / NIKA-PARSE-005), and so are the ${{ vars.X }} / ${{ env.X }} / ${{ config.X }} reads. There is no alias: each old use classifies into the authority its role commands — a typed parameter is an inputs: declaration, a fixed value a const: entry, a deployment-supplied value an inputs: entry with required: false and a default:, a governed store reference a secrets: entry. nika check --fix migrates the provable cases. (The env: inside an exec: block is a different field and is alive: it is the child process’s environment map.)

`permits:` — the key is optional, the authority is not

An absent permits: block declares zero authority. Every effect the body requires is refused at check with NIKA-AUTH-006 — before a single token — and any effect attempted at run time fails the task with NIKA-SEC-004. A pure-compute workflow passes with an informational hint; permits: {} is the authored spelling of “I touch nothing”.

nika check flow.nika --infer-permits   # prints the tightest block, ready to paste

Once the block is present every category is default-deny unless listed — including tools:, which must name every builtin the file invokes, even the pure-compute ones.

The run declaration

run:
  entropy: ambient           # none | ambient | { seeded: <u64> }
  clock: system              # system | virtual

Every source of randomness and time is declared, never ambient. Absent, the run behaves as entropy: ambient + clock: system. The two dimensions couple: only ambient × system and none | seeded × virtual are legal — byte-identical journals need deterministic time as much as deterministic randomness. A declared contradiction refuses at parse (NIKA-PARSE-026 · NIKA-PARSE-027); entropy: none with a live randomness source consumed refuses at check (NIKA-PARSE-028).

Types · inline, where the shape is used

A shape rides the verb’s own schema: (structured output) or a task’s returns: — inline, as a type expression. There is no named-type block any more (types: left the envelope with the nine-key one · NIKA-TYPE-002 retired with it).

typed-triage.nika

nika: typed-triage

permits:
  tools: ["nika:jq"]

tasks:
  classify:
    invoke:
      tool: "nika:jq"
      args:
        input: { severity: "high", summary: "unbounded retry", line: 42 }
        expression: "."
    returns:
      object:
        severity: { enum: ["low", "medium", "high"] }
        summary: string
        line: { integer: { min: 1 } }

outputs:
  severity: "${{ tasks.classify.output.severity }}"

The type grammar is closed: the ten primitives (null · bool · integer · number · string · bytes · uri · path · duration · timestamp, always lowercase) or a constructor — object: · array: · map: · union: · enum: · plus the refinements integer:/number: (min/max) and string: (pattern/min_len/max_len). An unknown name is NIKA-TYPE-001.

What left the envelope (0.109)

The nine-key envelope retired a family of top-level keys. Each refusal names the key’s role and where it went — nika check says it on the line, this is the same list:

Retired key	Where its role went
`workflow: { id, description }`	the identity is `nika: <id>`; the description is a `#` comment above it
`config:`	an `inputs:` entry with `required: false` + `default:`
`vars:` · `env:`	classified into `inputs:` / `const:` / `secrets:` by role
`types:`	the shape rides `returns:` or the verb’s `schema:`, inline
`policy:`	a vocabulary is not a policy: the effect boundary is `permits:`, a governed value is a `secrets:` entry, the ordering laws are unconditional
`assert:`	a run’s obligations are proven on the trace, not declared in the file — `nika trace verify` reads them from the sealed run

nika check --fix migrates the provable cases (the identity · config: · the renamed task fields below); a structural move stays yours, with the refusal naming it.

A task

<identifier>:                # the map KEY is the identity (snake_case · unique)

  with: { ... }              # optional · the DATA boundary · each tasks.* ref = one typed edge
  group: <name>              # optional · fan-in MEMBERSHIP · this task joins the set ${{ group.<name> }}
  after: { <id>: <pred> }    # optional · the CONTROL boundary · pred ∈ success|failure|skipped|terminal|unwind
  when: <expression>         # optional · LOCAL business condition · evaluated POST-gate
  for_each:                  # optional fan-out · a BLOCK, never a bare expression
    items: <expression>      #   the collection · evaluated ONCE, before the fan-out
    max_parallel: <int>      #   optional · cap concurrent iterations
    fail_fast: <bool>        #   optional · default true · false = finish the batch
  timeout: "<duration>"      # optional · quoted Go-duration · per-iteration on for_each
  retry: { ... }             # optional retry policy (max_attempts · backoff · on_codes)
  on_error: { ... }          # optional recovery · exactly one action · recover: <value> | skip: true
  extract: { <name>: <jq> }  # optional named jq bindings over the raw output
  returns: <type>            # optional · the task's output contract (a type expression, inline)
  lift: [ ... ]              # optional · the ONE door that opens a named law (taint · data-as-code)

  # exactly one verb block:
  infer: { ... }
  exec: { ... }
  invoke: { ... }            # tool: <builtin|mcp> XOR workflow: <path|registry ref>
  agent: { ... }

Those modifiers are the complete task surface. returns: and lift: are the two that carry a contract of their own:

Modifier	What it declares
`returns:`	The task’s output type, as an inline type expression — exclusive with a verb-level `schema:` (`NIKA-TYPE-003`). Under composition it is how the parent states the child’s shape.
`lift:`	The single construct through which an author opens a named law. `law: taint` raises exactly one binding (`from:` a dotted path · a non-empty `because:`) through the permit-parameterization taint — the value is still matched against the declared boundary, so it is never a permit bypass. `law: data-as-code` (no `from:` · a non-empty `because:`) is the door through the data-as-code sink: a `nika:fetch` whose resolved URL names a code-bearing class (`.pkl` · `.py` · `.so` · the closed NEP-0006 list) is refused with `NIKA-SEC-008` unless the entry declares the artifact will never be loaded or run. It lifts that law only — never the `net.http` boundary, never the SSRF floor.

inert-fetch.nika

nika: inert-fetch

permits:
  net: { http: ["example.com"] }
  tools: ["nika:fetch"]

tasks:
  audit_weights:
    lift:
      - law: data-as-code
        because: "checksum audit only · the file is hashed, never deserialized"
    invoke:
      tool: "nika:fetch"
      args: { url: "https://example.com/model.pkl" }

outputs:
  status: "${{ tasks.audit_weights.output.status }}"

Drop the lift: entry and that same file fails the check with NIKA-SEC-008. The door is greppable by design: a reviewer can find every place a law was opened, and each entry carries its written justification into the run receipt. (declassify: and inert: were the two earlier spellings; both merged into lift: — the law is a parameter of one door, not two keywords.) Cleanup is a task, not a task field: write it as its own task joined by after: { <parent>: unwind } — it runs once the parent has settled, whatever happened (graph_format: 3 projects it as a finally node). The old on_finally: list inside a task body is gone; so is on_error: fail_workflow — a failure that is not recovered or skipped already fails the run, there is nothing to declare. tasks.* crosses a task boundary through exactly two doors — with: (data · observations) and after: (control) — and the engine computes the graph FROM those doors. A with: binding that references ${{ tasks.X.* }} both names the data and declares a typed edge; an after: entry ({producer: predicate}) orders on state and carries no data. depends_on is dead (NIKA-PARSE-024 · nika check --fix migrates it), and a tasks.* reference outside the boundary — in a verb body, when:, or for_each: — is NIKA-VAR-021 with a machine-applicable fix (hoist into with:). The after: predicate set is closed: success · failure · skipped · terminal (terminal admits any settled state, cancelled included). Anything else is NIKA-DAG-005; the participial spellings succeeded and failed are dead forms and refuse with their respelling, which nika check --fix applies. The full per-field semantics live in the spec: 03 · The flow.

Timeouts

timeout: is a quoted Go-duration string ("90s", "7m", "1h30m") and bounds the entire task, wall-clock: retries and their backoff sleeps included. Exceeding it fails the task with NIKA-TIMEOUT-001 — catchable by on_error:, never retryable (the timeout already covered the retries by definition). On a for_each task the clock applies per iteration. On an infer: / agent: task the declared timeout: also governs the provider HTTP deadline: timeout: "7m" gives the provider round-trip those seven minutes — no internal HTTP default undercuts the declared budget.

deep_review:
  timeout: "7m"                # the whole task AND the provider deadline
  infer:
    model: ollama/qwen3:8b     # a thinking model legitimately needs minutes
    prompt: "Review this diff…"

When no timeout: is declared, the provider deadline defaults per provider class:

Class	Providers	Default deadline
Local	`ollama` · `lmstudio` · `llamacpp` · `localai` · `vllm`	≥ 300s
Cloud	`openai` · `xai` · `qwen` · `moonshot` · `anthropic` · `openrouter` · `groq` · `deepseek` · `gemini` · `mistral`	30s

A local model routinely needs minutes for one completion on consumer hardware — a 30s-everywhere default would silently kill every serious local-first workflow before the model finishes thinking. The class is keyed on the canonical provider id: a base_url override never flips it. Two honest bounds ride the transport (pinned by the engine’s wire tests):

600s ceiling on a fully-silent connection. A non-streaming completion delivers zero bytes while the model computes, so the transport cannot tell thinking from dead. A longer timeout: still bounds the task, but only a connection that starts delivering can use it.
Streaming rides only an explicit budget. A declared timeout: bounds a streaming request; when none is declared, the idle-read guard reaps a stalled stream instead of capping a healthy one.

Normative home: stdlib · providers §Transport deadline.

Verbs

See individual pages:

infer: LLM call
exec: shell commands
invoke: built-in or MCP tool (HTTP fetch is invoke: nika:fetch)
agent: tool-calling loop

Full schema

The canonical JSON Schema is at https://nika.sh/schema/workflow.json. It’s 100% machine-authoritative. This doc is a readable summary.

Contract version policy

The envelope carries no version marker: nika: <identifier> is the mark and the name, and there is nothing to bump. Minor additions (a new optional field, a new builtin) are additive; a grammar change before 1.0 ships with its migration in nika check --fix and its refusal naming the move (the pre-1.0 stability contract) · after engine 1.0.0 the grammar is additive only. The project file nika.yaml carries no tasks: and names the project (nika: my-project); nika: v1 there is a retired schema tag, not an identity.

YAML

Language fields

CLI & errors

Data catalogs

Workspace

Documentation system

Tool contracts

YAML syntax reference

Top level

The three value authorities

`permits:` — the key is optional, the authority is not

The run declaration

Types · inline, where the shape is used

What left the envelope (0.109)

A task

Timeouts

Verbs

Full schema

Contract version policy

​Top level

​The three value authorities

​permits: — the key is optional, the authority is not

​The run declaration

​Types · inline, where the shape is used

​What left the envelope (0.109)

​A task

​Timeouts

​Verbs

​Full schema

​Contract version policy

Top level

The three value authorities

`permits:` — the key is optional, the authority is not

The run declaration

Types · inline, where the shape is used

What left the envelope (0.109)

A task

Timeouts

Verbs

Full schema

Contract version policy