What Is a Data Dictionary?
A data dictionary describes the variables in a dataset: their names, meanings, storage types, units, permitted values and rules. It lets another person interpret a column without asking its creator. A heading such as status is not enough: it might mean interview completion, participant eligibility or service use.
In M&E, the dictionary sits beside the dataset and its data management arrangements. It is not the dataset itself, the questionnaire or the full analysis plan. An indicator reference sheet defines a measure; the dictionary explains the actual fields needed to calculate it. Link the two rather than copying different definitions into separate places.
What to Record for Each Variable
Use one row per variable and separate columns for different properties. Record the dataset or table first, especially when several files reuse names such as date or id.
| Property | What to Record | A Useful Check |
|---|---|---|
| Name and label | Exact machine name and a readable label | Can the name be matched to the exported column? |
| Definition | What is observed, for whom and over which period | Would two analysts interpret it the same way? |
| Type and format | Integer, decimal, text, date or category; date format | Could import software change the value? |
| Allowed values | Codes, labels, ranges and units | Are unusual but valid values distinguished from errors? |
| Missing values | Each reason, code and analysis treatment | Can refusal be separated from inapplicability? |
| Source | Question, administrative field or calculation | Can the field be traced back to its origin? |
| Derivation | Formula, inputs, eligibility and exclusions | Can another analyst reproduce it? |
| Ownership and version | Responsible role, revision date and dataset release | Does this dictionary describe this file? |
A variable label is a short reminder, not a substitute for its definition. “Attended” still needs an activity, a reference period and a rule for what counts as attendance. For dates, distinguish collection date, event date and entry date.
A Worked Example
The following fields belong to a hypothetical training follow-up dataset. The names, codes and calculation choices illustrate documentation; they are not universal standards.
| Variable | Definition and Type | Values or Rule |
|---|---|---|
record_key | Text key for one respondent's follow-up record | Generated study key; preserve leading zeros; no names |
eligible | Integer: met the follow-up eligibility rule | 1 = yes; 0 = no; eligibility rule documented separately |
sessions_attended | Integer: sessions attended during the stated cycle | 0 to 6; blank only with a documented missing reason |
attendance_missing_reason | Text reason when the session count is absent | refused, unknown, not_applicable or not_recorded |
completed_cycle | Derived category for eligible respondents with observed attendance | 1 if attendance is at least 4; otherwise 0; absent when eligibility or attendance is unresolved |
The four-session threshold is an invented choice for this example. The dictionary should point to the approved program definition instead of making a threshold seem standard. An ineligible respondent does not automatically become a non-completer. Document who enters the denominator before reporting a completion percentage.
A dictionary describes the key's format and purpose. It should not contain a real participant key paired with a name, telephone number or identifying interview quote. Use artificial examples and control access to any separate linkage file.
How to Build and Check It
- Start from the instrument and expected export. List every field, including identifiers, timestamps, repeated groups and calculated variables.
- Write definitions before collection. Resolve ambiguous concepts with the program and analysis leads while changes are still practical.
- List valid codes and missing reasons separately. Choose a representation the collection and analysis tools can preserve.
- Document derivations with input names, eligibility rules, units and exclusions. Keep an executable calculation in the analysis workflow when possible.
- Compare the dictionary with a real export. Look for undocumented columns, renamed fields and categories that never reached the specification.
- Ask another analyst to calculate a selected measure using the dataset and dictionary. Record where clarification was necessary.
- Release them together with matching version information. Record later definition changes rather than silently replacing the meaning of an old field.
These checks complement data quality assurance; a complete dictionary cannot prove that the observations are correct. A value may satisfy its declared range and still refer to the wrong person or reporting period.
Missing Values Need an Explicit Rule
Zero can be a genuine observation. It should not silently mean “not asked,” “refused” and “unknown” at the same time. A separate reason field, software-supported missing categories or reserved codes can preserve distinctions. Choose deliberately, document the choice and test the export.
If reserved numbers are used, exclude them from arithmetic and ensure they cannot collide with valid values. A code that works for a yes/no question might be a plausible value in an income field. If software converts special missing categories to blanks, preserve the reason through another field or a documented export step.
Do not quietly replace missing observations with zero. If values are imputed, retain provenance, identify the imputed records or fields, and document the method. The reporting denominator must agree with the declared analysis rule.
Keep Human and Machine Versions Together
A spreadsheet can be convenient for review; a structured CSV, database schema or other machine-readable specification can support automated checks. Neither format removes the need for readable definitions. Avoid two independently maintained dictionaries. Generate one view from the other where practical and compare exported field names during each release.
Keep stable variable names when their meaning stays stable. If meaning changes, document whether a new field is needed and whether periods remain comparable. Preserve the old dictionary with the dataset version it describes.
Common Questions
Is a Data Dictionary the Same as a Codebook?
The terms overlap for quantitative data: “codebook” often includes variable definitions, response codes and survey questions. A qualitative codebook has a different job: it defines the analytic codes applied to interview or document passages. State which meaning is intended.
Must Every Project Use the Same Missing-Value Codes?
No universal set fits every tool and variable. Use a consistent project convention where compatible, preserve the different reasons for absence and document any exceptions. What matters is that a reader and the analysis software can distinguish missing observations from valid values.
Last updated October 25, 20263 sources checked
M&E Studio also does this work for clients.
The team that writes and reviews this library takes on M&E system design, evaluation quality reviews, AI advisory and workflow automation.
variable dictionary, data codebook, variable documentation