Why a Data Dictionary Matters
A dataset can contain entries that look clear when first recorded but become uncertain later. Does a value of 30 mean minutes or seconds? Does “0” mean no, not recorded, or not applicable? A data dictionary answers these questions by documenting what each variable represents and how its values are encoded. It helps people interpret data consistently without having to guess from column labels or ask the original recorder.
A data dictionary is not the dataset itself, and it is not a record of every action taken while collecting data. It is a reference for the variables and their recorded values. Recording Data Provenance addresses where data came from and how they were obtained; a data dictionary focuses on what the variables mean and how to read them.
A useful definition is specific enough that someone unfamiliar with the collection can decide what an entry means. “Time” is too vague: it could refer to the time of day, a duration, or a date. “Minutes from check-in to departure” identifies a duration and its unit. Likewise, “status” does not explain which categories are permitted; listing the categories does.
What to Record for Each Variable
A dictionary should use names that are stable and understandable, such as visit_minutes rather than col3. The name is a compact identifier; the definition supplies the meaning. Avoid relying on abbreviations unless they are explained, and use a consistent naming style within the dictionary.
For quantitative variables, state the unit and whether values are counts, measurements, or durations. For categorical variables, list the permitted labels or codes and explain them. If a numeric code represents a category, say so explicitly: a code such as 1 for “bus” is not a measurement of one bus. Also document missing-value conventions. A missing entry is not automatically a zero, and different missing codes should not be assumed to have the same meaning.
| Dictionary field | What it specifies | Example |
|---|---|---|
| Variable name | A stable identifier used to refer to the variable | visit_minutes |
| Meaning | What is recorded, including relevant scope or timing | Duration from check-in to departure |
| Unit | The measurement unit, or “not applicable” for labels | Minutes |
| Allowed values | Permitted values, labels, or codes and their meanings | Nonnegative whole numbers |
| Missing-value codes | Special representations for absent or inapplicable values | NA = not recorded |
A compact description can include further details where they matter, such as the time period covered or which response option a category represents. The goal is not to add lengthy prose to every entry; it is to remove consequential ambiguity. A definition should distinguish the intended observation from the way it happens to be stored.
Worked Example: Defining a Visit Duration
Imagine a hypothetical community center records how long each visitor stays. A spreadsheet column is named time, with entries such as 35 and 80. Build a dictionary entry that would allow another analyst to interpret those entries.
Variable name. Rename the identifier as visit_minutes. This name suggests a duration and its unit, while the definition will state both precisely.
Meaning and unit. Define it as “elapsed time, in minutes, from the visitor’s check-in to departure on the recorded visit date.” The unit is minutes. This definition clarifies that the variable is a duration, not the clock time when a visitor arrived.
Allowed values. Specify nonnegative whole numbers of minutes, such as 35 or 80. A value of 35 therefore means a visit lasting 35 minutes, not 35 seconds. If the collection records partial minutes, the dictionary must say so instead of silently treating decimals as whole minutes.
Missing value. Suppose the recorder uses the literal token NA when the duration was not recorded. Define that token as “duration not recorded” and state that it is not a duration of zero minutes. The finished entry now defines the variable, unit, permitted form of recorded values, and missing representation.
Missing Codes Need Explicit Meanings
A missing-value code is a storage convention, not an observed value of the variable. For example, if NA means “not recorded,” then it does not describe an actual category of travel or a measured duration. The dictionary should show which codes are permitted and state their meanings. It should also distinguish codes with different meanings rather than grouping them under an unexplained label such as “missing.”
One project might use NR for “not recorded” and REF for “the participant declined to answer.” These are not interchangeable descriptions: the first indicates a recording gap, while the second indicates a response choice. A third code, such as NA for “not applicable,” should be used only when that meaning is actually relevant and defined. It should not be added simply because it is a familiar abbreviation.
When a dataset stores missing codes alongside measured values, the dictionary must make the distinction visible. For instance, if age is recorded in years and the cell contains REF, the code means the person declined to provide an age; it is not a number of years. Anyone using or importing the data needs the documented convention to handle that entry as intended.
Worked Example: A Small Data Dictionary
Consider a hypothetical community center that records one entry for each visit. For this example, suppose the center records an anonymous visit identifier, age in completed years, travel mode, and whether the visitor agreed to be contacted about a later program. The following dictionary defines those fields; the example does not describe real visitors.
| Variable name | Meaning | Unit | Allowed values | Missing-value codes |
|---|---|---|---|---|
| visit_id | Anonymous identifier assigned to a recorded visit | Not applicable | Unique text identifier, such as V001 | None; an identifier is assigned to each recorded visit |
| age_years | Visitor’s age in completed years on the visit date | Years | Whole-number age values from 18 through 110 | NR = not recorded; REF = visitor declined |
| travel_mode | Visitor’s reported main mode of travel to the center | Not applicable | Walk, bicycle, bus, car, other | NR = not recorded; REF = visitor declined |
| contact_ok | Whether the visitor agreed to be contacted about a later program | Not applicable | Yes, No | NR = not recorded; REF = visitor declined; NA = question not applicable |
Each entry specifies a meaning rather than merely repeating its name. age_years says when age is measured and that it is recorded in completed years. travel_mode identifies the reported main mode and lists the exact labels. The allowed values for contact_ok are Yes and No; REF is not a third answer to the question but a code for a declined response.
The permitted age range in this hypothetical dictionary reflects the stated scope of this example’s data collection. In an actual project, the scope and permitted values would need to be chosen to fit the population and collection protocol, not copied automatically from this table. Likewise, NA is defined only for the contact question, where the example allows that the question might not apply. A missing code should be included only when the collection has a defined reason for using it.
Why Precise Definitions Change Interpretation
A data dictionary matters because interpretation depends on a link between a stored entry and what that entry represents. If the link is unclear, a number can support more than one reading. Consider an entry of 30 under a column named time. It could mean 30 minutes, 30 seconds, or a clock reading. With a dictionary definition of “elapsed time from check-in to departure, measured in minutes,” the intended interpretation is fixed.
This is a simple but important justification for documenting units and definitions: without the description, the same stored entry can map to different interpretations; with it, the intended interpretation is specified. The dictionary does not make an ambiguous or inaccurate measurement correct. It makes the recorded convention explicit so that users can understand what was intended and identify questions that still need clarification.
A precise dictionary also helps people distinguish legitimate values from codes and labels. A category code of 2 might stand for “bus,” while the number 2 in a count variable means two units. Without a variable-specific definition, numeric entries can be mistaken for quantities on which arithmetic is meaningful. The dictionary states whether values are measurements, counts, categories, identifiers, or missing-value tokens.
Worked Example: Improving an Ambiguous Entry
Suppose a hypothetical dictionary contains the following entry: variable: result; description: number; values: 0, 1, 2, 9. Improve it for a survey question asking whether a participant attended a workshop.
Identify the problem. “Result” and “number” do not say what was asked or whether the digits are measurements or category codes. The meaning of 9 is also unknown. A user could mistakenly treat all four entries as quantities.
Define the variable. Use the name workshop_attended and the meaning “Participant’s answer to whether they attended the specified workshop.” The scope is now clear enough to interpret the response.
List substantive values. Define 0 as “No” and 1 as “Yes,” and state that these are category codes, not counts. For example, 1 means that the participant answered Yes; it does not mean one workshop.
Resolve the code 9. Do not leave it as an unexplained allowed value. If the collection protocol defines 9 as “response not recorded,” list it as a missing-value code with that meaning. If the protocol does not establish what 9 means, the dictionary writer cannot infer the answer; the code needs clarification before it can be documented accurately.
A completed entry might therefore read: workshop_attended; participant’s answer about attending the specified workshop; unit not applicable; 0 = No, 1 = Yes; 9 = response not recorded. This is only appropriate if the data-collection convention really assigns 9 that meaning.
Building and Reviewing a Dictionary
A practical dictionary can be drafted while the variables and recording conventions are being specified. For each variable, ask what is being measured or classified, for whom or what, and at what point or over what period. Then record the unit, permitted values, and any missing codes with their meanings. If a detail is unknown, mark it for clarification rather than making an unsupported assumption.
Choose a stable identifier that is distinguishable from other variables and does not depend on a temporary column position.
State what is recorded and include relevant scope, timing, or response context.
Give units for measurements and list valid labels or codes for categories, explaining what each code represents.
List each permitted code and its meaning separately from the variable’s substantive values.
Ask whether someone unfamiliar with the project could interpret a typical entry without guessing. Revise any entry that leaves multiple plausible meanings.
This review is about the clarity and completeness of the documentation. It does not establish that a measurement was collected correctly or that a recorded value is accurate. Those questions depend on the collection process and the data themselves. The dictionary provides a shared account of intended meaning; it cannot substitute for good measurement or erase uncertainty that the documentation does not resolve.
Common Mistakes
- Using a name as the full definition. A variable called duration still needs to say what interval it measures and in what unit.
- Leaving units implicit. A numeric entry such as 12 is not self-explanatory. State whether it represents hours, minutes, years, or something else.
- Treating numeric category codes as measurements. If 1 means “Yes” and 0 means “No,” document them as labels. Their numerical appearance does not make them counts or measurements.
- Giving a missing code no meaning. “99 = missing” is incomplete unless the dictionary says what kind of missingness it represents and confirms that 99 is a code, not a substantive value.
- Guessing what an undocumented code means. A plausible interpretation is not a documented fact. Seek clarification or record the uncertainty rather than silently assigning a meaning.
Check Your Understanding
Use the examples and definitions above to answer these questions.
- What information should a dictionary entry provide beyond the variable name?
- A variable is named time and contains the value 20. Give two different possible interpretations that a precise definition and unit could distinguish.
- A survey stores 0 for “No,” 1 for “Yes,” and REF when a participant declines. Which are substantive category codes, and which is a missing-value code?
- Why should a dictionary state whether a numeric code represents a category rather than a quantity?
- A dictionary lists 9 as “missing” but gives no further explanation. What clarification would make this entry more useful?