> ## Documentation Index
> Fetch the complete documentation index at: https://docs.carelane.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Questionnaires

> Structure and behavior of data collection forms

Questionnaires are the primary data collection instruments in Carelane. They define the structure of case report forms (CRFs) used to capture participant data.

## Questionnaire Structure

### Hierarchy

Questionnaires are organized hierarchically:

```
Questionnaire
├── Group (Section)
│   ├── Item (Field)
│   ├── Item (Field)
│   └── Nested Group
│       └── Item (Field)
```

### Components

| Component         | Description                        |
| ----------------- | ---------------------------------- |
| **Questionnaire** | The complete form                  |
| **Group**         | A section containing related items |
| **Item**          | An individual field or question    |

## Item Types

### Text Items

| Type       | Description          |
| ---------- | -------------------- |
| **String** | Single-line text     |
| **Text**   | Multi-line text area |

### Numeric Items

| Type         | Description                 |
| ------------ | --------------------------- |
| **Integer**  | Whole numbers               |
| **Decimal**  | Numbers with decimal places |
| **Quantity** | Value with unit             |

### Date/Time Items

| Type         | Description            |
| ------------ | ---------------------- |
| **Date**     | Calendar date          |
| **Time**     | Time of day            |
| **DateTime** | Combined date and time |

### Choice Items

| Type            | Description                    |
| --------------- | ------------------------------ |
| **Choice**      | Single selection from options  |
| **Open Choice** | Choice with optional free text |
| **Boolean**     | Yes/No selection               |

For both single-choice and multiple-choice questions, study designers can pick how options are rendered to participants and site users:

| Display         | When to use                                                                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **As list**     | Default. Shows every option as a radio button (single-choice) or checkbox (multiple-choice). Best for short option lists where all choices should be visible at a glance.     |
| **As dropdown** | Collapses options into a select menu. Best for long option lists (for example, country, medication, or coded value pickers) where the list would otherwise dominate the form. |

To change the display, open the question in the questionnaire editor and use the **Display** toggle above the option list. The setting is stored on the question and applies wherever the CRF is rendered — data entry, preview, and participant-facing forms. Selected values can be cleared by reopening the dropdown and deselecting them, and every change to a question's display control is captured in the questionnaire audit trail.

### Special Items

| Type           | Description                 |
| -------------- | --------------------------- |
| **Attachment** | File upload                 |
| **Display**    | Read-only text/instructions |
| **Calculated** | Auto-computed value         |

## Validation Rules

### Built-in Validation

| Rule               | Description               |
| ------------------ | ------------------------- |
| **Required**       | Field must have a value   |
| **Min/Max Length** | Text length constraints   |
| **Min/Max Value**  | Numeric range constraints |
| **Decimal Places** | Maximum decimal digits    |
| **Pattern**        | Regex pattern matching    |

### Custom Validation

Questionnaires can include custom validation:

* Cross-field validation
* Conditional requirements
* Business rule checks

## Conditional Logic

### Enable When

Fields can be conditionally displayed:

```
If [QuestionA] = "Yes"
Then show [QuestionB]
```

### Enable Behavior

When multiple conditions exist:

| Behavior | Logic                       |
| -------- | --------------------------- |
| **All**  | All conditions must be true |
| **Any**  | Any condition can be true   |

<Accordion title="How Conditions Work">
  When a field has enable conditions, it's hidden until conditions are met. Changing answers updates field visibility dynamically.
</Accordion>

## Calculated Fields

Fields that compute values automatically:

### Types of Calculations

* Sum of other fields
* Averages and scores
* Derived values (e.g., BMI)
* Date differences

### Calculation Expressions

Calculations use FHIRPath expressions to reference other fields and perform computations.

<Note>
  Calculated fields update automatically when source values change. Users cannot manually edit calculated values.
</Note>

## Repeating Groups

Some sections can repeat:

* Multiple medications
* Multiple adverse events
* Repeated assessments

### How Repeating Works

1. User clicks "Add" to create a new instance
2. All items in the group repeat
3. Each instance has unique data
4. Instances can be removed if allowed

## Instructions and Help

### Display Items

Read-only text providing:

* Section instructions
* Field-level guidance
* Reference information

### Help Text

Individual fields can have:

* Tooltip help
* Extended descriptions
* Coding guidelines

## Questionnaire Templates

Questionnaires are typically created from templates:

1. Create template in organization library
2. Import template into study
3. Customize for study-specific needs

See [Questionnaire Templates](/templates/questionnaire-templates) for creating templates.

## Version Control

Questionnaires support versioning:

* Track changes over time
* Multiple versions can exist
* Active version used for data entry

<Warning>
  Changing questionnaire structure after data collection may require migration or amendment processes.
</Warning>

## FHIR Foundation

Questionnaires are built on HL7 FHIR:

* Standard Questionnaire resource
* QuestionnaireResponse for data
* Interoperable structure

## Best Practices

<AccordionGroup>
  <Accordion title="Clear Labels">
    Use clear, unambiguous labels for all fields.
  </Accordion>

  <Accordion title="Logical Grouping">
    Group related fields together in logical sections.
  </Accordion>

  <Accordion title="Appropriate Types">
    Choose field types that match the expected data.
  </Accordion>

  <Accordion title="Validation">
    Add validation to catch errors early in the process.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Data Entry" icon="keyboard" href="/data-collection/data-entry">
    How to enter data in questionnaires.
  </Card>

  <Card title="Questionnaire Templates" icon="copy" href="/templates/questionnaire-templates">
    Create reusable questionnaire templates.
  </Card>
</CardGroup>