A table contract is a one-page note that says what a table means, who owns it, and what it must not be used for. It matters because teams rarely fail at building a spreadsheet. They fail six months later, when nobody remembers what a row stands for, who owns the metric, or which records were left out on purpose.
The contract keeps the table usable after its author has moved on or gone on vacation. It is the last step in building a spreadsheet that other people can trust. The earlier posts in this series covered the risks of shared sheets, tidy structure, keys that link tables, repeatable cleaning, and exports that other systems can read.
Say you inherit a sheet from a coworker who has changed teams. It has 4,000 rows and a total at the bottom. Nothing tells you whether canceled orders are in that total, or whether test accounts were removed. You could ask around, but the one person who knows is in a different building. A one-page contract would have answered both questions before you asked.
A contract is not bureaucracy
Think of it as a list of answers you wrote down ahead of time. People who use the table stop asking you for the same definitions again and again. People who build the table stop making up meanings under pressure. And when a number moves because someone changed a filter, reviewers can see the reason instead of suspecting that someone did something wrong.
The minimum fields
A contract needs only a handful of fields. Each one exists to head off a specific kind of confusion, and the table below pairs them. The word grain in the second row means what one row stands for, such as one order or one customer.
| Field | Why it exists |
|---|---|
| Table name | Shared vocabulary |
| Grain | Stops double-counting |
| Primary key | Identity and dedupe |
| Owner / steward | Accountability |
| Refresh cadence + as-of | Freshness |
| Column dictionary | Meaning and types |
| Exclusions | Silent filters made loud |
| Allowed use / do-not-use | Stops wrong decisions |
| Change process | How definitions evolve |
Two of these words deserve a plain explanation. The primary key is the one column, such as an order number, that identifies each row and never repeats. A steward is someone who looks after the table’s accuracy day to day, and that person can change over time even when the owner stays the same.
A template you can paste
You can copy the block below into a tab named _meta in the same file. Fill it in once, then update it whenever a definition changes.
TABLE CONTRACT
Name:
Grain (one row = ):
Primary key:
Owner:
Steward:
Source system / URL:
Refresh:
Last as-of:
Columns:
- name | type | meaning | example
Exclusions:
Joins expected:
Consumers:
Do not use for:
Change process (who approves):
Related dashboards:Worked example: weekly_orders_clean
For this table, one row is one order, and the key is order_id. The owner is the operations analytics team. Test accounts and voided drafts are left out. The table must not be used for audited revenue.
That short block prevents a common mistake. Without it, someone in finance might treat an operations extract as if it were the official ledger. With it, they can see in ten seconds that the table was built for a different job and check a different source instead.
Contracts and shared-sheet risk
The first post in this series described how the risk from a shared sheet grows as more people edit it. That risk climbs even faster when the definitions live only in chat history. A contract is how you bring it back down. You do not ban sheets. You make the rules for many people working in one file explicit and easy to find.
When to leave the sheet entirely
Some tables outgrow a spreadsheet. If several teams depend on it, it refreshes often, and a mistake would be expensive, move it into a warehouse, which is a database built for company-wide reporting, and add automated tests. The contract still matters after the move, because it becomes the starting point for proper data documentation.
Practice this week
- Write a contract for the tab people argue about most.
- Review it with one person who uses the table, and fix anything that does not match how they read it.
- Link the contract from the _meta tab of the sheet.
- Schedule a 15-minute “definition checkup” meeting every quarter.
Contracts help when two teams disagree
A table contract earns its keep when two teams read the same numbers differently. Open the page before the debate starts. If the contract says nothing about the exclusion in dispute, update it with an agreed rule and a date. If one team truly needs a different definition, that usually means a second table, not a hidden filter on the first one.
Ownership has to belong to a person. “The data team” is not an owner, but a named person or role who answers messages in Slack is. Stewards can rotate. When someone leaves the company, hand their contracts to a new owner the way you would hand over a production system.
Link each contract from the dashboards that use the table. A chart with no path back to what a row means and what was excluded teaches readers to treat pixels as scripture. A small “definition” link under a headline number is a quiet way to change how people think about the data.
From a sheet contract to a warehouse contract
The same fields still work in a warehouse. There you can add promises about how fresh the data will be, automated quality checks, and a record of where each column came from. Do not wait for perfect tooling to write the basics. A one-page contract in the sheet today can become a documentation page in a tool like dbt (software that documents and tests warehouse tables) or an entry in a data catalog tomorrow.
If a table feeds money reporting, compliance, or anything sent outside the company, require a contract before you call it production. That sounds strict until you compare fifteen minutes of writing with the cost of one wrong number in front of your board.
Where the spreadsheets path leaves you
You now have a complete set of habits: spot the risk, structure the table, use keys, clean on purpose, export plainly, and write a contract. None of this forbids spreadsheets. It only forbids pretending that many people editing freely is the same as moving fast. When you outgrow the grid, carry these habits into SQL, the standard language for asking a database for data, and into Python. The tool changes, but the need for a clear definition of a row, a named owner, and honesty about exclusions does not.
Go back to the opening post on shared-sheet risk whenever a new “quick sheet” starts winning fans. Popularity is the first step toward trouble. Respond with one official link and a contract before the copies multiply.
Putting it into daily practice
Think about the last time two dashboards disagreed. The argument was rarely about chart colors. It was about definitions, filters, and who changed a file without telling anyone. Spreadsheet discipline exists to make those arguments shorter and rarer, so investing in keys, cleaning and contracts means fewer emergency meetings and more decisions that stay decided.
A good test for any process is vacation resilience. If the owner disappears for two weeks, can someone else reproduce the number from written rules and one official file? If the answer depends on what one person remembers, you have a single point of failure dressed up as a friendly grid. Write down the boring parts while they are still small enough to remember.
Tools will keep changing: sheets today, a warehouse tomorrow, a notebook the week after. Habits carry over. A clear statement of what a row means carries over, and so does ownership. Hopeful name matching does not, because it simply fails again in a new syntax. Build habits that survive the next platform pitch from a vendor or a well-meaning executive.
Stakeholders tend to reward speed visibly and quality invisibly. Part of your job is to make quality visible with row counts, as-of times, exclusion lists and links to definitions. Visible quality can be valued. Invisible quality gets treated as optional polish, and then people blame you when something breaks in public.
None of this requires perfection. It requires a minimum standard for structure, identity, cleanliness, handoff and memory. Below that standard, analysis turns into theater. Above it, even simple tools can support serious work until you truly need heavier infrastructure.
If you teach one sentence from this series to a new hire, make it this: say what one row means before you add anything up. That habit prevents a surprising share of wrong totals, broken joins, and confident nonsense in slides that look expensive.
Expect some resistance, because people like the freedom of freeform cells. Freedom without shared rules becomes a mess for the next person who opens the file. Frame structure as kindness to your teammates and to your future self, and not as paperwork for its own sake.
Keep contracts short or they die
If the document needs a committee and a tree of wiki pages, people will stop updating it. Keep it to one page, put it where people can see it, link it from the data, and add a date whenever a definition changes. Perfect prose is optional, but current facts are not.
When a dispute appears, open the contract before you open a fight. If the contract is wrong, fix the contract first and the numbers second. That order keeps the peace.
Quick recap
A table contract records what one row means, the key, the owner, how fresh the data is, the columns, the exclusions, and the allowed uses, all on one page. It turns knowledge that lives in people’s heads into something the whole team can read. Use it for any serious sheet now, and reuse it when you move tables into SQL and warehouses.
Your next step: pick the shared sheet your team argues about most and fill in a contract for it this week, because that is where a clear definition saves the most time. From there you can keep going with the SQL series, or with Python when you want computation beyond the grid. The basics still apply: define the decision before you worship the table.
Series notes
This is Part 6, the capstone of From spreadsheets to real data. The full path, in order:
- B1 Liability: when sheets become multiplayer risk
- B2 Tables: tidy structure
- B3 Keys: join without name hope
- B4 Cleaning: repeatable hygiene
- B5 Export: boring files for serious systems
- B6 Contract: memory that outlives you
Sources
- Data documentation / data contract ideas in modern analytics engineering (e.g. dbt docs concepts of models and descriptions): https://docs.getdbt.com/docs/build/documentation
- Analytics Made Simple: this series B1-B5; Analytics foundations; SQL series
Keep going
Same lessons in your feed
Short diagrams, hooks, and weekly tutorials on Substack, Instagram, X, and Facebook.
