Serverless Workflow Specification mapping and concepts

This page is a fast orientation to the CNCF Serverless Workflow Specification 1.0.0 that Quarkus Flow aligns with. It highlights the core ideas and gives you a compact cheatsheet of the most used components—each linking back to the spec for deeper reading.

If you understand these concepts, you can read any Quarkus Flow example and know exactly what it’s doing.

What the spec gives you (in 30 seconds)

  • Task-based workflow model — compose sequences that set data, call services or functions, emit or listen to events, and control the flow via switch, for, or try tasks.

  • Event-native — first-class support for CloudEvents for choreography, correlation, and waking up paused instances.

  • Service-oriented — call HTTP/GRPC/OpenAPI/AsyncAPI services with inputs and outputs strictly mapped to the workflow data context.

  • Deterministic execution & fault tolerance — explicit error handling (try/catch), retries with backoff, and timeouts.

  • Portable definitions — a vendor-neutral, declarative DSL (JSON/YAML) with a versioned schema (1.0.0).

Quick links:

Core components (cheatsheet)

The CNCF 1.0.0 Specification organizes workflows around the document (metadata) and a sequence of tasks (the do block).

Component What it is Typical use Spec link

Document Metadata

Top-level definition: dsl (version 1.0.0), namespace, name, version, optional description.

Identify the workflow, its domain, and which schema version you’re using.

DSL

Data model

The global workflow data context (JSON). Tasks extract from, transform, and export back to this context.

Keep transient state, map call inputs/outputs, and drive branching conditions.

DSL Data Flow

Tasks (do)

The ordered list of steps to execute.

Define your core process: set → call → emit/listen → switch → loop, etc.

DSL Task

Task: set

Evaluates an expression and updates the workflow data context.

Initialize fields, compute constants, or shape intermediate values.

Reference

Task: call

Invokes external endpoints or internal functions.

HTTP/OpenAPI calls, communicating with other microservices, or triggering LangChain4j AI agents.

Reference

Task: emit

Publishes a CloudEvent to an external broker.

Notify other services, fan-out architectural patterns, or broadcast integration events.

Reference

Task: listen

Pauses execution and waits for one or more CloudEvents matching specific correlation rules.

Human-in-the-loop approvals, asynchronous callbacks, or waiting for external system signals.

Reference

Task: switch (Branching)

Evaluates conditions (when) and routes execution to specific paths (then).

Feature flags, guardrails, compliance checks, or routing "happy vs. error" paths.

Reference

Task: for (Loops)

Iterates over a collection in the data context, executing a block of tasks for each item.

Batch processing, agentic revise-loops, or polling.

Reference

Task: try (Errors)

Executes a block of tasks and catches specific errors to trigger compensations or retries.

Wrap unreliable network calls, steer to fallback paths, and surface clear failures without crashing the instance.

Reference

Timeouts

Declarative time limits applied to individual tasks or the overarching workflow execution.

Prevent stalled processes, bound external waits, and enforce business SLAs.

DSL Timeouts

Expressions & Data Filters

The runtime evaluation of input, output, and export fields within a task using jq.

Extracting payloads from events, filtering API responses, or computing booleans for switch blocks. (See Data flow).

DSL Expressions

Auth & Secrets

References to credentials or API keys used during call tasks.

Securely communicate with external services without hardcoding tokens in the definition.

DSL Auth
This is a quick reference. For the authoritative wording and full property sets, always read the linked spec sections.

Where Quarkus Flow fits

Quarkus Flow provides a Java fluent API that maps 1:1 to the tasks defined above (e.g., set, call, emit, listen, switchWhenOrElse, forEach, tasks).

Crucially, Quarkus Flow leans into the Quarkus "Ahead-of-Time" philosophy by discovering your Flow classes at build time, and integrates deeply with CDI, HTTP/OpenAPI, SmallRye Messaging, and LangChain4j for building standard-compliant agentic AI orchestrations.

See also

Now that you understand the underlying specification, here is where you can see these concepts applied in Quarkus Flow: