Two native formats, no translation layer. Behaviour is described in Gherkin; interfaces are described in OpenAPI. Both are ordinary text, both are read by tools you already use, and neither is trapped inside the platform.
OpenAPI documentsHow interfaces are written, and what the contract can express
Cross-format consistencyThe check that catches mismatches between behaviour and interfaces
Assertion strengthWhy a passing test suite is not proof, and how we grade it
Why native formats
The specification is the artefact a human reads, a tool executes, and a diff tracks. Every layer we could have put in between — a proprietary DSL, a YAML schema of our own, an intermediate representation — would be a layer that has to be correct, and a place where meaning can be lost.
Using Gherkin and OpenAPI means:
- The specification is readable by anyone who already knows BDD or API design, with no training from us.
- Your existing tooling reads it. Cucumber, pytest-bdd, Playwright, Spectral, Prism, schemathesis, Dredd, and your generators all work against the same files.
- The specification lives in your repository as text, diffable by Git, greppable, and not subject to our pricing or our availability.
- When you leave, you leave with something your team still understands.
The division of labour
Gherkin and OpenAPI answer different questions, and a good specification uses each for what it is good at.
| Question | Format |
|---|---|
| What happens when a customer does X? | Gherkin |
| What must never happen? | Gherkin |
| What is the shape of the request and the response? | OpenAPI |
| Which fields are required, and what are their constraints? | OpenAPI |
| What happens on a specific error response? | Both — the schema in OpenAPI, the behaviour in Gherkin |
The hard cases are the ones that need both. "The refund endpoint returns 422 when the order is outside the refund window" is half a contract and half a behaviour: OpenAPI says the 422 response exists and what it contains; Gherkin says when it happens. Checking that the two agree is the job of the cross-format consistency check.
OpenAPI documentsHow interfaces are specified in OpenAPI, and what the contract checks can prove.
Cross-format consistencyThe checks that catch Gherkin and OpenAPI disagreeing with each other.
Assertion strengthWhy a passing suite proves little on its own, and how scenarios are graded for strength.