Written and maintained by CASRAI Editorial Board
Last updated
REDCap organizes every field on every form in a project around one artifact: the Data Dictionary. It is the machine-readable specification of the project’s variables — every field’s name, type, choices, validation, and conditional logic, in one flat table. Understanding its structure matters for two very different jobs: editing a project without silently corrupting it, and moving a project from one REDCap instance to another when a researcher changes institutions.
This is REDCap-specific mechanics. For the general research-data-management concept a data dictionary implements — and how it differs from a codebook — see Data Dictionary in Research Data Management. For REDCap itself, see the REDCap dictionary term.
What the REDCap Data Dictionary actually is
Every REDCap project, at any given moment, has exactly one Data Dictionary: a table with one row per field and a fixed set of columns describing that field’s behavior. It is not a separate document you maintain alongside the project — it is the project’s design, expressed as data. The Online Designer (REDCap’s point-and-click form builder) and the Data Dictionary (the downloadable/uploadable spreadsheet) are two different interfaces onto the exact same underlying table.
Two consequences follow directly from that:
- Anything you can build in the Online Designer, you can also produce by editing the spreadsheet and uploading it — and vice versa.
- The REDCap API‘s
content=metadatacall exports this same table (field definitions, validation, branching logic) programmatically, which is how external scripts and wrapper libraries read a project’s structure without opening REDCap at all.
The 18 columns, and what each one does
The Data Dictionary has 18 fixed columns (A–R). Four are mandatory on every field; the rest are optional and only apply to specific field types or use cases.
| Column | Name | What it does |
|---|---|---|
| A | Variable / Field Name | The field’s unique internal identifier — lowercase letters, numbers, and underscores only, at least 2 characters, unique across the whole project. This is the name used in branching logic, calculations, exports, the API, piping, and smart variables. Mandatory. |
| B | Form Name | Which instrument (form) the field belongs to. Mandatory. |
| C | Section Header | Optional labeled divider bar displayed above the field on the form. |
| D | Field Type | Determines how the field is rendered — text box, radio, checkbox, dropdown, calculated field, etc. Mandatory. |
| E | Field Label | The question text shown to the person filling out the form. Mandatory. |
| F | Choices, Calculations, OR Slider Labels | Answer choices for a radio/dropdown/checkbox field, the formula for a calculated field, or the endpoint labels for a slider. Conditionally mandatory — required for the field types that need it, meaningless for a plain text field. |
| G | Field Note | Short instructional text displayed under the field. |
| H | Text Validation Type OR Show Slider Number | Validation format for a text field (date, integer, email, phone, etc.), or whether a slider shows its numeric value. |
| I | Text Validation Min | Minimum allowed value for a validated text field. |
| J | Text Validation Max | Maximum allowed value for a validated text field. |
| K | Identifier? | Flags the field as containing identifying information, which controls what a de-identified data export includes. |
| L | Branching Logic | The conditional-display expression that determines whether the field appears — see REDCap branching logic syntax for how to write it correctly. |
| M | Required Field? | Whether the form can be saved with this field left blank. |
| N | Custom Alignment | Display width and choice orientation (horizontal vs. vertical). |
| O | Question Number | Custom numbering, survey mode only. |
| P | Matrix Group Name | Groups multiple radio/checkbox fields into a single table-style matrix. |
| Q | Matrix Ranking? | Flags a matrix as a ranking question rather than an independent-choice grid. |
| R | Field Annotation | Free-text designer notes and/or REDCap action-tag codes (e.g. @READONLY, @HIDDEN). |
Editing it: the CSV spreadsheet vs. the Online Designer
There are two legitimate ways to change a project’s structure, and they write to the same underlying table — but they are not interchangeable in how they fail.
Data Dictionary (CSV) method
From Project Setup, download the current Data Dictionary as a spreadsheet, edit it in Excel or any spreadsheet tool, then upload the modified file. REDCap validates the upload and reports errors with row-level detail before committing anything. This method is the fast path for bulk changes — renaming many fields, adding a block of new variables, or restructuring choice lists — where clicking through the Online Designer field-by-field would be slow.
Online Designer (GUI) method
The point-and-click form builder edits one field at a time with a guided interface, and is the safer default for occasional, single-field changes, especially for anyone not comfortable hand-editing a CSV’s Field Type or Text Validation columns correctly.
The rule that avoids losing work
Use only one method at a time, and coordinate with any co-designers before switching. Uploading a CSV overwrites the current dictionary wholesale — if someone else made changes through the Online Designer since you downloaded your copy, uploading your CSV silently discards theirs. There is no merge step.
The upload validator catches technical errors (malformed field names, invalid Field Type values, orphaned branching-logic references) but does not check whether the instrument design makes clinical or scientific sense — that is still the designer’s judgment call.
The deletion trap: any variable that exists in the live project but is absent from the CSV you upload gets deleted, along with any data already collected for it. If your working copy of the dictionary is stale — downloaded before a field was added by someone else, or before you added one yourself in a separate session — uploading it can silently remove a field and its data. Always download a fresh copy of the dictionary immediately before editing it, not one you saved days earlier.
Moving a project to a different REDCap institution
REDCap is not a single hosted service with one account system — it is licensed per institution through the non-profit REDCap Consortium, and each institution runs its own separate instance (see the REDCap dictionary term for the access model). “Moving a project between institutions” therefore always means recreating it inside a different, separately-administered instance — there is no single-click transfer between two institutions’ REDCap servers. Two methods do this, at different levels of completeness.
XML export/import (Other Functionality tab)
From the source project’s “Other Functionality” tab, exporting the full project as XML captures both metadata (the complete Data Dictionary, including branching logic, validation, and matrix groupings) and, optionally, the data itself, plus arms/events for a longitudinal project. On the destination instance, creating a new project from that XML file rebuilds the full structure in one step. This is the more complete of the two routes and is the one to prefer whenever the destination REDCap version and configuration support importing the file cleanly.
Data Dictionary CSV + separate data export
Where a full XML import is not accepted or not appropriate, the alternative is to download the Data Dictionary as a CSV from Project Setup, download events/arms separately if the project has them, and export the data itself as a raw-data CSV from the data-export tool. On the destination instance, create a new (blank) project and upload the Data Dictionary CSV to rebuild the instrument design, then import the data. This route is more manual and loses anything that lives outside the dictionary/data/events triad — user accounts and their permissions, data-access-group assignments, and File Upload field contents (see the REDCap API guide‘s note that files require a separate per-record export; there is no bulk file-export call) all have to be recreated or moved by hand on the new instance.
Either way, plan the move as a structural migration, not a copy: confirm with the destination institution’s REDCap administrator which import path their instance supports, and verify the rebuilt project’s branching logic and calculated fields against the original before retiring it — a field referencing a checkbox or an event by the wrong internal name will silently evaluate as blank rather than error, the same failure mode covered in the branching logic guide.
Frequently asked questions
Can I edit the Data Dictionary and the Online Designer at the same time?
Not safely. Both write to the same underlying table, but a CSV upload overwrites the dictionary wholesale rather than merging changes — use one method at a time and coordinate with co-designers.
What happens if I delete a row from the Data Dictionary CSV before uploading it?
The corresponding field, and any data already collected for it, is deleted from the project on upload. There is no separate “delete field” confirmation step at that point — the upload treats an absent row as an instruction to remove the field.
Does REDCap check whether my instrument design makes sense before accepting an upload?
No. The validator checks technical correctness — valid field names, valid Field Type values, branching logic that references real fields — not clinical or scientific soundness of the design.
Is there a one-click way to move a project to another institution’s REDCap?
No. Because each institution runs its own separately-licensed instance, moving a project always means exporting it (as project XML, or as a Data Dictionary CSV plus a separate data export) from the source and rebuilding it on the destination instance.
