Open Workflow Specification: a vendor-neutral DSL for serverless workflows

A language, not an engine

The Open Workflow Specification is the official specification for a domain specific language aimed at defining and executing workflows in serverless environments. The repository holds the specification itself, and its language is Gherkin, which is a hint about the shape of the project: this is a document and a set of test features, not a program you install and run.

That distinction decides who should care. The project describes the ecosystem as vendor-neutral, open-source and community-driven, and it is hosted by the Cloud Native Computing Foundation, having been approved as a Cloud Native Sandbox level project on July 14, 2020. A vendor-neutral language matters in a specific situation: you want to describe an order handling flow, a data pipeline or an approval chain once, and you want to be able to move it between execution engines without rewriting it, or you want the engine vendor to be measured against a published contract rather than against a proprietary format.

The stated features of the DSL are the ones you would expect from a workflow language for this kind of environment. Events are first class, with support for formats including CloudEvents, and workflows can interact with services over standard application protocols such as HTTP, gRPC, OpenAPI and AsyncAPI. Functions hosted on different platforms can be invoked from a workflow, which is the function-as-a-service orientation of the design. Timeouts can be defined for workflows and tasks, error handling strategies can be declared, and workflows can be scheduled with CRON expressions or triggered by events.

For a team with a single engine and no plans to move, the honest assessment is that this repository gives you a document to read and a set of features to run, and that is a weaker payoff than it looks like from the outside.

DSL, conformance kit, SDKs, runtimes and tooling

The README organises the ecosystem into five parts, and knowing which one you need is the fastest way to navigate the repository.

The DSL is the core, described in dsl.md, and it defines the fundamental syntax and semantics of the specification. A separate dsl-reference.md file sits at the top level, and a schema directory holds the machine readable form of the same thing, so a tool can validate a workflow file against it rather than parsing prose.

The CTK, the Conformance Test Kit, lives in its own directory and is described as a set of Gherkin features used for both conformance testing and Behaviour Driven Development. That dual purpose is the neat part of the design. The same feature file that a runtime vendor runs to prove compliance can be read by a developer writing their own workflow, in the same Given/When/Then form, which means the specification and its test suite teach the same lesson in the same language.

The SDKs exist to consume workflows. They are described as enabling developers to interact with workflows in various programming languages, with functionality for reading, writing, building and validating workflows, and the project publishes them for .NET, Go, Java, PHP, Python, Rust and TypeScript. The README is explicit that contributions of new SDKs are welcome, so the list is a snapshot rather than a fixed set.

Runtimes are the execution environments for workflows written in the DSL, and the README lists them in a table that includes Apache KIE SonataFlow, described as a tool for building cloud-native workflow applications for services and events orchestration and choreography, a Java SDK reference implementation described as a full compliant implementation of the specification, and Quarkus Flow, described as a full Java Enterprise implementation. Tooling covers the rest of the lifecycle, from development and debugging through to management.

The examples folder is the fastest way to learn the syntax

The repository carries a large set of example workflows as YAML files, and they are the most efficient introduction to the language available. The names alone describe the feature surface, since each file is named after the pattern it demonstrates. There are files for calling an HTTP endpoint with path interpolation, for supplying query parameters and for setting query headers with expressions, and there are files for redirects, for gRPC calls, for OpenAPI and AsyncAPI, and for invoking a custom function either inline or from a catalog.

Those file names, under examples/ in the repository, are worth reading as a table of contents for the language.

The authentication examples form their own group and show a range of mechanisms rather than one: bearer token with a URI format, plain bearer, OAuth2 with and without a secret, OpenID Connect with and without a secret, and a reusable authentication definition. If you are wondering how a given credential is expressed in the DSL, the answer is almost certainly in one of those files.

There is also an examples README at the top of that directory, so the set is meant to be read rather than merely copied. And because the CTK features are written in Gherkin, the examples and the conformance features describe the same behaviour in two different notations, which is useful when you are writing your own acceptance tests against an implementation.

Schema, use cases and ADRs are the parts a builder actually reads

Beyond the language document, the repository contains the material that implementation teams usually want. The schema directory holds the structured definition of a workflow document, which is what an SDK or a linter validates against, and it is the difference between a specification you read once and a specification a tool can enforce.

