openwdl/wdl: the specification behind the Workflow Description Language

This repository is a language definition, not a program you run

The clearest way to understand what lives here is to notice what the repository does not contain. There is no engine, no runtime, no command line tool and no scheduler. The description is simply a specification for the Workflow Description Language, and the repository root holds SPEC.md, a CHANGELOG.md, documentation, a LICENSE and the CODE_OF_CONDUCT.md, plus a shields directory used for the conformance badges.

So the project is the document that everyone else implements. The README states the point plainly: the WDL specification contains all relevant information for users and developers, including those wanting to implement an execution engine. It is a contract, in the same way that a protocol specification is a contract.

That framing decides how you should evaluate it. You are not choosing a tool you will depend on for a service level agreement. You are choosing a notation, and you are choosing the set of engines that implement it.

The community angle is the second thing to understand. The language is driven and developed by a community of distributed volunteers as an open standard, there is no single execution engine, and anyone can build tooling to contribute to the ecosystem. The README points to an official website and blog, to GitHub and Slack for interaction, and to a getting started documentation set for people new to the language.

task and workflow are the two units of the language

The language introduces a domain specific language aimed at simple but powerful facilities for three things: defining atomic units of computation, connecting those units into a larger computation graph, and scaling execution of those graphs in multiple environments.

Those three facilities map onto three named concepts. A task is the atomic unit of computation. A workflow connects tasks into a computation graph. And the third facility, scaling execution across environments, is where the language departs from a plain scripting model.

WDL differentiates itself from other workflow languages by focusing on ease of implementation and accessibility to a wide range of users, and the README names software engineers, domain experts such as biologists, and operators of production computational systems as the intended audience. That accessibility claim is the design constraint behind the syntax, which is described as human readable and writeable.

The idiomatic execution patterns are also part of the standard rather than extensions of it. Conditional execution, dynamic resource allocation and scatter-gather operations are simply expressed, in the words of the README. Scatter-gather in particular is the pattern that distinguishes a workflow language from a job script: you describe one task and how it fans out over a set of inputs, rather than generating N job files yourself.

The conformance suite is what makes several engines trustworthy

The README opens with a table of engines and their conformance test results, and this is the most operationally important part of the document. MiniWDL, Sprocket, Toil and Cromwell each have a badge linked to a CI run, so the state of each engine against the specification is visible without reading issue trackers.

Why this matters is specific to the open standard model. When there is no single engine, the usual objection is that a language implemented by four teams will mean four slightly different dialects. The conformance suite answers that directly. An engine either passes the shared test suite or it does not, and the badge tells you which.

It also changes how you choose an engine. Rather than evaluating four projects on their own features, you can ask a sharper question: which of them currently passes the conformance suite for the version of the specification you are writing against.

The README notes that several engines and platforms exist and cover most execution environments, listing all major HPCs, all major clouds and local execution, with the ecosystem page linked from the repository. That is the practical payoff of the standard, and it is also the reason the conformance table sits at the top of the README rather than at the bottom.

The language version and the specification version are different numbers

WDL follows semantic versioning for all of its products, but the README draws a distinction that causes confusion the first time you hit it.

The WDL language has a two number version, for example 1.3. An increase in the minor number, such as from 1.2 to 1.3, indicates the addition of, or non-breaking changes to, the language or the standard library functions. An increase in the major number, such as from 1.0 to 2.0, indicates that breaking changes have been made.

The WDL specification has a three number version, for example 1.3.0. The specification version tracks the language version, but there can also be patch releases, marked by a change to the third number, that include fixes for typos, additional examples, or non-breaking clarifications of ambiguous language.

So a spec patch release does not mean the language changed, and a language minor bump means every conforming engine needs an update. The repository's release list shows exactly this pattern. v1.3.0, the WDL 1.3.0 release, is dated 2026-01-12, while two specification patch releases, WDL Specification v1.2.1 and v1.1.3, are both dated 2026-02-15.

That sequencing is intentional, and it tells you that older specification lines still receive maintenance after a new language version ships.

Non-breaking work happens on wdl-1.3, breaking work on wdl-2.0

The branch layout encodes the versioning policy, and the README states it in two bullet points.

This repository uses the branch for the current version of the specification as its primary branch, so the root URL always shows the current specification. Users are strongly encouraged to use the current version unless absolutely necessary.

Concretely, the branch for version 1.3 of the specification is where all development of new non-breaking features should be done. The next major version, 2.0, is where all development of new breaking features should be done. Previous versions of the spec can be found on the GitHub branches page.

The default branch is therefore wdl-1.3, which tells you two things at a glance. The current stable language is 1.3, and a 2.0 is in development for anyone who wants early warning of what will break.

The maintenance picture is healthy on the numbers: the last push to the repository was on 2026-09-14, and the specification releases above show both feature work and continued patch maintenance of older lines. For an open standard that is a good sign, since the risk with a community specification is not that it stops improving but that it improves in ways that break the engines you depend on, which is what the conformance suite exists to catch.

Community governance with a committee on top

The README is explicit that the specification only advances through community contributions, and that discussions and issues are only part of what is needed, because help is also needed to implement changes to the specification. The contributing guide is hosted in the openwdl governance repository rather than in the specification repository itself.

Governance is community driven but not unstructured. The specification is overseen by a governance committee and process, with the details in the governance repository, and the README invites people interested in governance to join the Slack and post in the general channel.

The engine conformance table closes the loop on that structure. Volunteers write the specification, volunteers implement engines, and the test suite is the shared mechanism that keeps the two honest.

For an organisation betting on WDL, the practical thing to check is the governance repository and the contributing guide, not just the specification text. A standard maintained by distributed volunteers with a named committee is a different risk profile from one maintained by a single vendor, and your exit cost depends on how many engines you could realistically switch to.

BSD 3-Clause covers the text, and engine choices carry the real upgrade cost

The licensing position is simple and permissive. The WDL specification is made available under the BSD 3-Clause License, with the copyright held by The OpenWDL Developers.

That licence covers the specification document itself. It does not cover the engines, and it does not automatically cover the workflows you write. Those live under whatever terms their engine and their execution environment impose.

The upgrade cost in this ecosystem is also unusual, because it has two layers. If the language moves from 1.3 to 2.0, your workflow source may need edits, but the specification stays open and readable, so the edits are informed by a document you can quote. If an individual engine lags behind the specification, your workflow may still run on it, with the newer language features unavailable to you, which is a per engine limitation rather than a language one.

That is the trade the open standard model offers. You accept that features arrive unevenly across engines and that upgrades are coordinated by a community rather than a vendor roadmap, and in exchange your workflow definitions stay portable across execution environments that are genuinely different, from a laptop to a cluster to a cloud platform.

Editorial conclusion

This repository suits a team that writes analysis pipelines for people who are not programmers, and biologists are the case the README names, or anyone who needs one workflow definition to run on a laptop, on an HPC cluster and on a cloud platform without rewriting it. It does not suit a team that wants a single engine with a single support contract, because there is no single execution engine and the specification only defines the language. Before you build a workflow in WDL, read the getting started documentation as the README strongly recommends, decide which engine you will actually run, and check the conformance table for that engine, since it is the only place where you can see which implementations currently pass the test suite, and remember that the current specification branch is wdl-1.3 while breaking changes land on wdl-2.0.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. openwdl/wdl on GitHub
3. Project website
4. README
5. Releases