Skip to content

Data Dictionary

beta  ·  Family governance-docs  ·  Phase undefined  ·  Sizes lean, full  ·  ~3,700 tokens

The standing reference that documents what the fields of a dataset or table mean - each one’s name, type, allowed values, and unit - so that different teams compute the same number from them. Distinct from the tracking plan, which specifies the events and properties a product emits, and from the KPI dashboard’s own Metric Definitions section, which locks one dashboard’s metric formulas rather than a field’s meaning.

Fast reference for using the data-dictionary bundle. For the full reasoning, origins, and sources, read data-dictionary_companion.md.

  • A dataset or table already exists, or is about to, and more than one team reads from it: each team needs to compute the same number from the same field, and the honest answer to “what does this column mean” today is “ask the person who built it.”
  • The schema will change over time. This is a standing reference, revised as the schema changes, not a one-time record filed once and archived; a field you add, redefine, or stop using gets a row here before or as part of that same change.
  • A field carries a value a reader could misread without help: a coded value, a unit, a missing or sentinel code, or a flag that the field holds personal or restricted data.
  • Your organization already keeps a similar document under the name codebook. Some research-data guides treat the two names as one document and others separate them, so check which yours is. If they are the same document, name which word your team actually uses rather than maintaining both under different headings.
  • The question is what events a product emits, and why. That is the tracking plan’s job: it specifies the events and properties a product intends to track, drawn on subject rather than on which document is written first. Several product-analytics vendors use this bundle’s own name, “data dictionary,” for that event-and-property catalog; a reader who means the event list wants the tracking plan, not this document.
  • The question is a metric’s own formula, inclusions, or exclusions. That is the KPI dashboard’s own Metric Definitions section. This bundle documents what a field means; it does not lock what a derived metric computes from that field. This is this library’s own position, held against three sources that place calculation logic inside a data dictionary, not a settled reading every source shares.
  • The question is an approved vocabulary of business terms, or an inventory of every data asset in the organization. Those are a business glossary and a data catalog, two related, named artifacts this library does not build. Naming them here is only to keep their jobs out of this one.
  • The question is a risk, an open item, a resolved issue, or a change to an agreed baseline. Those belong in the risk register, the RAID log, the issue log, or the change log. Nothing in this bundle’s research connects a field’s meaning to any of those four subjects.
  • The data has not landed anywhere yet, and nothing has been built to read it. A data dictionary documents a field once it exists; a team with nothing to describe yet wants the tracking plan, which specifies what will be emitted before it lands.

Data dictionary, or one of its three neighbors?

Section titled “Data dictionary, or one of its three neighbors?”
Data dictionary Tracking plan KPI dashboard’s Metric Definitions
Tense Documents a field once it exists Specifies events before, or as, they are emitted Locks a metric already defined elsewhere
Scope What a field means, its type, its allowed values, its owner Events, properties, and traits a product emits One metric’s formula, inclusions, exclusions, owner, and steward
Drawn on Subject: what a field means versus what a product emits Subject, not tense: this library’s own reasoning differs from a tense-based line an older companion still carries This library’s own position against three sources that place formula logic inside a dictionary

A business glossary and a data catalog are not a fourth neighbor on this table: this bundle builds neither, and names both only so a reader reaching for glossary or catalog language does not fold a different document’s job into this one.

  • Lean (default): Purpose and Boundary, Field Definitions, Ownership and Review. A single table’s grain, its field-level facts, and a named owner with a review trigger, and nothing else. This matches the shape every research-data source in this bundle’s research ships for one dataset: no relationships section, no separate validation table, and no formal sign-off chain.
  • Full: adds Dataset Metadata (source system, version, effective date, refresh cadence, and primary consumers, ahead of the field table), Relationships (how this table’s fields join to other tables), Validation Rules (enum lists, ranges, and cross-field checks stated separately from the field table’s own allowed-values cells), and Review and Sign-off (a dated approval chain and the running version history, including each field’s own deprecation). This matches a vendor’s own fuller shipped template. Move to full once you have several related tables whose joins need stating somewhere, a dataset several teams rely on, or one that feeds a regulated report.

Grow lean into full by inserting Dataset Metadata before Field Definitions, inserting Relationships and Validation Rules after Field Definitions and before Ownership and Review, and appending Review and Sign-off last; the three lean sections keep their name, order, and table. No source read for this bundle states a rule for when a team should make that move; the match between the lean and full shapes and what each group of sources actually ships is this library’s own observation, not a sizing threshold any source states, and the choice is left to the author.

