A REDCap data dictionary is a CSV file that defines the complete structure of a REDCap project - every field's name, type, label, answer choices, branching logic, and validation rules. It is the primary way to create or modify a REDCap instrument in bulk, and can be downloaded from any existing project or uploaded to build a new one.
What a REDCap Data Dictionary Is
Every REDCap project's structure is defined by its data dictionary. Whether you build fields through the Online Designer (clicking through the interface) or by uploading a CSV file, REDCap stores the project structure as a data dictionary that can be downloaded at any time from Project Setup > Data Dictionary > Download the current Data Dictionary.
The data dictionary CSV has one row per field and columns that define every property of that field. Uploading a data dictionary to a new or existing project is the fastest way to build a complex instrument - significantly faster than clicking through the Online Designer for each of 40+ fields individually.
All 18 Data Dictionary Columns Explained
| Column Name | What Goes Here |
|---|---|
| Variable / Field Name | Unique identifier for the field. Lowercase letters, numbers, underscores only. No spaces. Max 26 characters. E.g. phq9_q1 |
| Form Name | Which instrument/form this field belongs to. Lowercase, underscored. E.g. depression_screen |
| Section Header | Optional bold header text displayed above this field in the form. Leave blank for no header. |
| Field Type | One of: text, notes, radio, checkbox, dropdown, calc, file, slider, yesno, truefalse, descriptive, sql |
| Field Label | The question text shown to the respondent. HTML supported. E.g. "Over the last 2 weeks, how often have you been bothered by little interest or pleasure in doing things?" |
| Choices, Calculations, OR Slider Labels | For radio/checkbox/dropdown: pipe-delimited choices. For calc: the formula. For slider: three labels separated by | |
| Field Note | Small helper text displayed below the field in grey. Optional. |
| Text Validation Type OR Show Slider Number | For text fields: date_mdy, date_dmy, integer, number, email, phone, zipcode, etc. For sliders: 'y' to show the numeric value. |
| Text Validation Min | Minimum accepted value for validated text fields (e.g. 0 for age) |
| Text Validation Max | Maximum accepted value for validated text fields (e.g. 120 for age) |
| Identifier? | y if this field contains identifiable information (name, DOB, MRN). Flags field for de-identification exports. |
| Branching Logic | Show this field only if a condition is met. E.g. [group]='2' - shows only for respondents in group 2. |
| Required Field? | y if the field must be answered before the form can be marked complete. |
| Custom Alignment | LH (left horizontal), LV (left vertical), RH (right horizontal), RV (right vertical). Controls layout. |
| Question Number (surveys only) | Auto-number displayed to respondents in survey mode. Leave blank to suppress numbering. |
| Matrix Group Name | Groups radio fields into a visual matrix table. All fields in the same Matrix Group Name display as a grid. |
| Matrix Ranking? | y for rank-order matrices where each column can only be selected once per row. |
| Field Annotation | Action tags or custom annotations. E.g. @HIDDEN, @CALCDATE, @DEFAULT='0'. For advanced use. |
REDCap Field Types
text - A single-line text entry box. Add validation type, min, and max to constrain input format (date, integer, number, email, phone).
notes - A multi-line text box for longer open-ended responses.
radio - Radio buttons for single-select questions. Define choices in the Choices column.
checkbox - Checkboxes for multi-select questions. Define choices in the Choices column. Each checkbox choice exports as a separate binary variable.
dropdown - A dropdown menu for single-select questions with long option lists.
calc - A calculated field. The formula in the Choices/Calculations column is evaluated automatically. Use for composite scores (PHQ-9 total = sum of items 1-9).
slider - A visual analog scale. Enter three pipe-delimited labels: left label | centre label | right label. Add 'y' in the Text Validation column to show the numeric value.
yesno - A fixed Yes/No radio. No choices needed.
truefalse - A fixed True/False radio. No choices needed.
descriptive - Display-only text or an embedded image. No response collected. Use for section instructions, informed consent text, or embedded media.
file - A file upload field. Respondents attach a file to the record.
How to Format Answer Choices
For radio, checkbox, and dropdown fields, choices are entered in the Choices column as pipe-delimited pairs of code and label:
1, Not at all | 2, Several days | 3, More than half the days | 4, Nearly every day
Each option is a numeric code, a comma, a space, then the label text. Options are separated by pipe characters with spaces on each side. The numeric codes are what REDCap stores in the database - the labels are what respondents and data entry staff see. Keep codes consistent across instruments for analysis (e.g. always code "Strongly Agree" as 5 on a 5-point scale).
Branching Logic Syntax
Branching logic in REDCap uses a specific expression syntax in the Branching Logic column. The field is shown only when the condition is true:
[field_name] = '1' (show if field equals 1) [field_name] <> '' (show if field is not empty) [field_a] = '1' AND [field_b] = '2' (AND condition) [field_a] = '1' OR [field_b] = '1' (OR condition) [checkbox___1] = '1' (show if checkbox option 1 is selected)
Field names are enclosed in square brackets. String values are enclosed in single quotes. Numeric comparisons can use =, <>, <, >, <=, >=. Checkbox field branching uses the triple-underscore syntax: [fieldname___code] = '1'.
Creating a Data Dictionary From a Survey Document
Building a data dictionary manually for a 40-item validated instrument takes 3-5 hours - selecting field types, typing labels verbatim, formatting choices in pipe-delimited syntax, writing branching logic expressions. Pirai AI generates the data dictionary CSV automatically from your Word, PDF, or Excel document. Upload at platform.piraiai.com, select REDCap, and download the pre-formatted CSV. Import via Project Setup > Data Dictionary > Upload File > Commit Changes. Review and refine in the Online Designer after import.
Common Data Dictionary Import Errors
Duplicate field name. Every variable name must be unique across the entire project. If two fields have the same name, the import fails. Prefix section-specific fields with a section code (e.g. phq9_q1, gad7_q1).
Invalid field name characters. Field names can only contain lowercase letters, numbers, and underscores. No spaces, hyphens, or uppercase letters. REDCap rejects names that violate this rule.
Malformed choices string. Missing pipe separators, missing commas between code and label, or inconsistent spacing cause choice parsing errors. The format must be exactly: 1, Label one | 2, Label two.
Branching logic referencing a non-existent field. If branching logic references a field name that does not exist in the data dictionary or project, the import fails. Check all field names in branching logic conditions against the Variable/Field Name column.
Frequently Asked Questions
A REDCap data dictionary is a CSV file that defines the complete structure of a REDCap project - every field's name, type, label, answer choices, branching logic, and validation rules. It can be downloaded from any existing REDCap project or uploaded to build a new instrument. It is the fastest way to create a complex survey instrument in REDCap.
REDCap choices are formatted as pipe-delimited code-label pairs: 1, Not at all | 2, Several days | 3, More than half the days | 4, Nearly every day. Each option starts with a numeric code, then a comma, then the label. Options are separated by space-pipe-space. This format applies to radio, checkbox, and dropdown field types.
Add REDCap branching logic expressions in the Branching Logic column. The syntax is [field_name] = 'value' - the field name in square brackets, equals sign, and the value in single quotes. Use AND/OR for multiple conditions. For checkbox fields, use [fieldname___code] = '1' to check whether a specific option is selected.
Yes. Upload your Word, PDF, or Excel survey document to Pirai AI, select REDCap as the target platform, and download the data dictionary CSV. Field types, labels, answer choices in pipe-delimited format, and branching logic are all populated from the source document. Import via Project Setup > Data Dictionary > Upload File in your REDCap project.
Deploy Your Survey to 27+ Platforms
Convert Word, PDF, and Excel survey instruments to Qualtrics, REDCap, SurveyMonkey, and more. No manual programming required.
Start Converting Free