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.

string

required

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

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

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>.

Artifact[]

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

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

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.

Artifact[]

Array of output artifact declarations.

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.

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

string

required

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

string

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

object

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

Show executor fields

string

required

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

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).

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.

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'"

string

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

object

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

Show retry fields

integer

required

Maximum number of retry attempts. 0 disables retries.

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

object

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

Show continueOn fields

boolean

default:"false"

Continue scheduling dependents when this task reaches Failed.

boolean

default:"false"

Continue scheduling dependents when this task reaches Error.

boolean

default:"false"

Continue scheduling dependents when this task reaches Timeout.

object

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

Show resources fields

string | number

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

string

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

string

GPU request, e.g. "1".

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

string

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

string

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

string

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

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

Hook

Fires on Running.

Hook

Fires on Succeeded.

Hook

Fires on Failed.

Hook

Fires on Error.

Hook

Fires on Suspended.

Hook

Fires when Resume() re-dispatches the task.

Hook

Fires on Cancelled.

Hook

Fires on any terminal phase.

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).

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.

object

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

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.

string

required

Unique template name within the workflow.

object

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

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.

object

The executor plugin to invoke for this task.

Show executor fields

string

required

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

string

Task deadline as a Go duration string. Requires WithTimeoutWatcher.

object

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

object

Custom phase expressions. See phaseConditions under DAG task fields.

object

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

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.

string

required

Unique template name within the workflow.

object

Input parameter declarations for the loop template.

object

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

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).

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.

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.

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).

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.

string

required

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

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

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

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.

string[]

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

object

Custom phase-derivation expressions for the loop container itself.

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

​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

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