Build a data dictionary for a small research dataset
Document what each variable means, how it is coded, and when values are missing so another reader can interpret your dataset without guessing.
About 5 min read · Allow extra time for the practical checks
A spreadsheet column called score, a value of 2, or a blank cell may seem obvious to the person who collected the data. A collaborator opening the file later may not know what the score measures, which response the code represents, or whether the blank means “not asked”, “not recorded” or “not applicable”.
A data dictionary makes those decisions visible at the variable level. It gives a reader enough information to interpret the fields in a dataset and trace important coding choices. It does not replace the study protocol, data-management plan, survey instrument or analysis code. It is a compact reference to what the fields in the data actually mean.
The UK Data Service recommends documenting variable names and labels, types, units, coding, missing-value conventions, applicability, weights and derived variables. ICPSR’s codebook guidance also points to question wording, response labels, skip patterns and notes where those help a user interpret a variable. Both sources stress clarity and context; neither requires one universal layout. Check the format required by your repository, course or research team.
Begin with the data file you will describe
Before writing, identify the exact file and version. Check the column names against the file, confirm what one row represents, and find the instrument or protocol that defines the variables. If a column has been renamed, recoded or calculated, record the current field and explain the change. Do not infer its definition from a short label alone.
The dictionary should answer a few practical questions for each field:
- What is the variable called in the file, and what does it represent?
- What type of value does it contain, and what are its units or allowed categories?
- What does each code mean? How are missing and non-response values represented?
- Which cases were eligible to have a value?
- If the variable was derived, how was it constructed?
Not every project needs every column in the same table. Include details that affect interpretation or reuse, and place longer study background in a README or codebook introduction.
Use a consistent variable-level structure
The fictional table below demonstrates one possible format. The project name, participants, variables, values, codes and calculations are invented. The codes are not recommendations for real datasets.
On a narrow screen, scroll sideways to compare each fictional variable with its definition and coding notes.
| File name | Meaning and type | Values or units | Applicability and missingness | Construction or note |
|---|---|---|---|---|
feedback_mode | Assigned feedback format; categorical | 1 = written; 2 = audio | All participants in the second pilot; blank = no assignment recorded | Labels copied from the pilot assignment list |
completion_min | Minutes from opening to submission; numeric | Minutes; valid range in the source file is 3–88 | Submitted tasks only; blank = timing not captured | Do not replace blank timing with zero |
change_points | Difference between two rubric scores; derived numeric measure | Points on the same 0–10 scale as each score | Only where both scores are present; blank if either score is unavailable | followup_score - initial_score; negative values indicate a lower follow-up score |
The table separates a field’s name from its reader-facing meaning. A numeric code is not self-explanatory: a user needs the mapping to “written” or “audio”. Units matter too. A value such as 15 could mean minutes, points or cases unless the dictionary says which.
Explain missing values and who was eligible
Avoid treating every blank or special code as the same kind of missingness. A blank could mean the question was skipped, the person declined, the field was not collected in a particular wave, or the value was lost. Those situations can affect analysis differently. Define the code used in the file and explain the reason only when records or study procedures support it.
Applicability is related but separate. If only people who submitted a task can have a completion time, state that universe. If a follow-up measure was collected from a subset, say which subset. This helps a reader distinguish “not applicable” from “applicable but unanswered”. Keep the dictionary aligned with any denominator or missing-data explanation in the report; see the separate guide to reporting missing observations and changing denominators.
Document variables you created
For a calculated field, give a usable definition of the derivation. A short formula may be enough for a simple difference. If the field uses several steps, categories, exclusions or a reference date, give the rules or point to retained code. State which source fields feed the calculation and what happens when an input is missing.
Check the definition against your operational definitions: an operational definition explains how a research concept is observed or measured; a data dictionary explains how the resulting field is represented in the file. They connect, but they answer different questions.
Check the dictionary against the dataset
Before sharing the file, compare the dictionary with the actual data and supporting materials:
- Confirm every documented variable exists, and identify undocumented fields.
- Check that categorical values and labels match those in the file.
- Confirm units, valid ranges, wave labels and missing codes against the instrument or data record.
- Check that calculated fields match the retained formula or syntax.
- State what one row represents and how files or identifiers relate, if that is not obvious.
- Remove or generalise sensitive examples and identifiers before sharing.
A dictionary is useful only when it describes the file someone receives. Keep the version, names and code meanings aligned when the dataset changes. For summaries of the values actually observed, use a separate descriptive-statistics table; the dictionary explains fields, while that table reports the analysis sample.
The table is a starting point, not a required schema. Formats vary by dataset, course and repository. The fictional entries establish no required code scheme or valid range; follow your project, ethics and repository requirements.
