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:

1. Single SQL SSOT — a file like schema.sql is the truth of the current schema. All changes directly modify this file. Often kept idempotent with constructs like CREATE TABLE IF NOT EXISTS.
2. 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.