domain-spec
The ADL says how the code is organised; the domain spec says what the code
must guarantee. hughes writes it with the user, in two passes, and unclebob
turns every entry into a red test.
File
One file, .sources/spec.yaml, next to the ADL and, like it, never
committed: never stage it. It grows in two passes: domain (before ford)
adds entities, relations and constraints; contracts (after ford)
adds contracts and properties, tied to the ADL components.
Format
spec: 1
system: bookmarks # the ADL SYSTEM physical name
entities:
- name: Bookmark # PascalCase, unique
description: A web page a user saved, to be tagged and archived.
fields:
- name: id
type: integer # free text, in the target language's terms
required: true
- name: status
type: one of open, archived
invariants:
- id: archived-bookmark-has-a-tag
rule: An archived bookmark carries at least one tag.
- name: Tag
description: A label a user defines to classify their bookmarks.
fields:
- name: name
type: string
required: true
relations:
- from: Bookmark
to: Tag
kind: many_to_many # one_to_one | one_to_many | many_to_one | many_to_many
description: A bookmark is tagged with any number of tags.
rules: # optional
- id: tag-belongs-to-the-same-user
rule: A bookmark is tagged only with tags of its user.
constraints: # rules spanning several entities or the system
- id: tagging-is-atomic
rule: Either every tag of a request is applied or none is.
contracts:
- id: tag-bookmark
component: bookmarks.api.bookmark_tagger # ADL physical path
operation: tag/2 # name/arity or function name
pre:
- The bookmark exists.
post:
- The bookmark carries exactly the requested tags.
errors:
- when: The bookmark does not exist.
returns: "{:error, :bookmark_not_found}"
properties:
- id: tagging-twice-equals-tagging-once
component: bookmarks.api.bookmark_tagger
kind: idempotence # see the kinds below
forall:
- name: bookmark
generator: an existing bookmark
- name: tags
generator: a non-empty list of valid tags of its user
holds: Tagging twice with the same tags leaves the same state as tagging once.
Rules:
ids are kebab-case and unique across the whole file; tests and reviews
cite them.
- Every rule,
pre, post, holds and generator is one C2-level English
sentence that a test can check. No "should", no "for now", no TODO.
relations name existing entities; contracts and properties name a
COMPONENT or LIBRARY defined in the ADL (DEFINE … AS <physical>), by its
physical path from the system down (nested physical names that already
repeat their parent's, such as BookmarksWeb.API.BookmarkFinder inside
BookmarksWeb.API, are not repeated in the path).
- A property's
forall lists every input it quantifies over; the generator
describes the domain of values, not a library call.
Property kinds
kind |
It states |
Typical test |
invariant |
Something always true of the result or the state. |
Generate inputs, run, assert the invariant. |
roundtrip |
Encoding then decoding (or doing then undoing) gives the input back. |
decode(encode(x)) == x |
idempotence |
Applying twice equals applying once. |
f(f(x)) == f(x) |
metamorphic |
How the output changes when the input changes in a known way. |
Compare f(x) with f(transform(x)). |
model |
The component behaves like a simpler reference model. |
Run the same commands on both, compare. |
oracle |
The result equals that of a trusted implementation. |
f(x) == trusted(x) |
Validation
Run spec-check from the project root after every write; it must print ok:
spec-check --stage domain .sources/spec.yaml # after the first pass
spec-check --stage contracts .sources/spec.yaml # after the second pass
It checks the structure, the kinds, the id format and uniqueness, the entity
names relations refer to and, at the contracts stage, that contracts and
properties are present and every component is defined in the .sources/
files. It prints one line per problem and exits non-zero on any. Whether a
sentence is testable is the interview's job.
From the spec to the tests (unclebob)
Each entry of the component being implemented is at least one red test, one
at a time, through the normal cycle:
- A contract gives example-based tests: one red for the main
post, one
per errors entry, one per pre whose violation must be handled.
- A property gives one property-based red: ExUnit with StreamData
(
use ExUnitProperties, property … do check all … end) in Elixir,
Hypothesis (@given) in Python. Build the generators from the forall
entries in the project's shared generator module.
- Entity invariants, relation rules and constraints are tested
where the component that enforces them is implemented, as a property when
they quantify over values, as an example otherwise.
- The test name states the behaviour in plain words; a comment cites the spec
id (
# spec: tagging-twice-equals-tagging-once), so coverage can be checked
with grep.
- An entry that cannot be tested as written (an unclear sentence, a generator
that cannot be built) is raised with the user, never skipped silently.
Adding a missing property-based testing library (stream_data in mix.exs,
hypothesis in the Python dependencies) is the user's decision.
1---2name: domain-spec3description: Reference for the domain spec (.sources/spec.yaml) of this workflow, the structured input next to the ADL that lists the entities, their relations, the system constraints, the contracts of the component operations and the properties to test with property-based tests (StreamData, Hypothesis). Covers the format, the spec-check validator and how each entry becomes a test. Load it before reading, writing or testing against a spec.4metadata:5 source: https://skillmd.com/skills/korsmakolnikov/domain-spec6---78# domain-spec910The ADL says how the code is organised; the domain spec says what the code11must guarantee. hughes writes it with the user, in two passes, and unclebob12turns every entry into a red test.1314## File1516One file, `.sources/spec.yaml`, next to the ADL and, like it, **never17committed**: never stage it. It grows in two passes: **domain** (before ford)18adds `entities`, `relations` and `constraints`; **contracts** (after ford)19adds `contracts` and `properties`, tied to the ADL components.2021## Format2223```yaml24spec: 125system: bookmarks # the ADL SYSTEM physical name2627entities:28 - name: Bookmark # PascalCase, unique29 description: A web page a user saved, to be tagged and archived.30 fields:31 - name: id32 type: integer # free text, in the target language's terms33 required: true34 - name: status35 type: one of open, archived36 invariants:37 - id: archived-bookmark-has-a-tag38 rule: An archived bookmark carries at least one tag.39 - name: Tag40 description: A label a user defines to classify their bookmarks.41 fields:42 - name: name43 type: string44 required: true4546relations:47 - from: Bookmark48 to: Tag49 kind: many_to_many # one_to_one | one_to_many | many_to_one | many_to_many50 description: A bookmark is tagged with any number of tags.51 rules: # optional52 - id: tag-belongs-to-the-same-user53 rule: A bookmark is tagged only with tags of its user.5455constraints: # rules spanning several entities or the system56 - id: tagging-is-atomic57 rule: Either every tag of a request is applied or none is.5859contracts:60 - id: tag-bookmark61 component: bookmarks.api.bookmark_tagger # ADL physical path62 operation: tag/2 # name/arity or function name63 pre:64 - The bookmark exists.65 post:66 - The bookmark carries exactly the requested tags.67 errors:68 - when: The bookmark does not exist.69 returns: "{:error, :bookmark_not_found}"7071properties:72 - id: tagging-twice-equals-tagging-once73 component: bookmarks.api.bookmark_tagger74 kind: idempotence # see the kinds below75 forall:76 - name: bookmark77 generator: an existing bookmark78 - name: tags79 generator: a non-empty list of valid tags of its user80 holds: Tagging twice with the same tags leaves the same state as tagging once.81```8283Rules:8485* `id`s are kebab-case and unique across the whole file; tests and reviews86 cite them.87* Every rule, `pre`, `post`, `holds` and `generator` is one C2-level English88 sentence that a test can check. No "should", no "for now", no TODO.89* `relations` name existing entities; `contracts` and `properties` name a90 COMPONENT or LIBRARY defined in the ADL (`DEFINE … AS <physical>`), by its91 physical path from the system down (nested physical names that already92 repeat their parent's, such as `BookmarksWeb.API.BookmarkFinder` inside93 `BookmarksWeb.API`, are not repeated in the path).94* A property's `forall` lists every input it quantifies over; the generator95 describes the domain of values, not a library call.9697### Property kinds9899| `kind` | It states | Typical test |100|---|---|---|101| `invariant` | Something always true of the result or the state. | Generate inputs, run, assert the invariant. |102| `roundtrip` | Encoding then decoding (or doing then undoing) gives the input back. | `decode(encode(x)) == x` |103| `idempotence` | Applying twice equals applying once. | `f(f(x)) == f(x)` |104| `metamorphic` | How the output changes when the input changes in a known way. | Compare `f(x)` with `f(transform(x))`. |105| `model` | The component behaves like a simpler reference model. | Run the same commands on both, compare. |106| `oracle` | The result equals that of a trusted implementation. | `f(x) == trusted(x)` |107108## Validation109110Run `spec-check` from the project root after every write; it must print `ok`:111112```sh113spec-check --stage domain .sources/spec.yaml # after the first pass114spec-check --stage contracts .sources/spec.yaml # after the second pass115```116117It checks the structure, the kinds, the id format and uniqueness, the entity118names relations refer to and, at the `contracts` stage, that `contracts` and119`properties` are present and every `component` is defined in the `.sources/`120files. It prints one line per problem and exits non-zero on any. Whether a121sentence is testable is the interview's job.122123## From the spec to the tests (unclebob)124125Each entry of the component being implemented is at least one red test, one126at a time, through the normal cycle:127128* A **contract** gives example-based tests: one red for the main `post`, one129 per `errors` entry, one per `pre` whose violation must be handled.130* A **property** gives one property-based red: ExUnit with StreamData131 (`use ExUnitProperties`, `property … do check all … end`) in Elixir,132 Hypothesis (`@given`) in Python. Build the generators from the `forall`133 entries in the project's shared generator module.134* Entity **invariants**, relation **rules** and **constraints** are tested135 where the component that enforces them is implemented, as a property when136 they quantify over values, as an example otherwise.137* The test name states the behaviour in plain words; a comment cites the spec138 id (`# spec: tagging-twice-equals-tagging-once`), so coverage can be checked139 with `grep`.140* An entry that cannot be tested as written (an unclear sentence, a generator141 that cannot be built) is raised with the user, never skipped silently.142143Adding a missing property-based testing library (`stream_data` in `mix.exs`,144`hypothesis` in the Python dependencies) is the user's decision.