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.
When to use
Section titled “When to use”- 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.
When NOT to use
Section titled “When NOT to use”- 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.
Pick a variant
Section titled “Pick a variant”- 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.
Quality rubric (self-grade)
Section titled “Quality rubric (self-grade)”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 |
Rubric scope by variant
Section titled “Rubric scope by variant”| 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.
Named anti-patterns (the usual wrecks)
Section titled “Named anti-patterns (the usual wrecks)”- 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.
- 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.
- 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_cdwith 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. - 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.
- 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.
- 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.
- 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.
- 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.
No paired skill (yet)
Section titled “No paired skill (yet)”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.
The artifacts
Section titled “The artifacts”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-dictionarysize: leansource_template: data-dictionarysource_template_version: 0.1.0---
<!--LEAN DATA DICTIONARY. The smallest data dictionary that is still a real one: what it covers and the twoneighboring documents it rules out, the load-bearing field table itself, and the table's own named ownerwith a stated review trigger. Use it for a single small table, matching the shape the research-datasources themselves ship: no relationships section, no separate validation table, and no formal sign-offchain. To grow it into the full form (see data-dictionary_template-full.md), ADD sections; never rename orreorder 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 ofmeasurement, allowed values, and any coding scheme used to represent those values - so that anyone otherthan 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 spreadsheetreally mean." It is a standing reference, revised as the schema changes, not a one-time record filed onceand archived. In research settings this same document is often called a codebook; sources disagree onwhich name is the narrower one, and this template does not rank the two. See data-dictionary_companion.mdsection 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 thistemplate's own name for a catalog of a product's events and their properties; Mixpanel's own Lexicon pagestates, "Lexicon is a data dictionary that stores descriptions of events and their properties." Thatdocument is the tracking plan's job, drawn on subject rather than on which document is written first: atracking plan specifies the events and properties a product emits, and this document describes what thefields of a dataset or table mean once those events and properties land somewhere. Separately, thisdocument does not lock a derived metric's own formula, inclusions, or exclusions; that is the KPIdashboard's own Metric Definitions section. This second boundary is this library's own position againstthree sources that place calculation logic inside a data dictionary, not a settled reading every sourceshares. 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 onequalitative case study of a clinical-research project that lacked one, reporting that the absence "createdthe possibility for new study staff to misinterpret the data," and one datathon event abstract that namesincomplete data dictionaries among several reproduction challenges while every team still reproduced thetrial's results. Neither is a measured effect, and this template's reason to exist rests on named failuremodes, not on a measurement. See data-dictionary_companion.md section 1 and section 7.
HOW TO FILL THIS IN1. 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}}data-dictionary_template-full.md · ~6,050 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-dictionarysize: fullsource_template: data-dictionarysource_template_version: 0.1.0---
<!--FULL DATA DICTIONARY. Everything in the lean variant, plus a dataset-level header ahead of the field table,a place to state how a table's fields relate to other tables, a place to list cross-field and range checksseparately from the field table itself, and a formal sign-off record with a running version history. Useit for several related tables, for a dataset several teams rely on, or for one that feeds a regulatedreport, following Docsie's own fuller shipped shape: a metadata header, a relationships section, avalidation section, and a sign-off block beyond the basic owner-and-cadence fields the lean variant alreadycarries.
This is a STRICT SUPERSET of data-dictionary_template-lean.md: every lean section appears here in the samerelative order, under the same names. If you are growing from lean, insert Dataset Metadata before FieldDefinitions; insert Relationships and Validation Rules after Field Definitions and before Ownership andReview; and append Review and Sign-off last.
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 ofmeasurement, allowed values, and any coding scheme used to represent those values - so that anyone otherthan 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 spreadsheetreally mean." It is a standing reference, revised as the schema changes, not a one-time record filed onceand archived. In research settings this same document is often called a codebook; sources disagree onwhich name is the narrower one, and this template does not rank the two. See data-dictionary_companion.mdsection 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 thistemplate's own name for a catalog of a product's events and their properties; Mixpanel's own Lexicon pagestates, "Lexicon is a data dictionary that stores descriptions of events and their properties." Thatdocument is the tracking plan's job, drawn on subject rather than on which document is written first: atracking plan specifies the events and properties a product emits, and this document describes what thefields of a dataset or table mean once those events and properties land somewhere. Separately, thisdocument does not lock a derived metric's own formula, inclusions, or exclusions; that is the KPIdashboard's own Metric Definitions section. This second boundary is this library's own position againstthree sources that place calculation logic inside a data dictionary, not a settled reading every sourceshares. 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 onequalitative case study of a clinical-research project that lacked one, reporting that the absence "createdthe possibility for new study staff to misinterpret the data," and one datathon event abstract that namesincomplete data dictionaries among several reproduction challenges while every team still reproduced thetrial's results. Neither is a measured effect, and this template's reason to exist rests on named failuremodes, not on a measurement. See data-dictionary_companion.md section 1 and section 7.
HOW TO FILL THIS IN1. Read the comment under each heading: WHAT, WHY (with a companion pointer), ASK, GOOD, WEAK, TRAP; the four table sections also carry 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. Relationships and Validation Rules in particular may be "N/A, this dataset is a single table with no foreign keys and no cross-field rules beyond the allowed values already stated" for a small dataset.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}}
## Dataset Metadata
<!-- WHAT A header naming the dataset or table, its source system, its version, and its effective date, ahead of the field table. WHY A single small table needs little more than its field list, while several related tables need a header that says which system each one came from and when this version took effect. Docsie's own shipped document opens with exactly this header before its field table, asking the author to "Describe the dataset purpose, source systems, refresh cadence, and primary consumers." Basedash frames the same idea at the table level throughout, describing what a complete dictionary documents about a table beyond any single column. Deep dive: data-dictionary_companion.md section 3 (Dataset Metadata). ASK What is this dataset or table's source system? What version of this document is this, and when did it take effect? How often does the underlying data refresh? Who are its primary consumers? GOOD "Source system: Fulfillment Core, the warehouse management platform. Version 2.1, effective 2026-09-01. Refreshes nightly at 02:00 UTC. Primary consumers: the fulfillment analytics team and the carrier-performance dashboard." WEAK "This is our warehouse data." (no source system, no version, no effective date, and no consumer named) TRAP Stating a version number with no effective date, so a reader cannot tell whether a field's definition below reflects the schema as it exists today or as it existed several releases ago. -->
**Source system(s):** {{source_system}}
**Version:** {{dictionary_version}}
**Effective date:** {{effective_date}}
**Refresh cadence:** {{refresh_cadence}}
**Primary consumers:** {{primary_consumers}}
## 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}} |
## Relationships
<!-- WHAT How this table's fields relate to other tables: foreign keys, joins, or a field computed from another table's field. WHY A single table with no related tables has nothing to describe here, while several related tables need the joins stated somewhere. Docsie's own template asks the author to "Document primary keys, foreign keys, joins, and related datasets," and Harvard Medical School's own definition, "Outlines the structure, content, and variable definitions for a dataset or collection of data," reads naturally as more than one table in scope once relationships exist between them to describe. Deep dive: data-dictionary_companion.md section 3 (Relationships). ASK Which field in this table is a foreign key into another table? What table and field does it point to? Is the relationship a straightforward foreign key, a join condition, or a field this table computes from another table's own field? PRIORITY Name the exact field on each side of the relationship, not only the two table names; "joins to the warehouse table" with no field named is not a relationship statement a reviewer can test. ROW HINT A good row names both fields and the relationship's kind (foreign key, join, or derived). A weak row names only the two tables and leaves the kind and the fields unstated. GOOD | shipments.warehouse_id | warehouses.warehouse_id | Foreign key | Every shipment originates from exactly one warehouse | WEAK | shipments | warehouses | related | | TRAP Naming a relationship that exists only informally, through a shared naming convention, as though it were an enforced foreign key, when no constraint or documented join condition actually ties the two columns together. -->
| This field | Related table and field | Relationship | Notes ||---|---|---|---|| {{related_field}} | {{related_table_field}} | {{relationship_type}} | {{relationship_notes}} |
## Validation Rules
<!-- WHAT Enum lists, numeric ranges, required-versus-optional fields, and any cross-field rule a loader or a reviewer should check, stated separately from the field table's own allowed-values cells. WHY A small table's Field Definitions table already carries its allowed values, while a larger or more heavily consumed table benefits from stating the checks separately so a loader can test against them directly. Docsie's own template asks the author to "List accepted values, null handling, range checks, and uniqueness rules," and Basedash's own attribute list names the same content at the field level, "Enums, ranges, or units." dbt's own documentation-as-code mechanism offers a parallel, automated form of the same idea, a test declared beside the field's own description. Deep dive: data-dictionary_companion.md section 3 (Validation Rules). ASK Which fields must be unique? Which are required rather than optional? What numeric range, if any, is valid? What cross-field rule, if any, must hold (for example, a status that constrains which other fields may be populated)? PRIORITY State the rule as something a loader could actually run, not as prose a human must interpret differently each time; "shipment_id must be unique" is testable, "shipment IDs should make sense" is not. ROW HINT A good row names the exact field and a rule specific enough to fail a real row against it. A weak row names a field with no rule, or a rule so general it would accept almost anything. GOOD | shipment_id | Must be unique across the table | WEAK | shipment_id | Should be correct | TRAP Restating a field's allowed-values cell here word for word with no added rule, which duplicates the Field Definitions table instead of adding a check that table does not already state. -->
| Field | Rule ||---|---|| {{validation_field}} | {{validation_rule}} |
## 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}}
## Review and Sign-off
<!-- WHAT A formal record of who reviewed and approved this version, and when, apart from the Ownership and Review section's own standing owner and cadence, plus the running record of what changed, including each field's own deprecation. WHY A small, informally maintained table needs no sign-off chain, while a dataset several teams rely on, or one that feeds a regulated report, benefits from a dated approval trail. Docsie's own shipped document carries exactly this beyond its basic owner-and-cadence fields, with "Preparer," "Reviewer," and "Approver" roles, a "Review Cycle," an "Effective Date," and a status field, "[Draft / In Review / Approved]." A field the schema has stopped using is marked rather than silently dropped: the NIMH Data Archive marks an entry "obsolete, superseded by newer structures," and this section's version history is where that marker, and its date, are recorded. Deep dive: data-dictionary_companion.md section 3 (Review and Sign-off). ASK Who prepared this version? Who reviewed it, and who approved it? What review cycle does this version follow, and what is its status: Draft, In Review, or Approved? What is the running record of what changed, when, why, and who approved it, including when a field was deprecated? PRIORITY Every version-history row names the field or table affected and the person who approved the change, not only that "something was updated." A deprecated field's row names its replacement, if one exists, and the date the deprecation took effect. ROW HINT A good version-history row names the field, what changed about it (added, redefined, deprecated, removed), who approved it, and when. A weak row says "updated" with no field named and no approver. GOOD "Preparer: Priya Okafor. Reviewer: the fulfillment data steward. Approver: the Fulfillment Eng lead. Review cycle: quarterly. Status: Approved." Version history row: | v2.1 | 2026-09-01 | carrier_code enum value "ontrac" removed, superseded by a direct carrier-API integration | Approved by the Fulfillment Eng lead | WEAK Version history row: | v2.1 | | updated some fields | | TRAP Marking a field deprecated with no replacement named and no removal date, leaving a reader with no way to tell whether the field is still safe to query against. -->
**Preparer:** {{preparer}}
**Reviewer:** {{reviewer}}
**Approver:** {{approver}}
**Review cycle:** {{review_cycle}}
**Status:** {{signoff_status}}
| Version | Date | What changed | Approved by ||---|---|---|---|| {{version_number}} | {{version_date}} | {{version_change_summary}} | {{version_approved_by}} |---title: "Acme Analytics Reporting Warehouse Data Dictionary"dataset: "Reporting analytics warehouse: the events, report_sessions, users, and accounts tables"owner: "Lee Zhang (Data Eng)"steward: "Lee Zhang (Data Eng)"dictionary_version: "v1.1"last_reviewed: "2026-09-08"status: "active"doc_type: data-dictionarysize: fullsource_template: data-dictionarysource_template_version: 0.1.0---
> **Worked example.** A filled `data-dictionary`, full variant, for the Reporting Platform Modernization> program at the fictional Acme Analytics, the same program the> [`tracking-plan`](../tracking-plan/tracking-plan_example.md) and> [`kpi-dashboard`](../kpi-dashboard/kpi-dashboard_example.md) examples already cover, and the same program> whose [risk register](../risk-register/risk-register_example.md),> [RAID log](../raid-log/raid-log_example.md), [issue log](../issue-log/issue-log_example.md), and> [change log](../change-log/change-log_example.md) Marta Reyes already keeps as its other standing> governance instruments. `data-dictionary` joined the `governance-docs` family as its seventh member on> 2026-10-15 under> [ADR 0073](../../docs/internal/decisions/0073-data-dictionary-joins-governance-docs-as-a-seventh-member.md),> distinct from the tracking plan upstream of it: the tracking plan specifies the events and properties the> Reporting product emits, and this document describes what the warehouse columns those events land in> actually mean. It is dated **2026-09-08**: after the tracking plan's own last review on 2026-08-24, and> after the Saved Views adoption-nudge experiment closed on 2026-08-31, so the `variant_id` column below is> documented as a closed test's assignment field, without this document restating what the test found. No> version-history entry below predates 2026-08-24.>> Figures not already fixed by a sibling example, including every table and column name, every type and> nullability statement, the warehouse's internal grain and join structure, and the review channel name,> are illustrative: plausible for this document, invented for it, and not drawn from a real company.
# Acme Analytics Reporting Warehouse Data Dictionary
## Purpose and Boundary
This document covers four tables in the warehouse the Reporting product's events land in once Amplitudeexports them: `events`, `report_sessions`, `users`, and `accounts`. It does not catalog which events theReporting web app emits or why each one is tracked; a reader after that, including each event's ownbusiness question, wants the [tracking plan](../tracking-plan/tracking-plan_example.md) open instead, andthis document assumes they already have it. It does not fix Time to Insight's formula, inclusions, orexclusions; the [KPI dashboard](../kpi-dashboard/kpi-dashboard_example.md) already settles those in itsown Metric Definitions section. What this document adds that neither sibling states is the warehouse's ownshape: the table and column names an analyst actually queries, each column's type and nullability as aschema fact, the keys that enforce each table's grain, and the joins between them.
## Dataset Metadata
**Source system(s):** The nightly Amplitude product-event export (the ten events the tracking plan's Eventand Property Catalog names) and the nightly entitlements-database export (`analyst_segment` and`migration_reconciled`, the two user and account traits the tracking plan names), both loaded into theReporting analytics warehouse.
**Version:** v1.1
**Effective date:** 2026-09-08
**Refresh cadence:** Nightly for both source exports, matching the cadence the tracking plan states for theentitlements export.
**Primary consumers:** The Looker executive view that implements the KPI dashboard's live metrics, and theData Eng team's own debugging queries against the warehouse directly.
## Field Definitions
**Table:** events
**Grain:** One row per event occurrence the Reporting web app logs to Amplitude and the nightly exportlands in this warehouse. **Key column(s):** `event_id` enforces the grain.
| Field | Type and nullability | Definition | Allowed values, units, or missing codes | Source | Sensitivity | Owner ||---|---|---|---|---|---|---|| event_id | string, not null | A unique identifier for one logged event occurrence, assigned by the warehouse's nightly load job when the row lands | Free-form; no coding scheme | Assigned at load from the Amplitude export | none | Data Eng || event_name | string, not null | Which of the ten events in the tracking plan's Event and Property Catalog this row records | Enum: view_saved, view_switched, view_set_default, view_shared, view_load_error, report_opened, report_exported, report_shared, report_annotated, nudge_variant_assigned | Amplitude export, loaded nightly | none | Data Eng || occurred_at | timestamp, not null | When the event fired in the Reporting web app, as Amplitude timestamped it | UTC | Amplitude export | none | Data Eng || user_id | string, nullable | The user who fired the event; joins to users.user_id | Free-form; null only on nudge_variant_assigned, the one event the tracking plan ties to the account rather than a user | Amplitude export | none | Data Eng || account_id | string, nullable | The account the event's user belongs to; joins to accounts.account_id | Free-form; populated directly on nudge_variant_assigned, where the tracking plan names it as the event's own property; derived at load by joining user_id to accounts for every other event | Direct on nudge_variant_assigned; derived for every other event name | none | Data Eng || dashboard_id | string, nullable | The dashboard the event names: the saved view's own dashboard on the five Saved Views events, or the dashboard a report belongs to on report_opened | Free-form; null on report_exported, report_shared, report_annotated, and nudge_variant_assigned | Amplitude export | none | Data Eng || view_scope | string, nullable | The saved view's own scope property, carried through unchanged from the tracking plan's property of the same name | Free-form; populated on the five Saved Views events only | Amplitude export | none | Data Eng || report_id | string, nullable | The report the event names | Free-form; populated on report_opened, report_exported, report_shared, and report_annotated only | Amplitude export | none | Data Eng || reason | string, nullable | Why a saved view failed to load | Enum: filters_removed, permission_denied, timeout, unknown; populated on view_load_error only | Amplitude export | none | Data Eng || export_format | string, nullable | The file format a report was exported in | Enum: csv, pdf, image; populated on report_exported only | Amplitude export | none | Data Eng || annotation_id | string, nullable | The annotation the event names | Free-form; populated on report_annotated only | Amplitude export | none | Data Eng || recipient_user_id_hash | string, nullable | The colleague a view or a report was shared with, already hashed before this warehouse received it | Free-form hash; populated on view_shared and report_shared only; the tracking plan's own retention figure for this column (180 days) is still pending legal confirmation as of this document's date | Amplitude export, hashed in the ingestion pipeline before load | pii | Data Eng || variant_id | string, nullable | Which arm of the Saved Views adoption-nudge test the account was assigned to | Free-form; populated on nudge_variant_assigned only; the test closed 2026-08-31, so no row dated after that carries this event name | Amplitude export | none | Data Eng |
**Table:** report_sessions
**Grain:** One row per report-opening session: one row is created for every report_opened event row in theevents table above. **Key column(s):** `report_session_id` enforces the grain.
| Field | Type and nullability | Definition | Allowed values, units, or missing codes | Source | Sensitivity | Owner ||---|---|---|---|---|---|---|| report_session_id | string, not null | A surrogate key assigned when this session row is created from its originating report_opened event | Free-form | Assigned at load, one per report_opened row | none | Data Eng || report_id | string, not null | The report this session opened; carried through from the originating report_opened event's own property | Free-form; this warehouse does not yet carry a separate reports dimension table, so this column cannot be joined further than the events table it was copied from | Copied from events.report_id at load | none | Data Eng || user_id | string, not null | The analyst who opened the report; joins to users.user_id | Free-form | Copied from events.user_id at load | none | Data Eng || report_opened_at | timestamp, not null | When the report was opened: the first of Time to Insight's two timestamps | UTC; copied from the originating report_opened event's occurred_at | Derived at load from events | none | Data Eng || first_action_at | timestamp, nullable | The earliest occurred_at among report_exported, report_shared, and report_annotated events with this session's user_id and report_id, from report_opened_at until that user's next report_opened on the same report: the second of Time to Insight's two timestamps | UTC; null until one of the three actions fires for this session | Derived at load from events | none | Data Eng || first_action_type | string, nullable | Which of the three logged actions set first_action_at | Enum: report_exported, report_shared, report_annotated; null while first_action_at is null | Derived at load from events | none | Data Eng |
**Table:** users
**Grain:** One row per user. **Key column(s):** `user_id` enforces the grain.
| Field | Type and nullability | Definition | Allowed values, units, or missing codes | Source | Sensitivity | Owner ||---|---|---|---|---|---|---|| user_id | string, not null | A unique identifier for one Reporting user | Free-form | Entitlements export | none | Data Eng || account_id | string, not null | The account this user belongs to; joins to accounts.account_id | Free-form | Entitlements export | none | Data Eng || analyst_segment | string, not null | Which segment this user is classified into, the same property the tracking plan names | Enum: recurring, trialist, internal | Entitlements database, refreshed nightly, the same cadence the tracking plan states | none | Data Eng |
This table carries no column marking a service account. The Weekly active analysts metric's service-accountexclusion, named in the KPI dashboard's Metric Definitions section, is applied outside this warehouse today.Closing that gap is a known caveat of this table, not a column a reader can look up here yet.
**Table:** accounts
**Grain:** One row per account. **Key column(s):** `account_id` enforces the grain.
| Field | Type and nullability | Definition | Allowed values, units, or missing codes | Source | Sensitivity | Owner ||---|---|---|---|---|---|---|| account_id | string, not null | A unique identifier for one Reporting account | Free-form | Entitlements export | none | Data Eng || migration_reconciled | boolean, nullable | Whether this account's legacy saved-view configuration has been reconciled against the new schema, the same property the tracking plan names | True, false, or null before the migration cutover runs | Set by the migration reconciliation job at cutover | none | Data Eng |
## Relationships
| This field | Related table and field | Relationship | Notes ||---|---|---|---|| events.user_id | users.user_id | Foreign key | Null on nudge_variant_assigned; populated on every other event name || events.account_id | accounts.account_id | Foreign key | Direct on nudge_variant_assigned; derived by joining user_id to accounts for every other event name || report_sessions.report_id | events.report_id | Derived | Copied from the originating report_opened row; not an enforced foreign key, because no reports dimension table exists yet || report_sessions.first_action_at | events.occurred_at | Derived | Scoped to events with the same user_id and report_id, from report_opened_at until that user's next report_opened on the same report; no session identifier is stored on the events table, so this rule is the join || report_sessions.user_id | users.user_id | Foreign key | The analyst who opened the report || users.account_id | accounts.account_id | Foreign key | Every user belongs to exactly one account |
## Validation Rules
| Field | Rule ||---|---|| events.event_id | No two rows may share the same value || events.occurred_at | Required on every row || report_sessions.report_session_id | No two rows may share the same value || report_sessions.first_action_at | When populated, must be later than report_opened_at on the same row || users.analyst_segment | Must be one of recurring, trialist, internal || users.account_id | Required on every row; every user belongs to exactly one account |
## Ownership and Review
**Table owner:** Lee Zhang (Data Eng), who built and maintains this warehouse's schema.
**Table steward:** Lee Zhang (Data Eng).
**How to propose a change:** Propose a change in the #reporting-warehouse channel. Lee Zhang checks aproposed column against the tracking plan's own event and property names before it is added here.
**Review interval:** Monthly, the Tuesday before the tracking plan's own monthly review, so a schemaquestion raised here is already settled by the time that review reads events against it. This interval isData Eng's own choice, not borrowed from elsewhere.
**Other review triggers:** Every schema change to the warehouse, ahead of the monthly date rather thanwaiting for it, the same trigger shape the tracking plan uses for its own event changes. A definition areader reports as wrong or unclear is corrected when it is found, not held for the monthly date.
## Review and Sign-off
**Preparer:** Lee Zhang (Data Eng).
**Reviewer:** Dana Osei (Staff Engineer, Platform).
**Approver:** Marta Reyes (Program Manager, Reporting Platform Modernization).
**Review cycle:** Monthly.
**Status:** Approved.
| Version | Date | What changed | Approved by ||---|---|---|---|| v1.0 | 2026-09-01 | Initial dictionary published, covering the events, report_sessions, users, and accounts tables | Marta Reyes || v1.1 | 2026-09-08 | events.account_id's Definition cell clarified to state that every event besides nudge_variant_assigned derives account_id by joining user_id to accounts, rather than carrying it directly; and variant_id's allowed-values note updated to record that the adoption-nudge test closed on 2026-08-31 | Marta Reyes |Provenance
Section titled “Provenance”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.