SSOT Everywhere
SSOT Everywhere
SSOT (Single Source of Truth) started as a data governance term and has expanded into a principle for code, documentation, and schema operations. This article covers the origin, areas of application, and trade-offs.
1. About SSOT
The Wikipedia "Single Source of Truth" definition:
"the practice of structuring information models and associated data schemas such that every data element is mastered (or edited) in only one place."
The principle is to structure things so that each data element is authoritatively edited in one place only. The same idea is also called SPOT (Single Point of Truth).
The concept originated in enterprise data management, and implementation strategies are usually:
- Master Data Management (MDM) — an authoritative hub receives updates from multiple sources, decides, and propagates.
- Event Sourcing — store system state as an ordered sequence of events. The event store itself is the truth.
- Data Warehouse — a single version for reporting/analytics. Operational data lives separately.
2. Code SSOT
Don't duplicate the same constant, type, or business rule across multiple files. Pick one place as the SSOT and import. The same context as the "single representation of knowledge" of the DRY principle (01-kiss-dry-yagni).
3. Documentation SSOT
If the same fact (e.g. port mapping, environment variable list, API endpoint) is written in multiple READMEs, the facts diverge when one side is not updated. Designate one file as the SSOT and reference it elsewhere by link only.
4. Schema SSOT
A DB schema runs on one of two models:
- Single SQL SSOT — a file like
schema.sqlis the truth of the current schema. All changes directly modify this file. Often kept idempotent with constructs likeCREATE TABLE IF NOT EXISTS. - Migration tools — Flyway (Redgate, 2010), Liquibase (2006), Alembic (SQLAlchemy), etc. take an ordered sequence of changes as the SSOT. Each migration file holds a change at one point in time, and the current schema is built by cumulative application.
Trade-offs of the two models:
| Axis | Single SQL SSOT | Migration tool |
|---|---|---|
| Grasp of current state | Instant from one file | Track all migrations cumulatively |
| Operational DB change | Needs separate procedure | Standard automatic application |
| History | Relies on git history | Tool keeps it explicitly |
| Suitable environment | Few schema changes, frequent environment rebuilds | Long-lived operational DB with frequent changes |
For small teams or new projects, or when the schema can be rebuilt fresh in each environment, the single SQL model is lighter. When the operational DB lives long and data must be migrated, a migration tool is safer.
5. Other paths
SSOT is not always feasible. The Wikipedia entry also notes that "in enterprises where multiple information systems each need shared data, an ideal implementation is rare".
Alternatives or complements:
- Distributed SSOT based on Eventual Consistency — keep one authoritative source but allow replicas, tolerating update lag.
- Federated Truth — keep an authoritative source per domain, and synchronize between domains via explicit contracts (API, events).
In distributed systems, true single-truth often costs heavily, so domain-level SSOT is commonly considered realistic (see CAP in 04-tradeoff-not-bestpractice).
6. Common shapes
One form of documentation SSOT:
# port-mapping.md (SSOT)
| Service | Port |
|---|---|
| api | 8080 |
| web | 3000 |
# Other READMEs
See [port-mapping.md](docs/port-mapping.md) for port mapping.
Schema SSOT (single SQL):
-- schema.sql
CREATE TABLE IF NOT EXISTS users (
id BIGSERIAL PRIMARY KEY,
email TEXT NOT NULL UNIQUE,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
Schema SSOT (Flyway):
db/migration/
V1__create_users.sql
V2__add_user_status.sql
7. Common pitfalls
"Written in one place" and "one place is authoritative" are different — without agreement on which source is authoritative, people look at the copy closest to them.
Without splitting the SSOT into smaller pieces, one file becomes bloated and change conflicts grow — split SSOT by domain.
Even after introducing migration tools, if humans run direct ALTER on the operational DB, the tool's SSOT value collapses — operational rules narrow the change path to a single line.
Documentation SSOT and code-side facts (e.g. environment variable names) drift apart — when possible, extract automatically from code (lint, code generation), or require doc changes alongside fact-changing PRs.
Closing thoughts
SSOT is the simple principle of "edit authoritatively in only one place". It applies to code, documentation, and DB schema alike. Narrow the change path for the operational DB to a single line, and keep the same fact in one place while other places only link — these two are the practical core of SSOT.
Next
- folder-as-contract
- tradeoff-not-bestpractice
Wikipedia Single Source of Truth · Flyway official docs · Liquibase official docs · Alembic official docs · Martin Fowler Evolutionary Database Design · Event Sourcing (Martin Fowler) · Pat Helland — Data on the Outside vs. Data on the Inside for reference.