Notesdata-models🌱 seedling

Schema-on-Read

Also: Schemaless · Schema-on-Write · Implicit Schema · Schema Flexibility

There is always a schema; the question is when it's enforced. Schema-on-write checks every write against a declared schema, while schema-on-read accepts any structure and leaves interpreting it to the code that reads.

Why it exists

Some data really is heterogeneous: many kinds of object that don't justify a table each, or payloads whose shape is set by someone else (third-party webhooks). Forcing them into one declared schema is friction.

How it works

  • Schema-on-write (relational tables): writes that don't fit are rejected, so every stored record is known to match. Like static typing.
  • Schema-on-read (document stores): writes are accepted as they are; readers handle every shape ever written. Like dynamic typing.
  • A change such as splitting name into first and last: schema-on-write runs ALTER TABLE plus a backfill of every row; schema-on-read writes the new shape for new records and adds a fallback in readers.
  • Adding a column is cheap in modern RDBMSs (Postgres 11+ even with a constant default; instant in MySQL 8.0). The backfill is the expensive part, in any model.
  • Validation can be layered on: MongoDB $jsonSchema validators (since 3.6), CHECK constraints on Postgres jsonb.

Trade-offs

Schema-on-write Schema-on-read
Change cost paid once, up front (migration) paid on every read, as long as old shapes exist
Guarantees every row has the declared shape none, unless validated
Best for uniform records, many readers heterogeneous or externally defined data

In practice

  • Uber's Schemaless (2016) stored immutable JSON cells in sharded MySQL: schema-on-read on top of a relational engine.

Pitfalls

  • "Schemaless" read as "no schema": the schema still exists, scattered and unversioned across reading code.
  • Old shapes never die unless something backfills them, so fallback code accumulates.

Recall

These cards are also in your review deck, scheduled with spaced repetition.