Catalogs and where is the truth?

You ask three people where the “official” customer table lives. You get four answers, two Slack threads, and a spreadsheet named customers_FINAL_v7_use_this.xlsx. Someone points at a BI dataset. Someone else swears the CRM is the only truth. Engineering says “the warehouse mart,” then admits the mart is three weeks behind a hotfix that never got a ticket.

This is not a tooling failure first. It is a documentation failure with tooling as the costume. Catalogs exist to answer “where is the truth?” in under two minutes. They fail when they become museums: every table tagged, no human maintained, nobody trusts the badges.

This is Part 2 of Data stewardship at work. Part 1 covered steward, owner, and custodian. Here we build a lightweight truth map and a minimum catalog card you can keep honest without writing a 200-page wiki. Program-layer data governance and MDM still matter. This post is about weekly documentation habits that make those programs usable.

What you’ll learn

• What “system of record,” “curated analytics,” and “serving product” mean when people say “source of truth”
• How to draw a one-page truth map for a domain without boiling the ocean
• A minimum catalog card (fields that actually get filled)
• When a wiki page, a catalog tool, or a README in the repo is the right home
• Common catalog theater patterns and a 45-minute practice drill

“Source of truth” is three different sentences

People use one phrase for three jobs. Split them and arguments get shorter.

• System of record: where the business event is created and corrected in operational life. The CRM for opportunity stage. The orders database for checkout. The HRIS for employment status.
• Curated analytics truth: the table or model designed for analysis at a defined grain, with tested transforms, documented exclusions, and a steward. This is where most “dashboard truth” should live.
• Serving product: the BI dataset, reverse-ETL sync, API, or export that consumers actually hit. It should point at curated truth, not invent a fourth definition.

If Finance says “truth is NetSuite” and Growth says “truth is the revenue dashboard,” they may both be right for different sentences. NetSuite can be system of record for invoices. The certified warehouse model can be curated analytics truth for weekly net revenue. The Looker explore can be the serving product. Your job as steward is to map the chain, not to declare one winner by volume of email.

This sits on the path from the data pipelines series: sources → land → transform → serve. Catalogs are how you label which object is certified at which stage, and which is raw scrap you should not join into board metrics.

The truth map (one page, not a novel)

A truth map is a domain sketch: systems of record on the left, landing and raw zones next, curated models in the middle, serving products on the right. Annotate owners and stewards. Mark certified vs experimental. You are not diagramming every column. You are preventing the “which customers table?” tax.

How to build one without a week-long workshop:

1. Pick one domain (orders, customers, support tickets).
2. List the systems that create events (max five to start).
3. List the curated tables or models people should use for decisions (max five).
4. List the serving products that read them (dashboards, extracts, apps).
5. Draw arrows only for official paths. Put “do not use for X” notes on the dangerous clones.
6. Attach owner and steward names from Part 1.

If a path is unofficial but heavily used, draw it as a dashed risk, not as certified. Shadow truth is still truth in practice until you replace it. Pretending it does not exist only hides load on the wrong tables.

Document without a 200-page wiki

Wikis die when every field is mandatory and nobody has time. Catalogs die the same way. Aim for minimum honest documentation: enough that a competent new hire does not ship a wrong join, not enough that updating the page takes longer than fixing the bug.

What “minimum” means

For a certified dataset, you need answers to:

• What is one row?
• What is the system of record upstream?
• Who is owner and steward?
• What must consumers never do with this table?
• How fresh is it, and what do we do when freshness fails?
• Where is the definition of key metrics that read it?

Column-level docs can wait for the columns people actually join on. Full data dictionaries are great when automated from code. Hand-written dictionaries for 400 columns go stale by Thursday.

Where the words should live

Pick a primary home per asset type. Secondary homes should link, not copy-paste long definitions that will diverge. The metrics series already pushes written specs for KPIs. Catalog cards should point at those specs, not invent a second formula in a description field.

The minimum catalog card

Here is a card format you can paste into a catalog UI, a YAML file, or a wiki template. Fill one certified dataset this week. Ignore everything else until this one is honest.

Field checklist in table form:

A machine-readable sketch (adapt to your catalog API or dbt meta):

# catalog_card.weekly_order_facts.yaml
id: analytics.certified.weekly_order_facts
status: certified
grain: "one row per order_id per week_end_date"
system_of_record:
  system: checkout_db
  object: public.orders
owner: finance_analytics_lead
steward: orders_domain_analyst
custodian_oncall: platform_data_eng
consumers:
  - exec_weekly_pack
  - growth_weekly_review
freshness:
  slo: "Monday 08:00 America/New_York"
  check: job_success_and_max_week_end_date
sensitivity:
  pii: false
  notes: "customer_id is hashed; no email or phone"
do_not_use_for:
  - real_time_fraud
  - incomplete_current_week_as_final
definitions:
  weekly_net_revenue: "https://wiki.example/metrics/weekly-net-revenue"
quality:
  suite: "tests/weekly_order_facts.yml"
  scorecard: "https://wiki.example/quality/orders"
last_reviewed: "2026-03-01"
reviewed_by: orders_domain_analyst

Notice what is missing: 80 free-text paragraphs about company history. History can live in a linked ADR (architecture decision record). The card stays scannable.

Certification is a promise, not a sticker

