Research Data Dictionary: Template and Example
Document variable meanings, units, codes, missing values and derivations so your dataset can be interpreted and analysed consistently.
Six months after data collection, will someone know whether visit2 means a second appointment, a second interview or attendance at follow-up? A data dictionary should answer that question without requiring the person who created the variable to be available.
A research data dictionary describes the contents and conventions of a dataset. It connects short variable names to their meaning, source, coding and derivation. It is part of the analysis infrastructure, not an optional appendix added when sharing becomes unavoidable.
In this guide
Document more than labels
At minimum, record the variable name, description, data type, units or categories, allowed values, missing-value conventions and source question. For derived variables, include the rule and version of the code that generated them.
The UK Data Service. Prepare your data collection for deposit. highlights documentation needed for usable research data. A project-level dictionary can support that goal from the beginning, even when the dataset will remain restricted.
Use an explicit example
For a fictional appointment study:
| Variable | Meaning | Coding or units | Important note |
|---|---|---|---|
| participant_id | Pseudonymous participant key | String | Not a phone number or name |
| scheduled_date | Date of planned appointment | ISO date | Distinguish from actual attendance date |
| attended_7d | Attendance within seven days of scheduled date | 0 = no; 1 = yes | Derived only where outcome is ascertainable |
| travel_minutes | Reported one-way journey duration | Minutes | Do not combine with round-trip duration |
| outcome_missing_reason | Reason attendance is unknown | Defined categories | Separate from observed non-attendance |
The dictionary should explain boundary decisions too. Does “within seven days” include the scheduled day? How are early visits handled? The answer belongs in the documented derivation, not in an analyst’s memory.
Distinguish missing from zero
Zero travel cost can be a real value. A blank cost may mean not recorded. “Not applicable” may mean the person did not make the journey. Those states should not collapse into the same number.
If special numeric codes are used during collection, document them and convert or handle them appropriately in analysis. Otherwise, a code such as 999 can silently become an extreme but apparently valid observation.
Where practical, keep a separate field for the reason information is missing. Do not infer the reason from the value alone.
Record how derived variables are made
A label such as “knowledge score” is insufficient. List contributing items, reverse coding, weighting, permissible missing items and the score range. Link the derivation to executable code or a fully specified rule.
If the scoring rule changes, version it and regenerate the variable from preserved source data. Do not overwrite the old definition without documenting which analyses used it.
Keep the dictionary synchronised
Assign responsibility for updates. Review it after questionnaire changes, import transformations and analysis decisions. A dictionary that describes last month’s dataset can be more misleading than no dictionary because it looks authoritative.
Use automated checks where feasible to compare variable names, allowed categories and types with the actual dataset. Investigate mismatches; do not simply amend the dictionary to legitimise an unexpected value.
Test it with an unfamiliar reader
Give a colleague the dictionary and a small, appropriately de-identified or synthetic data extract. Ask them to calculate one basic measure and explain its denominator. If they need several clarifications, add those answers to the documentation.
Copy this data-dictionary header
An explicit definition prevents a plausible but wrong calculation.
Use one row per variable; keep longer derivation code in a versioned script referenced by the dictionary.
variable_name | label | source_item | data_type | units | allowed_values | missing_codes | derivation_rule | code_version | notes
For attended_7d, an explicit fictional rule could count attendance from the scheduled date through seven calendar days afterwards, inclusive. A known visit in that window is coded 1. Code 0 only when the ascertainment procedure establishes no visit in the window; otherwise retain a missing outcome and its reason. Define handling of early visits and date-time boundaries for the actual study before deriving the variable.
Good documentation reduces repeated questions and prevents avoidable analytical disagreements. It also makes future collaboration less dependent on whoever remembers what final_score_new2 was supposed to mean. Continue with the statistics and results collection once the data structure is explicit.
Continue your research
Three useful next steps for this topic.
Research notes, once a week
Practical research guidance, useful tools and funding opportunities in your inbox.