Template Types Reference — DAG, Task, and Loop

Every entry in spec.templates is a Template union: exactly one of dag, task, or loop must be set. The engine uses the active sub-type to determine how to schedule and execute the template. DAG templates orchestrate directed graphs of tasks; Task templates invoke a single executor plugin; Loop templates iterate over a list of items or repeat until a condition is false. Templates are composable — a DAG task can reference a Loop template, which in turn iterates over a DAG template, up to the configured maxNestedDepth.

All template names, task names within DAGs, and parameter names must match the DNS-1123 label rule: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$, maximum 63 characters. Dots are reserved as system namespace separators and are not allowed in user-defined names.

DAG template (`template.dag`)

A DAG template defines a directed acyclic graph of task invocations. Each task in the graph may declare dependencies on other tasks by name; the engine uses these edges to determine execution order and dispatch all dependency-free tasks in parallel.

dag.name

string

required

Unique template name within the workflow. Referenced by spec.entrypoint, dag.tasks[].template, and loop.body.

dag.inputs

object

Input parameter and artifact declarations for this template. When the DAG is invoked from a parent scope, the caller passes values via arguments.

Show inputs fields

dag.inputs.parameters

Parameter[]

Array of input parameter declarations. Each parameter has name, optional type, optional default, and optional description. Parameter values are available inside DAG task arguments via inputs.parameters.<name>.

dag.inputs.artifacts

Artifact[]

Array of input artifact declarations. (Artifact execution is reserved for a future release.)

dag.outputs

object

Output declarations for this DAG template. Each output parameter typically uses valueFrom.parameter to pull a value from a completed child task.

Show outputs fields

dag.outputs.parameters

Parameter[]

Array of output parameter declarations. Use valueFrom.parameter with paths like tasks.<task-name>.outputs.parameters.<param> to forward a child task’s output.

dag.outputs.artifacts

Artifact[]

Array of output artifact declarations.

dag.entrypoints

string | string[]

Optional subset of task names to treat as the starting nodes. When omitted, all tasks with no dependencies are treated as entrypoints and dispatched immediately. When set, only the named tasks (and their transitive dependents) are run — useful for running a sub-graph of a larger DAG.

dag.tasks

Task[]

required

Array of task call-site definitions. Each element describes one node in the graph, not a template definition. Must contain at least one entry.

Show dag.tasks[] fields

name

string

required

Node name within this DAG scope. Must be unique among siblings. Used to reference outputs via tasks.<name>.outputs.parameters.<param>.

template

string

Name of a template in spec.templates to execute at this node. Either template or executor must be set, but not both.

executor

object

Inline executor definition. Use when there is no reusable template to reference — a common pattern for small, single-use tasks.

Show executor fields

executor.type

string

required

Executor type identifier (e.g. "echo", "http", "shell"). Must match a registered executor.Plugin.

dependencies

string[]

Names of sibling tasks that must reach a terminal phase before this task is dispatched. An empty or absent list means the task starts immediately (it is a DAG root).

arguments

object

Parameter and artifact values passed to the referenced template’s inputs. Use valueFrom.parameter with paths like tasks.<dep>.outputs.parameters.<param> to wire dependency outputs.

when

string

Boolean expression evaluated before dispatching this task. When the expression evaluates to false the task is skipped (PhaseSkipped) and its dependents remain unblocked. Requires a configured expr.Evaluator.Example: "tasks.validate.outputs.parameters.ok == 'true'"

timeout

string

Task-level deadline as a Go duration string (e.g. "10m"). Overrides any template-level timeout. The watchdog calls OnTaskTimeout when exceeded.

retry

object

Retry policy for this task call site. Only applies to leaf task templates (not DAG or Loop containers).

Show retry fields

retry.limit

integer

required

Maximum number of retry attempts. 0 disables retries.

retry.expression

string

Optional boolean expression controlling whether a retry is attempted. When omitted, only Error and Timeout phases trigger a retry. The expression can reference:

tasks.<name>.phase — e.g. "Failed", "Error", "Timeout"
tasks.<name>.code — integer exit code
tasks.<name>.msg — error message string
tasks.<name>.outputs.parameters.<param> — output value

continueOn

object

Controls whether the DAG continues scheduling dependents even when this task reaches a non-Succeeded terminal phase.

Show continueOn fields

continueOn.failed

boolean

default:"false"

Continue scheduling dependents when this task reaches Failed.

continueOn.error

boolean

default:"false"

Continue scheduling dependents when this task reaches Error.

continueOn.timeout

boolean

default:"false"

Continue scheduling dependents when this task reaches Timeout.

resources

object

Compute resource requirements forwarded to the broker via TaskAssignment.Resources. Interpretation is broker-specific.

Show resources fields

resources.cpu

string | number

CPU request, e.g. "500m" or 0.5.

resources.memory

string

Memory request, e.g. "512Mi".

resources.gpu

string

GPU request, e.g. "1".

