Your first table contract

By now you have structure, keys, cleaning, and exports. What still fails teams is memory: six months later nobody remembers what a row means, who owns the metric, or which exclusions apply. A table contract is a one-page agreement that keeps the table usable when the original author is offline.

This is Part 6, the capstone of From spreadsheets to real data.

What you’ll learn

Example:

Contract fields

What belongs in a one-page table contract
How contracts prevent liability from Part 1
A fill-in template you can paste into _meta
When to promote a sheet table into a warehouse table

Fill these once; update when definitions change.

A contract is not bureaucracy

Example:

Table contract snippet

It is a pre-answered FAQ. Consumers stop pinging you for the same definitions. Producers stop inventing meanings under pressure. Auditors stop assuming malice when numbers move because a filter changed.

Minimum fields

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

Template you can paste

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

Grain: one row per order_id. Key: order_id. Owner: Ops analytics. Exclusions: test accounts, voided drafts. Do not use for audited revenue. That short block prevents Finance from treating an ops operational extract as the ledger.

Contracts and liability

Part 1’s liability ladder steepens when definitions live only in chat history. A contract is how you climb down: not by forbidding sheets, but by making multiplayer rules explicit.

When to leave the sheet entirely

If multiple teams depend on the table, refreshes are frequent, and mistakes are expensive, promote the contract into a warehouse table with tests. The contract text still matters; it becomes the beginning of proper data documentation.

Practice this week

Write a contract for your most argued-about tab.
Review it with one consumer; fix mismatches.
Link the contract from the sheet _meta tab.
Schedule a quarterly “definition checkup” 15-minute meeting.

Series recap

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

Contracts as conversation starters

A table contract is most valuable when two teams disagree. Open the page before the debate. If the contract is silent on the disputed exclusion, update the contract with an agreed rule and a date. If one team needs a different definition, that is often a second table, not a silent filter on the first.

Keep ownership human. “Data team” is not an owner. A named person or role that can answer Slack is an owner. Stewards can rotate; ownership should not be a ghost town. When someone leaves, reassign contracts like you reassign production systems.

Link contracts from dashboards. A chart without a path to grain and exclusions trains consumers to treat pixels as scripture. A small “definition” link under a KPI is a cultural intervention disguised as UI.

From sheet contract to warehouse contract

The same fields scale. In a warehouse you may add freshness SLAs, quality tests, and lineage. Do not wait for perfect tooling to write the basics. A one-page contract in the sheet today becomes the seed of dbt docs or a data catalog entry tomorrow.

If a table is used in money, compliance, or external reporting, require a contract before the table is considered production. That sounds strict until you price a single wrong board number against fifteen minutes of writing.

Closing the spreadsheets path

You now have a full arc: spot liability, structure tables, use keys, clean on purpose, export boringly, and write contracts. None of that forbids spreadsheets. It forbids pretending multiplayer chaos is agility. When you outgrow the grid, take these habits with you into SQL and Python. The tool changes; the need for grain, ownership, and honesty does not.

Revisit Part 1 when a new “quick sheet” starts winning fans. Popularity is the first step on the ladder. Meet it with a canonical 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, grain, filters, and who changed a file without telling anyone. Spreadsheet discipline exists to make those arguments shorter and rarer. When you invest in keys, cleaning, and contracts, you are investing in fewer emergency meetings and more decisions that stay decided.

A useful test for any process is vacation resilience. If the owner disappears for two weeks, can someone else reproduce the number from written rules and a canonical file? If the answer depends on a private brain, you have a single point of failure wearing a friendly grid. Document 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 transfer. Grain statements transfer. Ownership transfers. Hopeful name matching does not transfer; it just fails in a new syntax. Build habits that survive the next platform pitch from a vendor or a well-meaning executive.

Stakeholders often reward speed visibly and quality invisibly. Your job includes making quality visible: row counts, as-of times, exclusion lists, and links to definitions. When quality is visible, it can be valued. When it is invisible, it is treated as optional polish and then blamed when something breaks in public.

None of this requires perfectionism. It requires floors. A floor for structure. A floor for identity. A floor for cleanliness. A floor for handoff. A floor for memory. Below those floors, analysis becomes theater. Above them, even simple tools can support serious work until you truly need heavier infrastructure.

If you teach only one sentence from this series to a new hire, teach this: say what one row means before you sum anything. That single habit prevents a shocking share of wrong totals, broken joins, and confident nonsense in slides that look expensive.

Resistance is normal. People like the freedom of freeform cells. Freedom without shared rules becomes chaos for the next person. Frame structure as empathy for teammates and future you, not as bureaucracy for its own sake. Empathy scales better than heroics.

One more pass on judgment calls

Quick recap

A table contract records grain, keys, ownership, freshness, columns, exclusions, and allowed use on one page. It turns tribal knowledge into a shared asset. Use it for serious sheets now; reuse it when you graduate tables into SQL and warehouses.

You finished the core path of From spreadsheets to real data. Continue into the SQL series or Python when you want computation beyond the grid. Foundations still apply: define the decision before you worship the table.

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 contracts short or they die

If the document needs a committee and a wiki tree, people will not update it. One page. Visible. Linked from the data. Updated when definitions change, with a date stamp. Perfect prose is optional. Current truth is not.

When a dispute appears, open the contract before opening feelings. If the contract is wrong, fix the contract, then the numbers. That order keeps culture sane.