Distributed Workflow Orchestration Platform  ·  View 08 of 31  ·  Structure

Workflow Definition — Validation, Versioning and Binding

How a DAG becomes an immutable published version, and what a running execution is protected from.

Editable source SVG draw.io All views
Author
Author
Workflow DSL
JSON or YAML DAG
Workflow DSL...
Authoring CLI
lint · dry-run
Authoring CLI...
Submit
Submit
Workflow API
POST /workflows/{n}/versions
Workflow API...
Validate
Validate
Schema valid?
Schema valid?
Acyclic?
Kahn topological sort
Acyclic?...
Task types registered?
Task types registered?
Tenant policy met?
size · handlers · quota
Tenant policy met?...
Rejected before deploy
422 · violation list
Rejected before deploy...
Publish
Publish
Immutable version
content hash · never edited
Immutable version...
Version index
latest · pinned aliases
Version index...
Bind
Bind
Execution binds version
resolved once at submit
Execution binds version...
In-flight executions
keep their own version
In-flight executions...
Retire
Retire
Deprecate version
no new executions
Deprecate version...
Delete blocked
while executions reference it
Delete blocked...
422 + violations
422 + violations
cycle path
cycle path
unknown type
unknown type
quota exceeded
quota exceeded
Workflow Definition — Validation, Versioning and Binding
Workflow Definition — Validation, Versioning and Binding
Application we own
Application we own
Decision point
Decision point
Risk / gap
Risk / gap
Data store
Data store
failure / alternate
failure / alternate
Published versions are immutable and content-addressed. Schema evolution is additive: a new optional field publishes as a new version, and nothing already running observes the change.
Published versions are immutable and content-addressed. Schema evolution is additive: a new optional field publishes as a new version, and nothing already running observes the change.
v 1.0 · owner Data & AI Global Practice · date 2026-08
v 1.0 · owner Data & AI Global Practice · date 2026-08
Text is not SVG - cannot display

Decisions

  • Published versions are immutable and content-addressed. Editing a workflow produces a new version; nothing already running observes the change. This is what makes an execution that started three days ago still explainable.
  • Validation happens before publication, not at execution time. Cycle detection by topological sort, dependency resolution, task-type registration and tenant policy are all deploy-time gates, so a broken DAG cannot reach a queue.
  • An execution binds its version once, at submission. Late binding to 'latest' was rejected: a long-running execution would otherwise change behaviour mid-flight and become impossible to reason about.

Schema evolution rules

  • Additive only within a major version: new optional fields and new task types are a minor version bump. Removing a field or changing a task's semantics requires a new major version.
  • Deprecation blocks new executions but never deletes. A version cannot be deleted while any execution references it, which is enforced in the store rather than by convention.
  • The DSL is validated against a published JSON Schema that ships with the CLI, so the same errors appear locally as in CI as at the API.

Assumptions

  • Workflow size is capped at 500 tasks, and the cap is enforced at validation. View 31 explains why: a wider DAG concentrates RU and storage on one logical partition.
  • Task-type registration is a platform-team operation. Self-service handler registration is deferred to V2 because it is a supply-chain question, not a workflow question.
  • Definitions are assumed to be non-sensitive. Payloads may contain personal data; the DAG structure is not treated as confidential.