A team already keeping field descriptions in a documentation-as-code tool, beside the model that produces them, may use either variant as a parallel, hand-read document, or may use neither and keep the same content in the tool instead; this bundle does not resolve that choice.

Score each row 0, 1, or 2. Below 13 out of 18, a reader who joins this table to another, hits a missing value, or needs to know who to ask will have to go find that person instead of reading the document, which is the staleness and ownership failure this bundle’s research describes most fully. A lean dictionary carries no Dataset Metadata, Relationships, Validation Rules, or Review and Sign-off section to grade, so it is scored, and cleared, against a smaller table; see the scope table below.

# Criterion 0 1 2
1 Boundary rules out neighbors No line says what this document does not cover A boundary line exists, but it names no specific neighboring document You can point at the sentence naming at least one neighbor by name (the tracking plan’s event list, or the KPI dashboard’s metric formula) and at where that content actually lives instead
2 Grain and key A field table appears with no grain line above it A grain line exists, but it names no key column, or names a table with no grain line of its own For every table this document covers, you can point at its own grain line and the key column or columns that enforce it, stated before any field is listed
3 Non-circular definitions A definition restates the field’s own name, or the cell is blank Definitions are present, but at least one is circular, or one field’s name is left to speak for itself with no definition at all You can point at any field’s Definition cell and state back what the value means in one plain sentence, without reading the column name out loud
4 Missing and deprecated values A field’s missing or sentinel code is unstated, or a retired field has simply disappeared from the table Missing values are named, but at least one sentinel code is undocumented, or a deprecated field is marked with no replacement or removal date You can point at the exact code that marks a value missing or a sentinel, and at a deprecated field’s own replacement and removal date, for every field that carries one
5 Owner and review trigger A table has no named owner, or the owner is a department label such as “the data team” with no steward named An owner and a review interval are named, but nothing states whether a schema change itself also triggers a review You can point at a named owner, either a person or the specific team that produces the data, a named person as steward, a named interval, and a statement that every schema change triggers a review in addition to that interval
6 Dataset metadata complete (full) The source system, version, or effective date is missing The source system, version, and effective date are present, but the refresh cadence or the primary consumers are missing You can point at the source system, version, effective date, refresh cadence, and primary consumers, all stated before the field table starts
7 Exact relationship fields (full) A relationship names only the two table names, with no field on either side A relationship names one field, but not the field it points to, or leaves the relationship’s kind (foreign key, join, or derived) unstated You can point at the exact field on each side of a stated relationship and the kind of relationship it is, not only the two table names
8 Testable validation rules A validation row states no rule, or restates a field’s own allowed-values cell with nothing added Rules exist, but at least one is too general for a loader to run against (“should be correct”) You can point at a validation row stated specifically enough that a loader could run it against a real row and get a pass or fail
9 Sign-off and history (full) No reviewer or approver is named for the current version A sign-off is present, but the version history has a row naming no field, no approver, or no date You can point at the current version’s preparer, reviewer, and approver, and at a version-history row naming the field affected, what changed, who approved it, and when
Variant Rows scored Maximum Threshold
lean 1-5 10 7
full 1-9 18 13

Lean ships no Dataset Metadata, Relationships, Validation Rules, or Review and Sign-off section, so rows 6 through 9 grade content it does not carry; score a lean dictionary against rows 1 through 5 only. A lean dictionary at 7 out of 10 clears a comparable bar to a full dictionary at 13 out of 18.

  1. It goes stale. The most fully sourced failure mode in this bundle’s research: a dictionary written once and never reopened drifts from the schema it describes, and a reader trusts a definition that no longer matches the column. Fix: update the affected row as part of the same change that touches the schema, not as a separate task someone may skip, plus a standing calendar review besides.
  2. A header list standing in for a dictionary. A tab of column names with no Definition cell filled in is not a data dictionary; it is a list of the names a reader already had. Fix: no field ships without a plain-language sentence in its Definition cell, even a short one.
  3. A circular or cryptic definition. A definition that only restates the field’s own name (“carrier_code: the carrier code”), or an abbreviated name such as stat_cd with no definition at all, leaves a reader to guess what the value means, and a wrong guess goes straight into a query. Fix: write the definition in genus-differentia form, “A is a B that C,” and never let a field’s own name serve as its definition.
  4. The grain left unstated. A field table with no grain line forces a reader to infer what one row represents, which is a named source’s own candidate for the most common cause of double-counted metrics, stated here as that source’s own claim rather than a measured rate. Fix: one grain line, naming the key column or columns that enforce it, before any field is listed.
  5. A missing or sentinel value left undocumented. A null, a sentinel code, or a deprecated field marked only by quietly vanishing from the table leaves a reader unable to tell a missing value from a real zero, or a retired field from one still safe to query. Fix: state the exact missing or sentinel code in the Allowed values cell, and mark a retired field obsolete with its replacement and removal date rather than deleting its row.
  6. A metric’s formula, or an event’s own business reason, creeping into this document. Once a derived metric’s calculation, or an event’s own “why we track it,” starts living in a Field Definitions row, this document stops being a single source of truth for field meaning and starts duplicating the KPI dashboard or the tracking plan. Fix: route a metric’s formula to the KPI dashboard’s Metric Definitions section and an event’s own business reason to the tracking plan, and name the field this document actually documents instead.
  7. Ownership with no one to ask, and no review trigger beyond “periodically.” “Reviewed periodically by the data team” gives a reader no person to ask and no way to tell whether the table is actually current or merely was current once. Fix: one named owner, either a person or the specific team that produces the data, one named person as steward, and a stated review interval that names whether it is borrowed from elsewhere or the team’s own choice, in addition to the schema-change trigger.
  8. A known caveat left for a reader to discover the hard way. A field whose value excludes something its name does not advertise, such as a total that quietly excludes refunds, and that caveat is left unstated, lets a reader build a wrong number with full confidence. Fix: state the caveat in the field’s own Definition cell, where a reader actually meets the field, rather than leaving it to be rediscovered.

