Specification (quick reference)

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)

Tasks-based workflow model — compose steps that set data, call services/functions/agents, emit or listen to events, and branch/loop based on conditions.
Event-native — first-class events (e.g., CloudEvents) for choreography, correlation, and wake-ups.
Service-oriented — call HTTP/GRPC/OpenAPI/AsyncAPI services with inputs/outputs mapped to workflow data.
Deterministic execution & error handling — timeouts, retries, and explicit failure paths.
Portable definitions — JSON/YAML DSL with a versioned schema (1.0.0) and SDKs across languages.

Quick links:

DSL overview (concepts): DSL
DSL reference (definitions): DSL Reference

Core components (cheatsheet)

Component What it is Typical use Spec link

Component	What it is	Typical use	Spec link
Document	Top-level metadata: `dsl` (version), `namespace`, `name`, `version`, optional `description`.	Identify the workflow and which schema version you’re using (e.g., `1.0.0`).	DSL · Reference
Data model	Workflow data context (JSON). Tasks read/write slices of this context.	Keep transient state, map call inputs/outputs, and drive conditions.	DSL · Reference
Tasks (`do`)	Ordered list of steps to execute. Each item is a task (see next rows).	Define your flow: set → call → emit/listen → branch → loop, etc.	DSL · Reference
Task: `set`	Writes/merges values into workflow data.	Initialize fields, compute constants, stash intermediate values.	DSL · Reference
Task: `call`	Invokes a service/function/agent and maps input/output.	HTTP/GRPC/OpenAPI calls, LangChain4j agents, internal functions.	DSL · Reference
Task: `emit`	Emits an event (e.g., CloudEvent) with payload from workflow data.	Notify other services, fan-out, integration events.	DSL · Reference
Task: `listen`	Waits for one or more events and resumes with received data.	Human-in-the-loop approvals, external signals, callbacks.	DSL · Reference
Conditions / branching	Execute tasks only when an expression is true; branch/choose paths.	Feature flags, guardrails, compliance checks, “happy/error” paths.	DSL · Reference
Loops / repetition	Repeat a task block until a condition is met; bounded by timeouts/retries.	Agentic revise-loops, polling, chunked processing.	DSL · Reference
Errors & retries	Declarative error handling, per-task or global; backoff strategies.	Wrap unreliable calls, steer to compensations, surface clear failures.	DSL · Reference
Timeouts	Time limits on tasks and/or the whole workflow.	Prevent hangs; bound external waits; enforce SLAs.	DSL · Reference
Schedule	Start workflows on CRON/time schedules.	Nightly batches, hourly ingestions, weekly newsletters.	DSL · Reference
Events & correlation	Event shapes/types and how inbound events correlate to an instance.	Match review events to the right pending workflow, multi-event joins.	DSL · Reference
Expressions & data mapping	How to read/write parts of workflow data; `jq` expression dialects.	Map payloads to APIs, filter data, compute booleans for `when`.	DSL · Reference
Auth, secrets, refs	Reference credentials/secrets/config for calls without hardcoding.	Call secured services, keep definitions portable and safe.	DSL · Reference

Document

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

Identify the workflow and which schema version you’re using (e.g., 1.0.0).

DSL · Reference

Data model

Workflow data context (JSON). Tasks read/write slices of this context.

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

DSL · Reference

Tasks (do)

Ordered list of steps to execute. Each item is a task (see next rows).

Define your flow: set → call → emit/listen → branch → loop, etc.

DSL · Reference

Task: set

Writes/merges values into workflow data.

Initialize fields, compute constants, stash intermediate values.

DSL · Reference

Task: call

Invokes a service/function/agent and maps input/output.

HTTP/GRPC/OpenAPI calls, LangChain4j agents, internal functions.

DSL · Reference

Task: emit

Emits an event (e.g., CloudEvent) with payload from workflow data.

Notify other services, fan-out, integration events.

DSL · Reference

Task: listen

Waits for one or more events and resumes with received data.

Human-in-the-loop approvals, external signals, callbacks.

DSL · Reference

Conditions / branching

Execute tasks only when an expression is true; branch/choose paths.

Feature flags, guardrails, compliance checks, “happy/error” paths.

DSL · Reference

Loops / repetition

Repeat a task block until a condition is met; bounded by timeouts/retries.

Agentic revise-loops, polling, chunked processing.

DSL · Reference

Errors & retries

Declarative error handling, per-task or global; backoff strategies.

Wrap unreliable calls, steer to compensations, surface clear failures.

DSL · Reference

Timeouts

Time limits on tasks and/or the whole workflow.

Prevent hangs; bound external waits; enforce SLAs.

DSL · Reference

Schedule

Start workflows on CRON/time schedules.

Nightly batches, hourly ingestions, weekly newsletters.

DSL · Reference

Events & correlation

Event shapes/types and how inbound events correlate to an instance.

Match review events to the right pending workflow, multi-event joins.

DSL · Reference

Expressions & data mapping

How to read/write parts of workflow data; jq expression dialects.

Map payloads to APIs, filter data, compute booleans for when.

DSL · Reference

Auth, secrets, refs

Reference credentials/secrets/config for calls without hardcoding.

Call secured services, keep definitions portable and safe.

DSL · Reference

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

Where Quarkus Flow fits

Quarkus Flow provides a Java fluent API that maps 1:1 to the concepts above (e.g., set, call, emit, listen, conditions/loops, retries/timeouts), discovers your Flow classes at build time, and integrates with CDI, HTTP/OpenAPI, messaging, and LangChain4j for agentic workflows.