phaseConditions

object

Custom expressions that override the engine’s default phase derivation from ExecCode. Useful when the executor uses a non-standard exit code convention.

Show phaseConditions fields

phaseConditions.succeeded

string

When this expression evaluates to true, the task phase is set to Succeeded regardless of ExecCode.

phaseConditions.failed

string

When this expression evaluates to true, the task phase is set to Failed.

phaseConditions.error

string

When this expression evaluates to true, the task phase is set to Error.

hooks

object

Task-level lifecycle hooks. Fired when this specific task node enters the corresponding phase. Supports the same fields as workflow-level hooks plus onSuspend and onResume.

Show hooks fields

hooks.onStart

Hook

Fires on Running.

hooks.onSuccess

Hook

Fires on Succeeded.

hooks.onFailure

Hook

Fires on Failed.

hooks.onError

Hook

Fires on Error.

hooks.onSuspend

Hook

Fires on Suspended.

hooks.onResume

Hook

Fires when Resume() re-dispatches the task.

hooks.onCancel

Hook

Fires on Cancelled.

hooks.onExit

Hook

Fires on any terminal phase.

outputs

object

Output declarations for the task node. When present, template-declared value fields are merged as defaults if the executor does not produce the corresponding output (executor result takes precedence).

dag.continueOn

object

DAG-level continueOn. When set, controls default continue-on behaviour for all tasks in the DAG that do not override it at the task level.

dag.phaseConditions

object

Custom phase-derivation expressions for the DAG container itself (not its child tasks). Rarely needed.

dag.timeout

string

DAG-level deadline. The whole DAG (and all its child tasks) must complete within this duration, independent of individual task timeouts.

DAG example

{
  "dag": {
    "name": "main",
    "outputs": {
      "parameters": [
        {
          "name": "summary",
          "type": "string",
          "valueFrom": { "parameter": "tasks.transform.outputs.parameters.summary" }
        }
      ]
    },
    "tasks": [
      {
        "name": "fetch",
        "template": "fetch-data"
      },
      {
        "name": "transform",
        "template": "transform-data",
        "dependencies": ["fetch"],
        "arguments": {
          "parameters": [
            {
              "name": "raw",
              "valueFrom": { "parameter": "tasks.fetch.outputs.parameters.body" }
            }
          ]
        },
        "retry": { "limit": 3 },
        "timeout": "10m",
        "hooks": {
          "onFailure": { "template": "notify-failure" }
        }
      }
    ]
  }
}

Task template (`template.task`)

A Task template represents a single executor invocation — the leaf node of the execution graph. It carries its own inputs, outputs, and executor declaration, making it a reusable, named unit that DAG tasks can reference by name.

task.name

string

required

Unique template name within the workflow.

task.inputs

object

Input parameter and artifact declarations. Values are resolved from the caller’s arguments or from valueFrom references at dispatch time.

task.outputs

object

Output parameter and artifact declarations. Parameters listed here without a value are filled from the executor’s ExecOutputs.Parameters at completion time. Parameters with a value field act as static defaults used when the executor does not produce that key.

task.executor

object

The executor plugin to invoke for this task.

Show executor fields

task.executor.type

string

required

Executor type identifier. Must match a registered executor.Plugin.Type().

task.timeout

string

Task deadline as a Go duration string. Requires WithTimeoutWatcher.

task.retry

object

Retry policy. See the retry fields under DAG task fields.

task.phaseConditions

object

Custom phase expressions. See phaseConditions under DAG task fields.

task.hooks

object

Task-level lifecycle hooks. See hooks under DAG task fields. Both task templates and DAG task call-sites support onSuspend and onResume.

task.resources

object

Compute resource requirements forwarded via TaskAssignment.Resources.

Task template example

{
  "task": {
    "name": "greet",
    "inputs": {
      "parameters": [
        { "name": "username", "type": "string",
          "valueFrom": { "parameter": "workflow.arguments.parameters.username" } },
        {
          "name": "outputs",
          "value": [
            { "name": "message", "type": "string", "value": "Hello, Alice!" },
            { "name": "code",    "type": "int",    "value": 200 }
          ]
        }
      ]
    },
    "executor": { "type": "echo" },
    "outputs": {
      "parameters": [
        { "name": "message", "type": "string" },
        { "name": "code",    "type": "int" }
      ]
    }
  }
}

Loop template (`template.loop`)

A Loop template repeats a body template for each element in a list or until a condition becomes false. It supports static item lists, dynamic item lists sourced from a parameter, and condition-controlled repetition. All three modes run the same body template, which can itself be a DAG, Task, or another Loop.

Exactly one of repeatCondition, items, or itemsFrom must be set. Setting more than one, or none, causes validation to fail.

loop.name

string

required

Unique template name within the workflow.

loop.inputs

object

Input parameter declarations for the loop template.

loop.outputs

object

Output declarations for the loop as a whole. Typically used with aggregate to expose collected results from all iterations.

