FlowDrop Workflow Specification 1.0

The FlowDrop Workflow Specification is now at 1.0. It was tagged today, and it is live at flowdrop.io/spec.

In September we published a draft and explained why a workflow’s meaning has to live outside any one engine. We won’t repeat that here. This post is about what 1.0 promises and how you can put the specification to work.

What 1.0 means

The numbers first, because they are the easiest way to see what you’re getting:

• 386 rules in force: 217 core, 167 extended and 2 optional.
• 41 rulings: decisions that correct or clarify rules, kept next to the rules they touched.
• 53 conformance fixtures: test cases an implementation can run against itself.
• One page for every rule, under /spec/rules/, each with a permanent identifier.

The draft post counted 399 rules, which was right at the time. 1.0 counts the rules in force, and an identifier that is withdrawn stays reserved, so nothing you cited has changed meaning.

“Stable” has a specific meaning here. An identifier such as STORE-2 means one thing forever. It is never renumbered and never reused. A defect found in a rule is reported against the repository and fixed by a ruling: a short written decision that becomes part of the specification. If you wrote a test against a rule today, you will be able to read, years from now, exactly how that rule has been corrected.

The specification is still a target. Where an implementation disagrees with a rule, the rule is what is intended and the implementation has a defect, unless the rule itself is wrong, which is a bug you can report. It is informative only: it issues no certification, grants no mark, and records no implementation status. Each implementation publishes its own standing in its own documentation.

What is in it

The rules cover how a workflow is written, stored, validated and executed: storage, schema, the expression language, the runtime, memory, error handling, orchestration and the HTTP API. Every rule carries its level and the profiles it belongs to, so a team building a storage API can see what applies to them without reading a full runtime’s worth of text.

FlowDrop for Drupal, the @flowdrop/flowdrop editor library on npm, and a Rust backend are the implementations that aim at it.

The text is licensed CC BY 4.0, and the code and fixtures are MIT. Quote it, translate it, copy the fixtures into your own test suite.

Does it stand on its own?

A specification written by the people who wrote the first implementation has an obvious weakness: it can lean on things only they know. So we ran a check.

Two independent implementations of one part of the specification, parameter resolution, were written from the spec text alone. One in Python, one in TypeScript. Neither author saw any FlowDrop code. Both passed all 22 held-out fixtures.

That is a check on one part of the specification, not the whole of it, and we’d rather say so plainly. But the more useful result was the questions the two implementers had to guess at. Every place where the text left them guessing was a place where a rule was unclear. Those questions fed the final round of fixes before 1.0.

How to use it

Read the rules. Start at flowdrop.io/spec and browse by family, profile or level. Each rule says what must happen, not how.

Feed it to a tool. The specification is published for machines as well as people:

• rules.json: every field of every rule, plus backlinks and the identifiers the specification has declined.
• llms.txt: an index of every rule, one line each.
• llms-full.txt: the whole specification as one document.
• Every rule page also has a markdown twin at its own URL with .md appended.

Test an implementation. The conformance fixtures name the rules that decide each outcome. Run them against your backend and each failure points straight at a rule. Cite rule identifiers in your own tests too. They are permanent, so the test keeps its meaning.

Report a defect. If a rule is wrong, unclear, or two rules disagree, open an issue on GitHub. That is the most useful thing you can file. The contributing guide explains the difference between an editorial fix and a change to what implementations must do. The second kind needs a ruling first.

Where to go next

• The specification: flowdrop.io/spec
• The source: github.com/flowdrop-io/flowdrop-spec
• Why we wrote it: 100% test coverage, and still wrong

If you build a FlowDrop backend, or are thinking about one, tell us where the text gets in your way. That is how 1.1 gets better.