One post tagged with "schema documentation"

Database Normalization Is Not Enough: Context-Aware OLTP Schema Design

April 28, 202614 min read

The data is right there. The meaning is not.

That gap — between what your OLTP schema stores and what it means — has quietly become the most expensive problem in modern data work. The textbook half is solved. Tables normalize to 3NF, foreign keys check out, migrations ship without locking, and most senior engineers can stamp out a clean transactional schema in their sleep.

The unsolved half is everything the schema doesn't say. The intent behind a column. The grain of a row. The business definition of an enum value. The mutability of a foreign key target. None of it lives in the schema, the catalog, or the data dictionary — and the cost of that silence falls almost entirely on the teams downstream: analysts reverse-engineering column meanings from old Slack threads, ML engineers guessing at grain, executives squinting at dashboards quietly compromised by an undocumented default.

We're not alone in calling this out. Scroll through what the rest of the industry has been writing about it:

Worth a read

BCG XSolving the Data Context Problem for Development Teams AtlanContext Engineering for AI Analysts: Why It's Essential ColrowsKnowledge Drift and Semantic Decay: The New Technical Debt DatabytegoThe Death of the Static Data Catalog ER/StudioWhy Data Models Are the Only Documentation That Lasts kargin-utkinHow Meta Built 50 AI Agents to Map Tribal Knowledge Across Its Data Pipelines PromethiumAI's Achilles' Heel: Why Data Context Is the Key to Trustworthy Insights DataHubAI Documentation & Context Propagation tianpan.coYour RAG Knows the Docs. It Doesn't Know What Your Engineers Know.BCG XSolving the Data Context Problem for Development Teams AtlanContext Engineering for AI Analysts: Why It's Essential ColrowsKnowledge Drift and Semantic Decay: The New Technical Debt DatabytegoThe Death of the Static Data Catalog ER/StudioWhy Data Models Are the Only Documentation That Lasts kargin-utkinHow Meta Built 50 AI Agents to Map Tribal Knowledge Across Its Data Pipelines PromethiumAI's Achilles' Heel: Why Data Context Is the Key to Trustworthy Insights DataHubAI Documentation & Context Propagation tianpan.coYour RAG Knows the Docs. It Doesn't Know What Your Engineers Know.