“Certified” only means something if you can revoke it. Pair status with habits from the data quality series: dimensions, automated checks, and a scorecard someone actually reads. If freshness fails three Mondays in a row and status stays Certified, consumers learn to ignore badges.

A simple status ladder:

• Experimental: may break; no board use; owner optional, steward required.
• Certified: documented grain, owner, steward, checks, freshness SLO, consumer list.
• Deprecated: still readable for history, blocked for new builds, sunset date set.

Deprecation without a replacement path creates shadow clones. When you deprecate, name the successor on the card and in the serving product description the same week.

Worked example: orders domain mini catalog

Imagine a mid-size company. Checkout DB is system of record. Raw land is raw.checkout_orders. Curated truth is analytics.certified.weekly_order_facts. Serving products: a Finance dashboard and a Growth spreadsheet extract that should die but has not. Support also keeps a personal CSV of “VIP customers” that must never be treated as certified.

Truth map notes you would write on the diagram:

• CRM account names are not the system of record for order amounts.
• The Growth extract must lag the certified table by design, or it will invent its own week boundaries.
• VIP CSV is explicitly uncertified; access to PII may still need controls (Part 3).

Sample “do not use” rules worth putting on the certified card:

-- Example guardrail comment in a BI-facing view
-- Certified grain: one row per order_id x week_end_date
-- Do NOT join to raw.checkout_orders for board metrics
-- Do NOT filter week_end_date = CURRENT_DATE for "final" weekly revenue
-- Definition: wiki/metrics/weekly-net-revenue
CREATE VIEW analytics.certified.v_weekly_order_facts AS
SELECT *
FROM analytics.certified.weekly_order_facts;

Comments are not a catalog. They help. The catalog card is still the search entry for people who never open SQL.

Lineage: enough to debug, not enough to impress

Automated lineage is wonderful when it works. Manual lineage for three hops (source → curated → serve) is enough for many incidents. Capture:

• Upstream object name
• Job or model name that builds the curated table
• Downstream dashboards or extracts

If your catalog auto-harvests, still verify the certified edges by hand once a quarter. Tools mis-label temporary tables as beloved. Stewards confirm which edges matter for decisions.

When MDM and clean rooms show up

Master data management programs often own the golden customer or product record. Your analytics catalog should say whether a customer dimension is MDM-fed or CRM-direct. Do not quietly rebuild a second golden customer in the warehouse without linking to the program decision.

Clean rooms are a different serving pattern: multi-party measurement with constrained identifiers. Document them as serving products with strict do-not-use rules, not as general-purpose customer tables. If someone asks “is the clean room the customer truth?”, the answer is usually “no, it is a constrained collaboration surface.”

Common mistakes

• Catalog everything in month one: you get empty fields and cynicism. Start with certified assets only.
• Status without teeth: Certified forever, no review date, no checks.
• Duplicate definitions: metric formula in catalog, wiki, and Slack canvas, all slightly different.
• Ignoring serving products: documenting only warehouse tables while executives live in a spreadsheet extract.
• No owner or steward names: a card without humans is a brochure.
• Confusing system of record with curated truth: forcing dashboards to query production OLTP “because truth.”
• Wiki novels: 200 pages nobody updates. Prefer short cards plus links to code and metric specs.

Practice: 45 minutes this week

Choose one certified (or should-be-certified) dataset. Draw the three-column truth map on a whiteboard photo. Fill the minimum catalog card fields, including “do not use for” and last reviewed. Put the card where people already search (catalog tool or wiki). Send one message: “If you use another table for this decision, reply with why.” Collect shadow paths without shaming; schedule deprecation or documentation next.

Part 3 covers access, least privilege, and the eternal “just give me prod” request. A catalog without access rules becomes a treasure map for the wrong adventure. For more structured learning paths, see Learn.

Quick recap

• Split system of record, curated analytics truth, and serving product.
• Draw a one-page truth map per domain with owners and stewards.
• Use a minimum catalog card: grain, status, humans, freshness, sensitivity, do-not-use, definition links.
• Document lightly, link to metric specs and quality checks, review on a date.
• Governance and MDM programs set standards; catalogs make them findable in weekly work.

Sources

• DAMA International, data governance and metadata management concepts in DMBOK: https://www.dama.org/cpages/body-of-knowledge
• DataHub (open source metadata platform docs, vendor-neutral catalog patterns): https://datahubproject.io/docs/
• OpenMetadata documentation (catalog, glossary, and data quality integration patterns): https://docs.open-metadata.org/
• dbt Docs (documentation co-located with transforms): https://docs.getdbt.com/docs/collaborate/documentation
• NIST Privacy Framework (inventory and data processing documentation as risk practice): https://www.nist.gov/privacy-framework
• ISO/IEC 11179 (metadata registries concepts, high-level background): https://www.iso.org/standard/78914.html

More definitions in Key Terms →

Merch on Etsy

Open store →

You're On Mute White Ceramic Coffee Mug, Data Science Mug, Data Mug, Analytics Mug, Statistics Mug, Programming Mug, Gift Mug, Coffee Mug View on Etsy → Boxplot Mouse Pad, Data Science Mouse Pad, Analytics Mouse Pad, Box Plot, Whisker Plot View on Etsy → Naive Bayes Mouse Pad, Data Science Mouse Pad, Analytics Mouse Pad, Bayesian Mouse Pad View on Etsy → Mute Mouse Pad, Data Science Mouse Pad, Analytics Mouse Pad, You're On Mute View on Etsy →