Workflow resource schema reference — aether/v1

The Workflow resource is the primary declarative unit in the Graph Workflow Protocol (apiVersion: aether/v1). It describes a directed execution graph — which templates to run, how they are connected, what arguments they accept, and what lifecycle hooks fire at key points. The engine validates and persists a full JSON snapshot of the document at submit time, so the definition that runs is always exactly what you submitted.

Top-level fields

apiVersion

string

required

Protocol version. Must be the string "aether/v1". Any other value causes validation to fail with ErrValidation.

kind

string

required

Resource discriminator. Must be "Workflow" for a standalone workflow. ("CronWorkflow" is used by the CronWorkflow resource.)

metadata

object

required

Standard resource metadata.

Show metadata fields

metadata.name

string

required

Unique name for this workflow definition. Must conform to DNS-1123 label rules: lowercase alphanumeric characters or hyphens (-), must start and end with an alphanumeric character, maximum 63 characters.Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$Examples: "data-pipeline", "nightly-report", "user-onboarding-v2"

metadata.namespace

string

Optional logical namespace for multi-tenant deployments. Not enforced by the engine itself; available for store implementations to use as a partition key.

metadata.version

string

Optional user-defined version string for the workflow definition (e.g. "1.3.0"). Not interpreted by the engine.

metadata.labels

map[string]string

Arbitrary key/value labels for querying and grouping. Not interpreted by the engine.

metadata.annotations

map[string]string

Arbitrary key/value annotations. Commonly used for description text, test expectations, or operational metadata. Not interpreted by the engine.

spec

object

required

The workflow specification. Contains the entrypoint, templates, arguments, timeout, and hooks.

Show spec fields

spec.entrypoint

string

required

Name of the template to execute first. Must match exactly one template name in spec.templates. The engine will reject the workflow at submit time if the entrypoint template is not found.

spec.arguments

object

Workflow-level parameter declarations. Values provided here are available to templates via workflow.arguments.parameters.<name>.

Show arguments fields

spec.arguments.parameters

Parameter[]

Array of parameter declarations. Each parameter can carry a static value (value) or a reference to an external source (valueFrom).

Show Parameter fields

name

string

required

Parameter name. Must follow DNS-1123 rules (same as metadata.name).

type

string

Type hint for validation and display. One of: "string", "int", "float", "bool", "json", "list".

value

any

Static value encoded as JSON. Takes precedence over valueFrom when both are set.

default

any

Default value used when value and valueFrom are both absent at runtime.

description

string

Human-readable description of the parameter’s purpose.

enum

any[]

Allowed values. When set, the engine validates that the resolved value is a member of this list.

valueFrom

object

Dynamic value source. Exactly one sub-field should be set.

Show valueFrom fields

valueFrom.path

string

JSON path expression evaluated against the current execution context.

valueFrom.parameter

string

Reference to another parameter in the form tasks.<name>.outputs.parameters.<param> or workflow.arguments.parameters.<param>.

valueFrom.expression

string

Arbitrary expression evaluated by the configured expr.Evaluator.

valueFrom.secretKeyRef

object

Reference to a secret managed by the configured secret.Provider.

Show secretKeyRef fields

name

string

required

Secret name in the secret store.

key

string

required

Key within the secret.

spec.arguments.artifacts

Artifact[]

Array of artifact declarations for workflow-level input artifacts. (Artifact upload/download is reserved for a future release; the field is parsed but not yet wired into execution.)

spec.timeout

string

Workflow-level deadline as a Go duration string (e.g. "30m", "2h", "1h30m"). When the workflow has been running longer than this duration the watchdog calls OnWorkflowTimeout, which cancels all non-terminal tasks and marks the workflow Timeout. Requires a timeout.Watcher to be configured via WithTimeoutWatcher.

spec.priority

integer

Scheduling priority hint forwarded to the broker via TaskAssignment.Priority. Higher values indicate higher priority. Interpretation is broker-specific; the engine does not enforce ordering.

spec.maxNestedDepth

integer

default:"3"

Maximum static template nesting depth enforced at validation time. The absolute ceiling is 10 regardless of this value; configuring a higher number silently caps at 10. Set a lower value to prevent accidental deep nesting in large template libraries.

spec.templates

Template[]

required

Array of named template definitions. Must contain at least one entry. Each element is a union: exactly one of dag, task, or loop must be set. See the Template Types reference for complete field documentation.

spec.hooks

object

Workflow-level lifecycle hooks. Each hook names a task template to execute when the workflow enters the corresponding phase. Hook templates must be task templates (DAG and Loop templates are not allowed as hooks).

Show hooks fields

hooks.onStart

Hook

Fires when the workflow transitions from Ready to Running.

hooks.onSuccess

Hook

Fires when the workflow reaches Succeeded.

hooks.onFailure

Hook