The use-cases directory collects the situations the language is meant to cover, and it is where you find out whether the DSL has a first class concept for the thing you are trying to build. If your workflow needs a concept the language does not have, that directory is where you will discover it, and it is also the place to argue for a change.

The adr directory holds architecture decision records, which is a different kind of document again. It records the reasons behind design choices, including the ones that were rejected, and for an engineer joining a project that has to implement the spec, this is often the most valuable and least read material in the repository.

Then there is comparison.md at the top level, a document that sets the specification against other approaches, and a set of governance files: GOVERNANCE.md, MAINTAINERS.md, owners.md, contributing.md, code-of-conduct.md and SECURITY.md. The presence of a security policy in a specification repository is unusual and worth a look, since it tells you how a vulnerability report about the spec or its reference implementations is handled.

The community directory and the weekly meetings and Slack channels linked from the README show how a specification of this kind evolves, which is process rather than product, but it does tell you whether anyone is actually listening.

Releases are patch level and the spec is still version 1.0

The release history is short and tightly packed. Versions 1.0.1, 1.0.2 and 1.0.3 were all published on 2026-07-31, within a few minutes of each other, and the last push was on 2026-10-13, so changes continue to land on the main branch between those tags.

Three patch releases in one afternoon reads like a fix and a re-publish rather than a feature cycle, and the version number is the thing to notice. The specification is at 1.0, and there is no long history of compatibility promises to lean on. Anyone pinning to a tag should be aware that the tag number tells them very little about how much the document moved.

The licence is Apache-2.0, with a LICENSE file at the top of the repository and a badge in the README. The Makefile in the repository shows the house style for headers, adding the Apache header to all files with a target that fetches the addlicense tool:

addheaders:
	@which addlicense > /dev/null || go get -u github.com/google/addlicense
	@addlicense -c "The Serverless Workflow Specification Authors" -l apache .

That target is a small window into the project: contributors are expected to run tooling rather than paste headers by hand, and the copyright holder line is the specification authors rather than an individual.

Where a specification is the wrong thing to reach for

Three cases stand out.

First, if you want to execute workflows today. This repository contains no engine. The runtimes table lists implementations, some of them full implementations of the specification, but adopting the specification means adopting a runtime separately and then implementing the DSL side of the contract in your own code, or finding a runtime that already does it. A team that needs a working workflow this week is looking at the runtime, not here.

Second, if your workflow needs a single engine and will stay there. The vendor-neutral benefit only pays off across engines, and the cost of a portable description is that it is a lowest common denominator. A bespoke engine configuration may express your process better, and the specification will not let you use the engine specific feature that would have made it simple.

Third, if you expect a stable, widely implemented standard. The version numbers are still 1.0.x, the project sits at CNCF Cloud Native Sandbox level rather than graduated, and the SDK list, while it already covers seven languages, is a set of separate repositories each with its own cadence. That is the honest state of a young specification.

The realistic alternative is the runtime-first route: pick one of the listed runtimes, write the workflow in its native format, and accept the lock-in. The difference in approach is the entire point of the specification. Vendor-native gives you a richer feature set, better tooling and a single supported path today, at the cost of being unable to move the workflow. The specification gives you a portable contract, a conformance suite that lets you verify an implementation, and a validation schema that a tool can enforce, at the cost of running with whatever the lowest common denominator can express. Between the two, a platform team that expects to change engines should start from the DSL, and a product team that has already chosen its engine should stay there.

Editorial conclusion

The Open Workflow Specification is worth adopting when you intend to run the same workflow on more than one engine, or when you want a written contract that a runtime vendor can be held to, and it gives you concrete starting points in the dsl.md document, the schema directory, the conformance test kit and the examples folder. It is the wrong dependency for a team that just needs one workflow to run on one platform, since it ships no execution engine of its own. Before you build on it, read dsl.md and dsl-reference.md end to end, run the conformance features in the ctk directory against your runtime, and check the version of the specification you have pinned against the v1.0.x tags.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. open-workflow-specification/specification on GitHub
3. Project website
4. README
5. Releases