# Domain Spec

> 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.

- Skill: `korsmakolnikov/domain-spec` (Agent Skill)
- Install (CLI): `npx get-skill add korsmakolnikov/domain-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/korsmakolnikov/domain-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: korsmakolnikov (https://skillmd.com/u/korsmakolnikov)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/korsmakolnikov/domain-spec

---


# 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

```yaml
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:

* `id`s 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`:

```sh
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.

