## Questionnaires

Questionnaires are used to organize a collection of questions to gather healthcare information and are modeled in FHIR as a [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html) resource. The responses to these questions are modeled with the [`QuestionnaireResponse`](/content/docs/api/fhir/resources/questionnaireresponse/index.html) resource.

## Creating a Questionnaire [​](/content/docs/questionnaires/questionnaires-and-responses#creating-a-questionnaire "Direct link to Creating a Questionnaire"/index.html)

A [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html) represents the questions, rules for answering the questions, and metadata used to define what it should be used for. It allows you to create complex forms with nested and conditional questions.

| **Element** | **Description** | **Code System** | **Example** |
| --- | --- | --- | --- |
| `title` | A _human-readable_ name to identify the `Questionnaire`. |  | US Surgeon General - Family Health Portrait |
| `name` | A _computer-readable_ name to identify the `Questionnaire`. |  | USSurgeonGeneralFamilyHealthPortrait |
| `item` | An object containing the questions and groups of questions. Also includes any rules defined for answering. |  | [See below](/content/docs/questionnaires/questionnaires-and-responses#defining-the-questions/index.html) |
| `subjectType` | The resource types that can be a subject of this `Questionnaire`. |  | Patient |
| `description` | A description of the `Questionnaire`. It can include instructions, examples, comments about misuse, etc. |  | Questions to get a picture of family health and family health history. |
| `purpose` | An explanation of _why_ the `Questionnaire` is needed. |  | Captures basic family history information. |
| `status` | Defines the stage of its lifecycle a `Questionnaire` is in (e.g. active, in a draft, etc.). | [Publication Status Codes](https://www.hl7.org/fhir/valueset-publication-status.html) | draft |

### Defining the Questions [​](/content/docs/questionnaires/questionnaires-and-responses#defining-the-questions "Direct link to Defining the Questions"/index.html)

The actual questions on a [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html) are defined in the `item` element. This element allows you to structure your questions both as individual questions and in groups. You can also provide additional context or instructions on how the questions should be answered.

One of the most important properties in the `item` is `linkId`, which is used to link the questions to the corresponding answers on a [`QuestionnaireResponse`](/content/docs/api/fhir/resources/questionnaireresponse/index.html) resource. These must all be unique within the [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html) to ensure that there is no ambiguity.

| **Property** | **Description** | **Example** |
| --- | --- | --- |
| `linkId` | A unique identifier within the `Questionnaire` that maps directly to the answer for the equivalent `item` on a `QuestionnaireResponse`. | gender |
| `text` | The text of the question or name of a group of questions. | What is your date of birth? |
| `type` | The type of `item` this is. This could be a group, or could refer to the datatype that is used to answer the question. | date |
| `item` | Another `item` used when making groups or nested questions. | [See below](/content/docs/questionnaires/questionnaires-and-responses#nesting-questions/index.html) |
| `answerValueSet` | A reference to an external value set containing possible answers for the question. | [http://hl7.org/fhir/ValueSet/yesnodontknow](http://hl7.org/fhir/ValueSet/yesnodontknow) |
| `answerOption` | An array of possible answers for the question. |  |
| `initial` | A value that will pre-populate a free-form field when the question renders. | 1970-01-01 |
| `initialSelected` | A value that will pre-populate the field of an `answerOption` type question when the question renders. | male |
| `required` | A boolean indicating if the question must be answered. | false |
| `repeats` | A boolean indicating if the question may have more than one associated answer. | true |

### Example: A basic `Questionnaire`

```ts
{

resourceType: 'Questionnaire',

id: 'example-questionnaire',

status: 'draft',

title: 'Patient Health Questionnaire',

description: 'A questionnaire to gather basic health information from the patient',

item: [

{

linkId: 'full-name',

text: 'Patient Full Name',

type: 'string',

required: true,

},

{

linkId: 'age',

text: 'Patient Age',

type: 'integer',

},

{

linkId: 'gender',

text: 'Patient Gender',

type: 'choice',

answerOption: [

{

valueCoding: {

code: 'female',

},

},

{

valueCoding: {

code: 'male',

},

},

],

},

{

linkId: 'medications',

text: 'Current Medications',

type: 'string',

repeats: true,

},

{

linkId: 'allergies',

text: 'Known Allergies',

type: 'string',

repeats: true,

},

{

linkId: 'exercise',

text: 'Weekly Exercise Frequency',

type: 'integer',

},

{

linkId: 'smoking',

text: 'Smoking Status',

type: 'reference',

answerValueSet: 'http://loinc.org/LL22201-3',

},

],

};
```

### Nesting Questions [​](/content/docs/questionnaires/questionnaires-and-responses#nesting-questions "Direct link to Nesting Questions"/index.html)

The `item` element allows you to group and nest questions together by adding additional sub-questions on the `item.item` field.

To do this, you must set `item.type='group'`. This specifies that the item will not be a question, but instead a group of questions. When defining a group, the `text` property should be a description of the group instead of an actual question.

### Example: A `Questionnaire` with nested questions

```ts
{

resourceType: 'Questionnaire',

id: 'nested-questionnaire',

status: 'active',

subjectType: ['Patient'],

item: [

{

linkId: 'allergies',

text: 'Do you have allergies?',

type: 'boolean',

},

{

linkId: 'general',

text: 'General Information',

type: 'group',

item: [

{

linkId: 'general.gender',

text: 'What is your gender?',

type: 'choice',

answerOption: [

{

valueCoding: {

code: 'female',

},

},

{

valueCoding: {

code: 'male',

},

},

],

},

{

linkId: 'general.dob',

text: 'What is your date of birth?',

type: 'date',

},

{

linkId: 'general.marital',

text: 'What is your marital status?',

type: 'choice',

answerOption: [

{

valueCoding: {

code: 'married',

},

},

{

valueCoding: {

code: 'single',

},

},

],

},

],

},

{

linkId: 'intoxicants',

text: 'Intoxicants',

type: 'group',

item: [

{

linkId: 'intoxicants.smoking',

text: 'Do you smoke?',

type: 'boolean',

},

{

linkId: 'intoxicants.alcohol',

text: 'Do you drink alcohol?',

type: 'boolean',

},

],

},

],

};
```

### Defining Rules For Your Questions [​](/content/docs/questionnaires/questionnaires-and-responses#defining-rules-for-your-questions "Direct link to Defining Rules For Your Questions"/index.html)

FHIR allows you to set rules for your questions beyond just providing options for the answer. The two main rules that you can define are:

- Setting initial values
- Conditionally enabling/disabling certain questions

### Initial Values [​](/content/docs/questionnaires/questionnaires-and-responses#initial-values "Direct link to Initial Values"/index.html)

To set an initial value for your question, you can use the `item.initial` or `item.initialSelected` field.

The `initial` property can be set to any value type, but should be the same as the `type` field of the item it is on. It can be overwritten by the user responding to the [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html), but the value will persist if the user does not change it.

The `initialSelected` field works in the same way, but applies to questions that have an `answerOption` field, and is a property on that field (i.e. `answerOption.initialSelected`). In this case you set an initial choice that is automatically selected when a question renders.

### Conditionally Displaying Questions [​](/content/docs/questionnaires/questionnaires-and-responses#conditionally-displaying-questions "Direct link to Conditionally Displaying Questions"/index.html)

You can conditionally display questions so that they only appear based on a user's answer to a different question. This is done using the `item.enableWhen` field. The `enableWhen` property is an object with properties that define when a question should be displayed.

| **Property** | **Description** | **Code System** | **Example** |
| --- | --- | --- | --- |
| `question` | The `linkId` for the `item` whose answer determines if this `item` will appear. |  | gender |
| `operator` | The criteria used to determine if the question will appear. | [Questionnaire Item Operator](https://www.hl7.org/fhir/valueset-questionnaire-enable-operator.html) | = |
| `answer[x]` | The value that the referenced question is being tested against using the `operator`. The datatype should match the answer datatype of the referenced question. |  | female |

### Example: A `Questionnaire` with initial values and conditionally rendered questions

```ts
{

resourceType: 'Questionnaire',

id: 'conditional-questionnaire',

status: 'active',

subjectType: ['Patient'],

item: [

{

linkId: 'allergies',

text: 'Do you have allergies?',

type: 'boolean',

},

{

linkId: 'general',

text: 'General Information',

type: 'group',

item: [

{

linkId: 'general.gender',

text: 'What is your gender?',

type: 'choice',

answerOption: [

{

valueCoding: {

code: 'female',

},

},

{

valueCoding: {

code: 'male',

},

},

],

},

{

linkId: 'general.dob',

text: 'What is your date of birth?',

type: 'date',

},

{

linkId: 'general.birth-country',

text: 'What is your country of birth?',

type: 'string',

initial: [

{

valueString: 'United States',

},

],

},

{

linkId: 'general.marital',

text: 'What is your marital status?',

type: 'choice',

answerOption: [

{

valueCoding: {

code: 'married',

},

},

{

valueCoding: {

code: 'single',

},

},

],

},

],

},

{

linkId: 'intoxicants',

text: 'Intoxicants',

type: 'group',

item: [

{

linkId: 'intoxicants.smoking',

text: 'Do you smoke?',

type: 'boolean',

},

{

linkId: 'intoxicants.alcohol',

text: 'Do you drink alcohol?',

type: 'boolean',

},

],

},

{

linkId: 'pregnancy',

text: 'Pregnancy History',

type: 'group',

item: [

{

linkId: 'pregnancy.boolean',

text: 'Have you ever been pregnant?',

type: 'boolean',

},

{

linkId: 'pregnancy.count',

text: 'How many times have you been pregnant?',

type: 'integer',

enableWhen: [

{

question: 'pregnancy.boolean',

operator: '=',

answerBoolean: true,

},

],

},

],

enableWhen: [

{

question: 'general.gender',

operator: '=',

answerCoding: {

code: 'female',

},

},

],

},

],

};
```

## Creating a Response to a Questionnaire [​](/content/docs/questionnaires/questionnaires-and-responses#creating-a-response-to-a-questionnaire "Direct link to Creating a Response to a Questionnaire"/index.html)

Once you have created your [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html), you will need to record responses to it. This is modeled with the [`QuestionnaireResponse`](/content/docs/api/fhir/resources/questionnaireresponse/index.html) resource.

Each [`QuestionnaireResponse`](/content/docs/api/fhir/resources/questionnaireresponse/index.html) represents an _individual response_ to a [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html). An individual response could be one response per person or the same person responding multiple times to the same [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html) over the course of their care.

### Structuring Answers

The answer items in a [`QuestionnaireResponse`](/content/docs/api/fhir/resources/questionnaireresponse/index.html) should follow the same structure in terms of grouping and nesting and adhere to all data types for answers defined in the linked [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html).

The [`QuestionnaireResponse`](/content/docs/api/fhir/resources/questionnaireresponse/index.html) resource provides fields to define meta data about the responses, such as who provided the answers, recorded the answers, and more.

| **Element** | **Description** | **Code System** | **Example** |
| --- | --- | --- | --- |
| `questionnaire` | The canonical URL of the `Questionnaire` that is being answered by this response. |  | [http://example.org/Questionnaires/example-questionnaire](http://example.org/Questionnaires/example-questionnaire) |
| `source` | The individual who provided the answers on this response. |  | Patient/homer-simpson |
| `subject` | Who/what the answers from the response apply to, but not necessarily who actually answered the questions. |  | Patient/maggie-simpson |
| `item` | The responses to the questions. |  | [See below](/content/docs/questionnaires/questionnaires-and-responses#answering-the-questions/index.html) |
| `author` | The individual who received and recorded the responses, but not necessarily who actually answered the questions. |  | Practitioner/receptionist |
| `authored` | The date that the answers were gathered. | dateTime | 2023-11-18 |
| `encounter` | A reference to the `Encounter` that the response is a part of. |  | Encounter/maggie-simpson-physical |

### Answering the Questions [​](/content/docs/questionnaires/questionnaires-and-responses#answering-the-questions "Direct link to Answering the Questions"/index.html)

The answers on a [`QuestionnaireResponse`](/content/docs/api/fhir/resources/questionnaireresponse/index.html) are stored in the `item` element. It is very similar to the `item` element on a [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html), allowing you to model the responses so that they match the structure of the [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html) they are answering.

| **Property** | **Description** | **Example** |
| --- | --- | --- |
| `answer.value[x]` | The answer to the question. The datatype should correspond to what is specified in the `Questionnaire.item` | female |
| `answer.item` | Any nested answers or groups within the current one. Only used when nesting underneath an answer. |  |
| `text` | The text of the question that is being answered. | What is your gender? |
| `item` | An additional item that allows for grouping or nesting answers. |  |
| `linkId` | The item from the corresponding `Questionnaire` that this answer responds to. | marital-status |

### Example: A `QuestionnaireResponse` responding to the [conditional questionnaire above](/content/docs/questionnaires/questionnaires-and-responses#conditionally-displaying-questions/index.html)

```ts
{

resourceType: 'QuestionnaireResponse',

id: 'homer-simpson-conditional-response',

status: 'completed',

questionnaire: 'http://example.org/Questionnaires/conditional-questionnaire',

subject: {

reference: 'Patient/homer-simpson',

},

author: {

reference: 'Patient/homer-simpson',

},

authored: '2023-11-18',

source: {

reference: 'Patient/homer-simpson',

},

item: [

{

linkId: 'allergies',

text: 'Do you have allergies?',

answer: [

{

valueBoolean: false,

},

],

},

{

linkId: 'general',

text: 'General Information',

item: [

{

linkId: 'general.gender',

text: 'What is your gender?',

answer: [

{

valueCoding: {

code: 'M',

},

},

],

},

{

linkId: 'general.dob',

text: 'What is your date of birth?',

answer: [

{

valueDate: '1956-05-12',

},

],

},

{

linkId: 'general.birth-country',

text: 'What is your country of birth?',

answer: [

{

valueString: 'United States',

},

],

},

{

linkId: 'general.marital',

text: 'What is your marital status?',

answer: [

{

valueCoding: {

code: 'married',

},

},

],

},

],

},

{

linkId: 'intoxicants',

text: 'Intoxicants',

item: [

{

linkId: 'intoxicants.smoking',

text: 'Do you smoke?',

answer: [

{

valueBoolean: true,

},

],

},

{

linkId: 'intoxicants.alcohol',

text: 'Do you drink alcohol?',

answer: [

{

valueBoolean: true,

},

],

},

],

},

],

};
```

## UI Components [​](/content/docs/questionnaires/questionnaires-and-responses#ui-components "Direct link to UI Components"/index.html)

Medplum provides React components to help you view and build [`Questionnaire`](/content/docs/api/fhir/resources/questionnaire/index.html) resources. You can preview the [QuestionnaireForm](https://storybook.medplum.com/?path=/story/medplum-questionnaireform--basic) and [QuestionnaireBuilder](https://storybook.medplum.com/?path=/story/medplum-questionnairebuilder--basic) components in [Storybook](https://storybook.medplum.com/?path=/docs/medplum-introduction--docs).

### Signature Required [​](/content/docs/questionnaires/questionnaires-and-responses#signature-required "Direct link to Signature Required"/index.html)

To require a signature for a Questionnaire, add the following extension to the Questionnaire resource:

```typescript
{

"resourceType": 'Questionnaire',

"extension": [

{

"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-signatureRequired",

"valueCodeableConcept": {

"coding": [

{

"system": "urn:iso-astm:E1762-95:2013",

"code": "1.2.840.10065.1.12.1.1",

"display": "Author's Signature"

}

]

}

}

],

//...
}
```

The `QuestionnaireForm` component will automatically render a signature input field when the signature extension is present in the Questionnaire. The signature input field will be required and will validate that a signature is provided before submission.

See the [Storybook](https://storybook.medplum.com/?path=/story/medplum-questionnaireform--signature-required) for an example.

For where the captured signature is stored on the [`QuestionnaireResponse`](/content/docs/api/fhir/resources/questionnaireresponse/index.html) and how to attach it to a consent record, see [Consent and Signatures](/content/docs/consent/index.html).