Concepts
The mental model — registry, specs, mocks, governance, versioning.
The shape of Spec0
Four primitives. Everything else is composition.
| Primitive | What it is | Where it lives |
|---|---|---|
| Spec | An OpenAPI document — a versioned, immutable snapshot. | The registry. |
| API | A logical service identified by <org>/<name>. Owns a stream of specs. | The registry, scoped to a team. |
| Mock | A live HTTP server bound to a published spec. | mocks.spec0.io/m/<id>. |
| Subscription | A consumer's declared dependency on an API. | The registry. |
Specs are immutable
Every spec0 publish produces a new spec. Old versions don't disappear; subscribers can pin to any tag. Spec0's diff compares any two and answers is this a breaking change deterministically — it's the gate --semver uses to decide between patch, minor, and major bumps.
The registry is the source of truth
If a service can talk to the registry, it can:
- discover what APIs exist
- pull the latest spec for any of them
- subscribe and get notified on changes
- publish updates (with permission)
The CLI, the dashboard, CI runners, and AI agents over MCP — all four are clients of the same REST surface.
Mocks track specs, not the other way around
A mock is provisioned from a published spec. Update the spec and the mock follows on the next refresh. There is no parallel "mock definition" to keep in sync — the mock is the spec interpreted by the mock server engine.
Governance is opt-in
You can publish without lint rules, without breaking-change gates, without team ownership. Quality controls are layers you add — --min-score, --save-ruleset, team policies — when a contract becomes load-bearing.
Versioning, briefly
pull <api>@<tag>— fetch a specific version.pull <api>@latest— fetch the head of the stream.diff <a> <b>— works against files or registry refs.log <api>— chronological tag list.
The canonical CI gate lives in block-on-breaking-changes.