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
string
required
Protocol version. Must be the string
"aether/v1". Any other value causes
validation to fail with ErrValidation.string
required
Resource discriminator. Must be
"Workflow" for a standalone workflow.
("CronWorkflow" is used by the CronWorkflow resource.)object
required
Standard resource metadata.
Show metadata fields
Show metadata fields
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"string
Optional logical namespace for multi-tenant deployments. Not enforced by
the engine itself; available for store implementations to use as a
partition key.
string
Optional user-defined version string for the workflow definition (e.g.
"1.3.0"). Not interpreted by the engine.map[string]string
Arbitrary key/value labels for querying and grouping. Not interpreted by
the engine.
map[string]string
Arbitrary key/value annotations. Commonly used for description text,
test expectations, or operational metadata. Not interpreted by the engine.
object
required
The workflow specification. Contains the entrypoint, templates, arguments,
timeout, and hooks.
Show spec fields
Show spec fields
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.object
Workflow-level parameter declarations. Values provided here are available
to templates via
workflow.arguments.parameters.<name>.Show arguments fields
Show arguments fields
Parameter[]
Array of parameter declarations. Each parameter can carry a static
value (
value) or a reference to an external source (valueFrom).Show Parameter fields
Show Parameter fields
string
required
Parameter name. Must follow DNS-1123 rules (same as
metadata.name).string
Type hint for validation and display. One of:
"string", "int",
"float", "bool", "json", "list".any
Static value encoded as JSON. Takes precedence over
valueFrom
when both are set.any
Default value used when
value and valueFrom are both absent at
runtime.string
Human-readable description of the parameter’s purpose.
any[]
Allowed values. When set, the engine validates that the resolved
value is a member of this list.
object
Dynamic value source. Exactly one sub-field should be set.
Show valueFrom fields
Show valueFrom fields
string
JSON path expression evaluated against the current execution
context.
string
Reference to another parameter in the form
tasks.<name>.outputs.parameters.<param> or
workflow.arguments.parameters.<param>.string
Arbitrary expression evaluated by the configured
expr.Evaluator.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.)
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.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.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.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.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
Show hooks fields
Hook
Fires when the workflow transitions from
Ready to Running.Hook
Fires when the workflow reaches
Succeeded.Hook
Fires when the workflow reaches
Failed.Hook
Fires when the workflow reaches
Error.Hook
Fires when the workflow is cancelled via
Engine.Cancel.Hook
Fires on any terminal phase (success, failure, error, timeout, or
cancel). Useful for cleanup logic.
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.