Working …
This value you provided is not a number. Please try again.
This value you provided is not an integer. Please try again.
The value entered is not a valid Vanderbilt Medical Record Number (i.e. 4- to 9-digit number, excluding leading zeros). Please try again.
The value you provided must be within the suggested range
The value you provided is outside the suggested range
This value is admissible, but you may wish to double check it.
The value entered must be a time value in the following format HH:MM within the range 00:00-23:59 (e.g., 04:32 or 23:19).
This field must be a 5 or 9 digit U.S. ZIP Code (like 94043). Please re-enter it now.
This field must be a 10 digit U.S. phone number (like 415 555 1212). Please re-enter it now.
This field must be a valid email address (like joe@user.com). Please re-enter it now.
The value you provided could not be validated because it does not follow the expected format. Please try again.
Required format:
REDCap Logo
Plugins, Hooks, & External Modules
Developer methods for
Plugins, Hooks, & External Modules
Hook functions

REDCap Developer Tools:
Documentation for Plugins, Hooks, & External Modules

REDCap Version 14.9.1
REDCap::getDataDictionary
(REDCap >= 6.8.0)
REDCap::getDataDictionary — Returns the Data Dictionary of fields for a given project
Description
mixed REDCap::getDataDictionary ( [ int $project_id, ] [ string $returnFormat = 'csv' [, bool $exportCsvHeadersAsLabels = TRUE [, mixed $fields = NULL [, mixed $instruments = NULL [, bool $draftMode = FALSE ]]]]] )
Returns the Data Dictionary (i.e., metadata) of fields for a given project in a specified format. If $fields parameter is supplied as an array (or a string as a single field), it will only return those fields.
Parameters
project_id (optional)
The project ID number of the REDCap project from which to pull metadata. If not provided in a project-level plugin, it will assume the current project ID of the plugin and will also infer return_format to be the first parameter passed to the method. If project_id is not provided in a system-level plugin, it will throw a fatal error.
returnFormat
The format in which the Data Dictionary should be returned. Valid options: 'array', 'csv', 'json', and 'xml'. By default, 'csv' is used.
exportCsvHeadersAsLabels
Sets the format of the CSV headers returned (only applicable to 'csv' return formats). If FALSE, it returns the unique header names (with lowercase letters and underscores) - e.g., "field_name". If TRUE, it returns the human-readable text as the headers (as seen when downloading the Data Dictionary in the normal web interface) - e.g., "Variable / Field Name". By default, TRUE is used, but if returnFormat is not 'csv', then it is set to FALSE automatically.
fields
An array of field variable names, or alternatively a single field variable name (as a string). This will limit the Data Dictionary returned to only those fields specified. By default, NULL is used, which will return all fields from the given project. NOTE: The "fields" and "instruments" parameters are additive and can be used together.
instruments
If provided as an array of data collection instrument names (i.e. the unique name, not the instrument label), it will limit the Data Dictionary returned to only those instruments specified. If provided as a single instrument name (string), it will limit the Data Dictionary returned to only the specified instrument. By default, NULL is used, in which it will return all fields for the entire project. NOTE: The "fields" and "instruments" parameters are additive and can be used together.
draftMode
If set to TRUE while the project is in production status *and* in draft mode, it will return the drafted changes of the Data Dictionary that have not yet been appproved for production use. If FALSE, it returns the normal Data Dictionary of fields that are in use. By default, FALSE is used.
Return Values
Returns the Data Dictionary of fields in the specified format. Note: If returnFormat is 'array', the array key of each field will be the field's "field_name".
Examples
Example #1:
This example shows how one can obtain an array of all fields and their attributes for a project to perform a specific action for each field.
// Get the data dictionary for the current project in array format
$dd_array = REDCap::getDataDictionary('array');

// Loop through each field and do something with each
foreach ($dd_array as $field_name=>$field_attributes)
{
    // Do something with this field if it is a checkbox field
    if ($field_attributes['field_type'] == "checkbox") {
        // Something

    }
}
Example #2:
This example shows how one can get the data dictionary in CSV format just like one would download via the normal web interface for project_id=545.
// Get the CSV data dictionary with labels
$dd_csv = REDCap::getDataDictionary(545);
Example #3:
Get the data dictionary of drafted changes in JSON format for project_id=1124.
// Get the drafted changes in JSON format
$dd_json = REDCap::getDataDictionary(1124, 'json', false, null, null, true);
Example #4:
Get an array of just two fields for the current project.
// Get two fields' attributes as an array
$fields = array('dob', 'mrn');
$dd_array = REDCap::getDataDictionary('array', false, $fields);
REDCap 14.9.1 - © 2024 Vanderbilt University