Develop REDCap Instruments

This section provides a guide for developing REDCap instruments around the RareLink-CDM: that can also be processed by the Phenopacket and FHIR pipeline. If the rules are followd upon development of the REDCap sheets, mapping and setup steps will be required to convert the data into the Phenopackets or FHIR format. For example, see the section Usage for other REDCap data models of the rarelink-phenopacket-module.

REDCap instrument structure

A REDCap instrument is a collection of fields that are grouped together to collect data for a specific purpose. The fields can be of different types, such as text fields, radio buttons, checkboxes, etc. The fields can be grouped into sections, and the sections can be repeated for a specific number of times. The fields can also be validated using REDCap’s integrated validators.

REDCap-inherent rules

REDCap variables and choice codes have specific limitations and requirements you should or must comply with when creating your REDCap shets.

REDCap recommends a maximum of 26 characters for variable names. If possible, you should shorten the variable names to adhere to this limit.
REDCap variables must be unique and must not contain spaces or special characters, therefore only alphanumeric characters and underscores are allowed.

RareLink obligatory rules

1) Data element output

The output (i.e. the answer) to each question in your REDCap instrument MUST be encoded with Ontologies & Terminologies codes or pass on a validated data field! This is crucial, so that the output of a data element is a code or a validated format that can be processed by the RareLink framework.

… in regard to the different REDCap field types:

Single Choice Dropdown & Radio-Button fields: the choices (i.e. the data elemen’ts value set) must be encoded with Ontologies & Terminologies codes, their official BIOPORTAL prefixes and their respective preferred labels.

e.g.: snomedct_32218000 or hp_5200403.

Checkboxes (Multiple Answers)fields CANNOT be processed by the RareLink framework and should not be used. Even if the choices are encoded with ontology codes, the output are `1` or `0` for each choice while altering the variable names.

Text fields: can be used for free text input, but the data must either…

use REDCap’s integrated validators, for example for dates, numbers, etc.

A string or text should only be used when the target data element in HL7 FHIR or GA4GH Phenopackets is a string or text field.

or use an integrated BioPortal validation service to validate the free text input. If you cannot see this option in your REDCap setup, contact you REDCap administrator. This can be set free of charge.

2) REDCap expression repository

REDCap expression repository: for exporting data to FHIR or Phenopackets, you will always need the versions of the Ontologies & Terminologies you are using. REDCap does not natively include an expression repository, however you can use the Field Annotations field in each data element to store the version of the ontology or terminology you are using. You can also use an Excel or word sheet, but we recommend keeping these in there so that they are part your project’s REDCap data dictionary.

Like our RareLink-CDM, you can also convert your model into a LinkML Schema which also provides the possibility to dedicating a section to the codesystems used. (CAVE: this requires coding experince).
To give more context to the data element, you can also include the mapping to the FHIR expression or the GA4GH Phenopacket Schema element, like in the example below.

Variable:
HP:0012824 | Severity
Choices:
- HP:0012827 | Borderline
- HP:0012825 | Mild
- HP:0012826 | Moderate
- HP:0012829 | Profound
- HP:0012828 | Severe
Version(s):
- HPO Version 2026-02-16
Mapping:
- HL7 FHIR Expression v4.0.1: Observation.interpretation
- GA4GH Phenopacket Schema v2.0 Element: PhenotypicFeature.severity

RareLink optional rules

The REDCap variable names should also be encoded with Ontologies & Terminologies codes and their respective preferred labels and using their official prefix (e.g. hp_, snomedct_, etc.) so that the concept of an element itself is clear. Also, sometimes FHIR requires a CodeableConcept for a specific element.
If you include the codes in the variable names, you can use suffixes to differentiate between the codes and the variable names. For example, snomedct_123456_onset, or snomedct_123456_age.
For repeating sections, we recommend using the REDCap Repeating Instruments feature for separate instruments, which allows you to repeat a section of questions for a specific number of times. See Set up the Data Dictionary for more information on how to activate this feature.

Return to top.