This bundle’s family contract states plainly that no governance skill exists in pm-skills today for any of its members, so every member adopts pairs_with: [] until one does. Until a governance-side skill exists, this template is filled by hand.

data-dictionary_template-lean.md · ~3,700 tokens

---
title: "{{dataset_name}} Data Dictionary"
dataset: "{{dataset_name}}"
owner: "{{owner}}"
steward: "{{steward}}"
dictionary_version: "{{dictionary_version}}"
last_reviewed: "{{date}}"
status: "{{status}}"
doc_type: data-dictionary
size: lean
source_template: data-dictionary
source_template_version: 0.1.0
---
<!--
LEAN DATA DICTIONARY. The smallest data dictionary that is still a real one: what it covers and the two
neighboring documents it rules out, the load-bearing field table itself, and the table's own named owner
with a stated review trigger. Use it for a single small table, matching the shape the research-data
sources themselves ship: no relationships section, no separate validation table, and no formal sign-off
chain. To grow it into the full form (see data-dictionary_template-full.md), ADD sections; never rename or
reorder the ones below, because the full variant is a strict superset of this one.
WHAT A DATA DICTIONARY IS. CASRAI states the job in full: "A data dictionary is a structured document,
table, or file that defines every variable in a dataset - its name, meaning, data type, unit of
measurement, allowed values, and any coding scheme used to represent those values - so that anyone other
than the person who collected the data can interpret it correctly." OSF puts the same job more plainly:
"The purpose of a data dictionary is to explain what all the variable names and values in your spreadsheet
really mean." It is a standing reference, revised as the schema changes, not a one-time record filed once
and archived. In research settings this same document is often called a codebook; sources disagree on
which name is the narrower one, and this template does not rank the two. See data-dictionary_companion.md
section 1 and section 6, item 3.
IT IS NOT THE EVENT LIST, AND IT DOES NOT LOCK A METRIC'S FORMULA. Product-analytics vendors use this
template's own name for a catalog of a product's events and their properties; Mixpanel's own Lexicon page
states, "Lexicon is a data dictionary that stores descriptions of events and their properties." That
document is the tracking plan's job, drawn on subject rather than on which document is written first: a
tracking plan specifies the events and properties a product emits, and this document describes what the
fields of a dataset or table mean once those events and properties land somewhere. Separately, this
document does not lock a derived metric's own formula, inclusions, or exclusions; that is the KPI
dashboard's own Metric Definitions section. This second boundary is this library's own position against
three sources that place calculation logic inside a data dictionary, not a settled reading every source
shares. See data-dictionary_companion.md section 1, section 3 (Purpose and Boundary), section 6 (items 1,
2, and 8), and section 8.
NO SOURCE READ FOR THIS BUNDLE MEASURED WHETHER HAVING ONE CHANGES AN OUTCOME. What exists is one
qualitative case study of a clinical-research project that lacked one, reporting that the absence "created
the possibility for new study staff to misinterpret the data," and one datathon event abstract that names
incomplete data dictionaries among several reproduction challenges while every team still reproduced the
trial's results. Neither is a measured effect, and this template's reason to exist rests on named failure
modes, not on a measurement. See data-dictionary_companion.md section 1 and section 7.
HOW TO FILL THIS IN
1. Read the comment under each heading: WHAT, WHY (with a companion pointer), ASK, GOOD, WEAK, TRAP; the
one table section also carries PRIORITY and ROW HINT.
2. Replace each {{placeholder}}. The Field Definitions table is the heart; every table it covers opens with
one line stating its grain and the key column or columns that enforce it, before any field is listed.
Repeat the grain line and the table once per table this document covers.
3. If a section does not apply, write "N/A" and one line of why, rather than deleting it.
4. This document is never finished, but before you share it: self-grade against data-dictionary_guide.md,
then DELETE every HTML comment. They are guidance, not content.
-->
# {{dataset_name}} Data Dictionary
## Purpose and Boundary
<!-- WHAT A short statement of which dataset's or table's fields this document covers, and what it rules
out by name.
WHY The name this document carries is overloaded, so the first job of this section is to rule the
other senses out before the field table starts. It excludes event cataloguing: Mixpanel's own
Lexicon page states, "Lexicon is a data dictionary that stores descriptions of events and their
properties," using this document's own name for a different document; that subject is the
tracking plan's job, and a reader who means the event list is routed there. It excludes
metric-formula locking: Basedash separates "The metrics layer on top of tables" from the
field-level facts a dictionary carries, and dbt's own Semantic Layer exists specifically to
"centrally define business metrics" apart from the tools that consume them; that subject is the
KPI dashboard's own Metric Definitions section. The section also names codebook as the common
synonym this type carries in research settings, without ranking the two terms against each
other. Deep dive: data-dictionary_companion.md section 3 (Purpose and Boundary) and section 6
(items 1, 2, 3, and 8).
ASK Which dataset or table, or which several related tables, does this document cover? What does it
rule out by name: the event list another team already catalogs, and any metric's own formula?
If your organization calls a document like this a codebook, does this template serve that job
too, or does your team keep both under different names?
GOOD "This document covers the shipments and warehouses tables in Cedarbrook Fulfillment's
operational warehouse. It does not catalog the events Cedarbrook's driver app emits; that
catalog is the tracking plan's job. It does not lock the formula behind On-Time Delivery Rate;
that formula lives in the KPI dashboard's own Metric Definitions section. Some teams at
Cedarbrook call a document like this one a codebook; this one serves that job too."
WEAK "This describes our data." (names no table, rules out nothing, and a reader cannot tell this
document from a business glossary or the tracking plan)
TRAP Letting a metric's formula, or an event's own trigger and business reason, creep into this
document instead of staying in the KPI dashboard or the tracking plan, where each already
belongs. -->
{{purpose_and_boundary}}
## Field Definitions
<!-- WHAT One row per field, naming its type and nullability, its meaning, its allowed values, its source,
its sensitivity, and its owner. Repeat the grain line and the table once per table this document
covers.
WHY This is the section every admitting source converges on, and the one a reader actually opens
the document to find. Each table's entry opens with one line stating its grain, what one row
represents, and the key that enforces it, following the dimensional-modeling rule that "The
grain of a fact table states what 1 row means, and it is decided before any column is added,"
and that "Naming the columns that enforce the unit is what lets another engineer write a test
against it." Below the grain line, the columns are this library's own convergence across several
sources, not any single vendor's whole list: Field, the technical column name; Type and
nullability, paired the way Basedash pairs them, "Data type and nullability"; Definition, a
plain-language sentence of what the value means, following OSF's "Definition of the variable"
and CASRAI's "What does it measure or record?"; Allowed values, units and missing codes, sourced
to the University of North Carolina's "including null or missing values," CASRAI's "How is
missingness represented?," OSF's "Measurement units," and Basedash's "Enums, ranges, or units";
Source, including how often it refreshes, sourced to CASRAI's "Where did this variable come
from?" and Basedash's "Where the value originates"; Sensitivity, sourced to Basedash's "PII or
restricted-data flag" and Avo's own property field, "The PII status of the property - whether it
carries personally identifiable information"; and Owner, a person or team accountable for the
field, sourced to Basedash's own "Person or team accountable for it." A missing or sentinel
value is documented, not assumed: the DDI Alliance's own metadata model states, "Sentinel values
are used for processing, not to describe subject matter." A field the schema has stopped using
stays in the table rather than disappearing from it, with its replacement and removal date
recorded in its own Definition cell, following the Open Contracting Data Standard's own
deprecation rule, "Validation tools must report use of deprecated fields to the user," and the
NIMH Data Archive's own practice of marking an entry "obsolete, superseded by newer structures"
rather than deleting it. Deep dive: data-dictionary_companion.md section 3 (Field Definitions)
and section 6, item 2.
ASK For each table: what is its grain, in one sentence, and what key column or columns enforce it?
For each field: what is its name? Its type, and is it nullable? What does its value mean, in one
plain sentence? What values, units, or missing codes are allowed? Where does it come from, and
how current is it? Does it carry a sensitivity flag? Who is accountable for it?
PRIORITY Every table opens with a stated grain and key before any field is listed. A good definition
follows a genus-differentia form, "A is a B that C"; a circular definition, naming the thing by
itself, or a cryptic column name with no definition at all, fails this section outright.
ROW HINT A good row names the value's meaning in one plain sentence and states any known caveat in
the same cell, such as an exclusion the column's name does not advertise. A weak row restates
the column's own name as though that were a definition, or leaves the allowed-values cell blank.
GOOD Grain line: "Table: shipments. Grain: one row per shipment. Key: shipment_id enforces the
grain." Row: | carrier_code | string, not null | The carrier that physically moved the shipment
out of the warehouse; set once at dispatch and never changed afterward | Enum: ups, fedex, dhl,
usps | Set by Fulfillment Core at dispatch | none | Fulfillment Eng |
WEAK Grain line: none stated. Row: | carrier_code | string | The carrier | | | | |
TRAP Writing a definition that only restates the column's own name ("carrier_code: the carrier
code"), which CASRAI names directly as the failure this section exists to avoid: a tab of column
headers with no definitions "is not a data dictionary under this definition - it is a header
list." -->
**Table:** {{table_name}}
**Grain:** {{grain_statement}}
**Key column(s):** {{key_columns}}
| Field | Type and nullability | Definition | Allowed values, units, or missing codes | Source | Sensitivity | Owner |
|---|---|---|---|---|---|---|
| {{field_name}} | {{field_type_nullability}} | {{field_definition}} | {{field_allowed_values}} | {{field_source}} | {{field_sensitivity}} | {{field_owner}} |
## Ownership and Review
<!-- WHAT The table's own named owner and steward, apart from any individual field's own owner, and how
the table is reviewed.
WHY An unowned, unreviewed dictionary is the staleness failure this bundle's own research names most
often, and this section is where that failure is prevented. Basedash states the ownership
default plainly, "Owners are usually the team that produces the data, not the team that consumes
it." Docsie's own template asks the author to "Identify data owner, steward, support channel,
and review cadence." No fixed interval is a norm across the sources: Docsie offers a choice
rather than one answer, Wizbrand says monthly or quarterly, Basedash ties review to every schema
change plus a short quarterly check, and Atlan ties review frequency to change velocity. This
section asks the author to name an interval and to say whether it is borrowed or the team's own.
The review trigger itself has two parts the sources agree on even where the interval disagrees:
Basedash ties the first trigger directly to the change itself, "Update definitions whenever the
schema changes, as part of the change itself rather than as a separate task," and Atlan states
the second as a rule, "Review frequency depends on change velocity." Deep dive:
data-dictionary_companion.md section 3 (Ownership and Review) and section 6, items 6 and 9.
ASK Who is this table's own named owner, apart from any individual field's own owner? Who is its
steward? What is the support channel or process for proposing a change to a definition? What
triggers a review, besides every schema change: what calendar interval, and is that interval
borrowed from somewhere else or this team's own choice?
GOOD "Owned by Fulfillment Eng, the team that produces this data; stewarded by Priya Okafor. Propose
a change in the #fulfillment-data channel. Reviewed on every schema change, plus a standing
quarterly check; this quarterly interval is this team's own choice, not a sourced norm."
WEAK "Reviewed periodically by the data team." (no named owner, no steward, no interval, and nothing
a reader could check the table against)
TRAP Naming an owner but no review trigger beyond "periodically," which leaves a reader with no way
to tell whether the table is actually current or merely was current once. -->
**Table owner:** {{table_owner}}
**Table steward:** {{table_steward}}
**How to propose a change:** {{change_proposal_process}}
**Review interval:** {{review_interval}}
**Other review triggers:** {{review_triggers}}

The reasoning, the history and every source, in the repository:

  • Companion - the long-form argument: why these sections, where the sources disagree, and what the bundle refuses to claim
  • History - what changed in this bundle, and when
  • Research log - every source consulted, with what each one actually supports
  • Catalog metadata - the machine-readable record this page is generated from

Catalog record: 7 sections across 1 format(s), methodology methodology-agnostic, typically owned by Data / Analytics Eng.