Fires when the workflow reaches Failed.

hooks.onError

Hook

Fires when the workflow reaches Error.

hooks.onCancel

Hook

Fires when the workflow is cancelled via Engine.Cancel.

hooks.onExit

Hook

Fires on any terminal phase (success, failure, error, timeout, or cancel). Useful for cleanup logic.

hooks.*.template

string

required

Name of the task template to execute for this hook event.

Complete example

The following example demonstrates all top-level fields in a workflow that fetches data, transforms it, and sends a notification — with a timeout, priority, workflow-level arguments, and lifecycle hooks.

{
  "apiVersion": "aether/v1",
  "kind": "Workflow",
  "metadata": {
    "name": "data-pipeline",
    "namespace": "analytics",
    "version": "2.1.0",
    "labels": {
      "team": "data-eng",
      "env": "production"
    },
    "annotations": {
      "description": "Fetch → Transform → Notify pipeline with retry and hooks"
    }
  },
  "spec": {
    "entrypoint": "main",
    "arguments": {
      "parameters": [
        { "name": "source-url",  "type": "string", "value": "https://api.example.com/data" },
        { "name": "batch-size",  "type": "int",    "value": 500 },
        { "name": "notify-email","type": "string",
          "valueFrom": { "secretKeyRef": { "name": "smtp-config", "key": "recipient" } }
        }
      ]
    },
    "timeout": "2h",
    "priority": 10,
    "maxNestedDepth": 5,
    "templates": [
      {
        "dag": {
          "name": "main",
          "tasks": [
            {
              "name": "fetch",
              "template": "fetch-data",
              "arguments": {
                "parameters": [
                  { "name": "url",
                    "valueFrom": { "parameter": "workflow.arguments.parameters.source-url" } },
                  { "name": "batch-size",
                    "valueFrom": { "parameter": "workflow.arguments.parameters.batch-size" } }
                ]
              }
            },
            {
              "name": "transform",
              "template": "transform-data",
              "dependencies": ["fetch"],
              "arguments": {
                "parameters": [
                  { "name": "raw",
                    "valueFrom": { "parameter": "tasks.fetch.outputs.parameters.body" } }
                ]
              },
              "retry": { "limit": 3, "expression": "tasks.transform.phase == 'Error'" },
              "timeout": "30m"
            },
            {
              "name": "notify",
              "template": "send-notification",
              "dependencies": ["transform"],
              "arguments": {
                "parameters": [
                  { "name": "summary",
                    "valueFrom": { "parameter": "tasks.transform.outputs.parameters.summary" } },
                  { "name": "recipient",
                    "valueFrom": { "parameter": "workflow.arguments.parameters.notify-email" } }
                ]
              }
            }
          ]
        }
      },
      {
        "task": {
          "name": "fetch-data",
          "inputs": {
            "parameters": [
              { "name": "url",        "type": "string" },
              { "name": "batch-size", "type": "int" }
            ]
          },
          "executor": { "type": "http" },
          "outputs": {
            "parameters": [
              { "name": "body",  "type": "json" },
              { "name": "count", "type": "int" }
            ]
          }
        }
      },
      {
        "task": {
          "name": "transform-data",
          "inputs": {
            "parameters": [
              { "name": "raw", "type": "json" }
            ]
          },
          "executor": { "type": "shell" },
          "outputs": {
            "parameters": [
              { "name": "summary", "type": "string" }
            ]
          }
        }
      },
      {
        "task": {
          "name": "send-notification",
          "inputs": {
            "parameters": [
              { "name": "summary",   "type": "string" },
              { "name": "recipient", "type": "string" }
            ]
          },
          "executor": { "type": "email" }
        }
      },
      {
        "task": {
          "name": "on-pipeline-exit",
          "executor": { "type": "echo" }
        }
      }
    ],
    "hooks": {
      "onSuccess": { "template": "on-pipeline-exit" },
      "onFailure": { "template": "on-pipeline-exit" },
      "onExit":    { "template": "on-pipeline-exit" }
    }
  }
}

Validation rules

All names (metadata, template names, task names, parameter names) must match ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ with a maximum of 63 characters. Dots are reserved as the system namespace separator and are not allowed in user-defined names.

spec.entrypoint must match the name of an existing template in spec.templates. An unresolved entrypoint is a hard validation error; the workflow will not be submitted.

Hook templates must be task templates. Referencing a dag or loop template from a hook causes validation to fail. Hooks are fire-and-forget notifications, not recursive scheduling units.

Protocol

Go API

Workflow resource schema reference — aether/v1

Top-level fields

Complete example

Validation rules

Build docs developers (and LLMs) love

Protocol

Go API

Documentation Index

​Top-level fields

​Complete example

​Validation rules

Build docs developers (and LLMs) love

Top-level fields

Complete example

Validation rules