The REDCap Data Dictionary is a CSV file that bulk-creates all fields in your REDCap project at once. There are two ways to build it: manually in Excel (time-consuming, error-prone for instruments with complex choice coding) or automatically using Pirai AI (upload any document, download the Data Dictionary in minutes). This guide covers both methods.
Method 1 - Manual Data Dictionary Build in Excel
For small instruments (under 10 fields), building the Data Dictionary manually in Excel is feasible. For larger instruments or instruments with many radio/checkbox fields, the pipe-delimited choices formatting makes manual build error-prone.
Step 1 - Download the template. In any REDCap project, go to Project Setup > Data Dictionary > Download the current Data Dictionary. This gives you the correct 18-column CSV headers. Open in Excel.
Step 2 - Enter each field. One row per field. Key columns to fill: Variable/Field Name (lowercase, underscores), Form Name (matches your instrument name), Field Type (radio, checkbox, text, notes, etc.), Field Label (verbatim question text), and for radio/checkbox fields: the Choices column in pipe-delimited format (1, Option A | 2, Option B).
Step 3 - Save as CSV. File > Save As > CSV (Comma delimited). Do not save as .xlsx - REDCap will reject it.
Step 4 - Import. In REDCap: Project Setup > Data Dictionary > Upload File > select your CSV > Commit Changes.
Time for a 40-field instrument: 4-6 hours. Main bottleneck: manually formatting each radio/checkbox field's Choices column with correct pipe-delimited syntax. One missed pipe or incorrectly formatted code-label pair causes an import error on that field.
Method 2 - Pirai AI Automated Build
Step 1 - Upload your instrument. Go to platform.piraiai.com. Upload your Word document, PDF (enable Advanced PDF Processing for scanned documents), or Excel file.
Step 2 - Review in the workspace. Every extracted question appears with its detected field type and answer options. Verify field types and question wording before generating the Data Dictionary. The workspace shows the pipe-delimited choices format as it will appear in the CSV.
Step 3 - Select REDCap and download. Click REDCap as the output platform. Download the Data Dictionary CSV. All 18 columns populated - including correctly formatted pipe-delimited choices for every radio, checkbox, and dropdown field.
Step 4 - Import into REDCap. Project Setup > Data Dictionary > Upload File > select the CSV > Commit Changes. All fields created instantly.
Step 5 - Complete in Online Designer. After import, open the Online Designer to add branching logic, set required fields, configure validation rules, and adjust any field details the automated conversion flagged for review.
Time for a 40-field instrument: 15-20 minutes.
Common Data Dictionary Import Errors
| Error | Cause and Fix |
|---|---|
| Invalid field type | Field Type column contains a value REDCap does not recognise. Check spelling: radio, checkbox, text, notes, dropdown, yesno, truefalse, slider, calc, descriptive, file |
| Duplicate variable name | Two rows have the same Variable/Field Name. Variable names must be unique across the whole project. |
| Invalid variable name | Variable/Field Name contains spaces, capital letters, or special characters. Use lowercase letters, numbers, and underscores only. |
| Invalid choices format | Choices column not formatted as pipe-delimited pairs. Must be: 1, Label | 2, Label (space after comma, space around pipe) |
| Blank required column | Variable/Field Name or Field Type column is empty. Every row must have both. |
After Importing - What to Configure Manually
After the Data Dictionary import creates all fields, configure these in the Online Designer: branching logic (conditional display of fields based on previous answers), required field settings, text validation (min/max values, date formats), identifier flags for PHI fields, and field annotations (action tags like @DEFAULT or @HIDDEN). These are not part of standard Data Dictionary automation and require manual configuration per study protocol.
Frequently Asked Questions
Upload your Word document to Pirai AI at platform.piraiai.com. Select REDCap. Download the generated Data Dictionary CSV with all 18 columns populated. Import via REDCap Project Setup > Data Dictionary > Upload File > Commit Changes. All fields are created instantly. Alternative: build manually in Excel using the 18-column format, but this takes 4-6 hours for a 40-field instrument.
REDCap Data Dictionaries must be CSV files (.csv), not Excel (.xlsx). If you build or edit in Excel, save as File > Save As > CSV (Comma delimited) before importing. REDCap will reject .xlsx files. Pirai AI generates the Data Dictionary as a correctly formatted .csv file ready for direct import.
A 40-field instrument takes 4-6 hours to build manually in Excel - the main bottleneck being the pipe-delimited choices formatting for radio, checkbox, and dropdown fields. With Pirai AI, the same instrument takes 15-20 minutes including upload, review, and import.
After import creates all fields, open the Online Designer to add: branching logic (conditional field display), required field settings, text validation rules (date formats, number ranges), identifier flags for PHI fields, and action tag annotations. These are configured per study protocol and cannot be automated from document text alone.
Build Your REDCap Data Dictionary in 15 Minutes
Upload Word, PDF, or Excel. Pirai AI generates all 18 columns with pipe-delimited choices. Download and import. Free daily credits.
Start Converting Free