loop.repeatCondition

string

Boolean expression evaluated before each iteration. The loop continues as long as the expression evaluates to true. Requires maxIterations to be set as a safety bound. Cannot be combined with items or itemsFrom. Cannot be combined with concurrency (repeat-until loops are serial by definition).

loop.items

any[]

Static list of items. Each element is passed to the body template as iterator.item for the current iteration. Cannot be combined with repeatCondition or itemsFrom.

loop.itemsFrom

string

Expression or parameter reference that resolves to a list at runtime. The resolved list is treated identically to items. Cannot be combined with repeatCondition or items.

loop.concurrency

integer

Maximum number of iterations to dispatch in parallel. 0 or omitted means unlimited parallelism for items/itemsFrom mode. Not allowed with repeatCondition (repeat-until loops are always serial).

loop.maxIterations

integer

Maximum number of iterations before the loop is forcibly terminated. Required when repeatCondition is set. Optional for items/itemsFrom where the list length already bounds iteration count.

loop.body

string

required

Name of the template to execute for each iteration. Must reference an existing template in spec.templates.

loop.arguments

object

Arguments forwarded to the body template on each iteration. Use "{{iterator.item}}" and "{{iterator.index}}" interpolation to inject per-iteration values.Special interpolation tokens:

{{iterator.item}} — the current item from items or itemsFrom
{{iterator.index}} — zero-based iteration index

loop.aggregate

object

Defines how iteration results are combined into the loop’s output parameters. When omitted the last iteration’s outputs are used.

Show aggregate fields

aggregate.strategy

string

default:"last"

Aggregation mode. One of:

Strategy	Behaviour
`"last"`	Use the last completed iteration’s output values (default).
`"first"`	Use the first completed iteration’s output values.
`"list"`	Collect each named parameter from all iterations into a JSON array, sorted by iteration index.

aggregate.parameters

string[]

List of output parameter names to aggregate. When omitted all output parameters are included. Only meaningful with the "list" strategy.

loop.phaseConditions

object

Custom phase-derivation expressions for the loop container itself.

loop.timeout

string

Loop-level deadline. The entire loop (all iterations) must complete within this duration.

Loop example

{
  "loop": {
    "name": "run-loop",
    "items": ["jan.csv", "feb.csv", "mar.csv"],
    "concurrency": 2,
    "body": "process-file",
    "arguments": {
      "parameters": [
        { "name": "filename", "value": "{{iterator.item}}" },
        { "name": "index",    "value": "{{iterator.index}}" }
      ]
    },
    "aggregate": {
      "strategy": "list",
      "parameters": ["status", "rows"]
    },
    "outputs": {
      "parameters": [
        { "name": "status", "type": "array" },
        { "name": "rows",   "type": "array" }
      ]
    }
  }
}

Shared sub-types

Retry

type Retry struct {
    Limit      int    `json:"limit,omitempty"`
    Expression string `json:"expression,omitempty"`
}

Only leaf tasks (executor invocations) support retry. DAG and Loop containers are not retried directly. The engine resets the task to Created and re-dispatches it without writing a terminal phase, keeping RetryCount as the authoritative retry counter.

ContinueOn

type ContinueOn struct {
    Failed  bool `json:"failed,omitempty"`
    Error   bool `json:"error,omitempty"`
    Timeout bool `json:"timeout,omitempty"`
}

When continueOn.failed is true and a task reaches Failed, dependents are still dispatched. This enables best-effort pipelines that must always notify even when upstream steps fail.

PhaseConditions

type PhaseConditions struct {
    Succeeded string `json:"succeeded,omitempty"`
    Failed    string `json:"failed,omitempty"`
    Error     string `json:"error,omitempty"`
}

User-defined expressions that override the engine’s ExecCode → Phase mapping. The engine evaluates them in order (succeeded first) and uses the first one that evaluates to true. If none match, the default mapping applies.

Executor

type Executor struct {
    Type string `json:"type"`
}

The type field is the only field of the Executor struct. All configuration needed by the executor is passed via the task’s inputs.parameters.

Protocol

Go API

Template Types Reference — DAG, Task, and Loop

DAG template (`template.dag`)

DAG example

Task template (`template.task`)

Task template example

Loop template (`template.loop`)

Loop example

Shared sub-types

Retry

ContinueOn

PhaseConditions

Executor

Build docs developers (and LLMs) love

Protocol

Go API

Documentation Index

​DAG template (template.dag)

​DAG example

​Task template (template.task)

​Task template example

​Loop template (template.loop)

​Loop example

​Shared sub-types

​Retry

​ContinueOn

​PhaseConditions

​Executor

Build docs developers (and LLMs) love

DAG template (`template.dag`)

DAG example

Task template (`template.task`)

Task template example

Loop template (`template.loop`)

Loop example

Shared sub-types

Retry

ContinueOn

PhaseConditions

Executor