AI glossary Operations
What is an executable specification?
← All glossary termsA specification precise enough to run, so that it generates or drives tests, simulations or code without manual translation.
Explained
An executable specification is a description of required behaviour written precisely enough that a machine can check it or act on it. Instead of a document that people read and then translate into tests, the specification itself runs: concrete examples bound to test code, schemas that validate data, contracts that check an API, or constraints that bound what a language model may return. It bridges human intent and automation, reduces ambiguity and keeps the specification and the system in step. In spec-driven and AI-assisted development it is what lets generated code be verified against what was actually asked for.
Common forms
- Scenarios in Given-When-Then form (Gherkin), bound to step definitions that run them as automated acceptance tests.
- Specification by example: tables of concrete inputs and expected outputs agreed with the business.
- Schemas and contracts, such as JSON Schema or OpenAPI, that validate data and interfaces automatically.
- Property-based tests that state rules the system must always satisfy and generate cases to check them.
- For LLM features, structured-output schemas and evaluation cases that each response must pass.
Why it matters
Ordinary specifications drift: the document says one thing, the code does another, and nobody notices until something breaks. An executable specification fails loudly when the system stops doing what it describes, so it stays current.
It also changes the conversation with the business. Concrete examples are easier to agree on than abstract rules, and once agreed they become both the documentation and the test.
Executable specifications and AI
When AI agents write code, the bottleneck moves from writing to verifying. A precise, executable specification gives the agent a clear target and gives the team an automatic way to check the result: the generated code either passes the scenarios, schemas and contracts or it does not.
The same idea applies to AI features themselves. Output schemas, evaluation sets and acceptance criteria written as checks turn a vague expectation of good answers into something that can be tested on every change.
Frequently asked questions
What is an example of an executable specification?
A Gherkin scenario such as: given a customer with an expired card, when they place an order, then payment is rejected and they are asked to update the card. Each line is bound to test code, so the scenario runs against the system and passes or fails.
What is specification by example?
It is the practice of specifying behaviour through concrete examples rather than abstract statements. Martin Fowler describes it as one of the roles of tests in agile development: writing tests first is using examples as the specification.
How does an executable specification relate to BDD?
Behaviour-driven development (BDD) is one of the main ways of producing executable specifications. Teams describe behaviour in a shared language such as Gherkin, and tools like Cucumber run those descriptions as tests.
What is the difference between an executable specification and a unit test?
A unit test checks a small piece of code and is written for developers. An executable specification describes behaviour that matters to the business or to users, in terms they can read, and checks the system against it. Both are automated.
Why are executable specifications useful in spec-driven development?
In spec-driven development, the specification is the source from which design, code and tests are derived, increasingly with AI. Making it executable means every derived artefact can be checked against it automatically, which keeps them aligned.
Decision guides that use this term
Where it shows up at Thinkia
Further reading
Related terms
Sources
Updated: 2026-10-21