Data Dictionary

A data dictionary is a centralized reference document that describes the structure, content, format, and meaning of each variable in a dataset. It serves as the essential guide for anyone working with the data, whether they are members of the original research team, collaborators, or future researchers conducting secondary analyses. A well maintained data dictionary is a prerequisite for reproducibility, data sharing, and regulatory compliance.

Datasets without documentation become opaque surprisingly quickly. A variable named "v12_r" conveys no information about what it measures, how it was collected, or what its valid values are. When team members leave a project, when data are shared with collaborators at other institutions, or when a researcher returns to their own data after several years, the data dictionary is what makes the dataset interpretable. Archives such as ICPSR and the UK Data Service expect depositors to document every variable (its name, label, value codes and missing value codes), in a codebook or data dictionary or as labels embedded in the data files. In clinical trials, regulators expect the data to be fully described: the US FDA and Japan's PMDA, for example, require a data definition file (Define-XML) that describes the datasets, variables and controlled terms of each study in an electronic submission of standardized study data. Without a data dictionary, datasets that cost millions of dollars to collect can become effectively useless.

A data dictionary typically contains one row per variable and columns covering several key attributes. The variable name is the identifier used in the dataset file. The label is a plain language description (for example, "Systolic blood pressure at baseline visit"). The data type specifies whether the variable is numeric, categorical, string, date, or another format. Valid values describe the range or set of permissible entries, such as "0 to 300" for a blood pressure measurement or "1 = Male, 2 = Female, 3 = Other, 9 = Not reported" for a categorical variable. Units of measurement (mmHg, kg, years) are recorded for continuous variables. The source instrument or question identifies where the data point comes from, such as "Question 14 on the baseline survey" or "Lab result from central laboratory."

Additional information often includes how missing values are coded (some datasets use 999, others use blank cells, and others use specific codes like "NA" or negative values), any transformations or derivations applied (such as calculating BMI from height and weight), and skip patterns or conditional logic (for example, "collected only if Q10 = Yes"). Some data dictionaries also include the date the variable was added or modified and notes about known issues or caveats.

Data dictionaries should be created at the beginning of a study, alongside the study protocol and case report forms, and updated throughout the study as new variables are added, existing variables are modified, or coding decisions are revised. Formats range from simple spreadsheets (Excel or CSV) to structured metadata standards like DDI (Data Documentation Initiative). Some electronic data capture systems are built from the dictionary itself: a REDCap data dictionary is a CSV file that can be uploaded to create a project's data collection forms.

Every dataset used in research should have a data dictionary. This applies to datasets collected through primary research, datasets extracted from electronic health records, datasets compiled from multiple sources, and datasets created through systematic review data extraction. The data dictionary should be created before data collection begins and treated as a living document throughout the study. Data archives commonly expect variable level documentation at deposit, and regulators such as the US FDA require a data definition file with standardized study data submissions.

A common mistake is not creating a data dictionary at all, or creating one only at the end of the project when key details have been forgotten. Another error is creating a dictionary that documents variable names and types but omits critical information such as valid value ranges, missing value codes, and units of measurement. Researchers sometimes maintain the data dictionary in a separate file that becomes disconnected from the dataset, leading to version mismatches where the dictionary describes variables that no longer exist or fails to document newly added variables. Using jargon or abbreviations in variable descriptions without defining them defeats the purpose of the dictionary for external users. Finally, failing to document derived or computed variables leaves other researchers unable to reproduce calculated fields.

A REDCap database for a multicenter stroke recovery study includes a data dictionary with 280 variables. The entry for "mRS_discharge" specifies that it is an ordinal variable with values from 0 to 6 representing the modified Rankin Scale score at hospital discharge, with 99 coded as missing. The dictionary notes that the variable is collected by the treating physician, that inter rater training was conducted at study initiation, and that grading follows the structured interview for the modified Rankin Scale (Wilson and colleagues, 2002). Each site coordinator received a copy of the data dictionary during training, and updates are distributed quarterly.