FHIR Questionnaire: Complete Guide

What is a FHIR Questionnaire?

A FHIR Questionnaire is a resource that defines a structured set of questions, with item types, allowed answers, required flags, display text and conditional logic, so a form can be designed once and rendered by any system that supports it. Completed answers are stored in a separate QuestionnaireResponse resource that references the Questionnaire.

Questionnaire separates the form definition from the app. A clinic can update a screening form by publishing a new Questionnaire version, and every app that renders FHIR forms picks up the change without a code release.

How do Questionnaire and QuestionnaireResponse relate?

A Questionnaire is the template and a QuestionnaireResponse is one completed instance of it. The response points to the Questionnaire by its canonical URL and version, names the subject and author, and repeats the item structure with answers attached.

Items are matched by linkId. In FHIR R4, every group and question in a Questionnaire has a linkId that is unique within it, and the response uses the same linkIds, so software can pair each answer with its question even when the display text changes.

A QuestionnaireResponse has its own status: in-progress, completed, amended, entered-in-error or stopped. That lets an app save a partly finished form, mark it complete, and later record a correction as amended rather than overwriting history.

Treat the canonical URL and version as part of the data. A response is only interpretable against the exact Questionnaire version that produced it, so servers should keep old versions available after a form changes.

Which item types and rules does a Questionnaire use?

A Questionnaire is built from items, each with a type that sets what kind of answer it takes and rules that set when it appears and whether it is required. Groups nest items, and display items show text without collecting an answer.

• Structure types: group for sections and repeating blocks, display for instructions and headings.
• Simple answers: boolean, decimal, integer, date, dateTime, time, string and text for short and long free text.
• Choices: choice for a fixed list and open-choice for a list that also accepts free text, with options from answerOption or a ValueSet through answerValueSet.
• Rich answers: quantity for a value with units, attachment for files and reference for links to other resources.
• Required and repeats: Flags that make an item mandatory or let it be answered more than once.
• enableWhen: Conditions that show an item only when another item's answer meets a test, using operators such as exists, equals, not equals and comparisons.
• enableBehavior: Whether all or any of several enableWhen conditions must be true, which R4 requires when there is more than one condition.

Use coded answers wherever the result will be used downstream. A choice item bound to a ValueSet of SNOMED CT or LOINC answer codes produces data that analytics and decision support can use, while free-text options produce strings that must be cleaned later.

The item's code element matters too. Coding each question with a LOINC code, where one exists for that instrument, lets receiving systems recognize the question regardless of wording.

What does Structured Data Capture add?

Structured Data Capture, the HL7 SDC implementation guide, adds the behavior that real forms need on top of base Questionnaire: pre-population from existing data, calculated fields, extraction of answers into other resources, modular forms and rendering hints. Its current published release is version 4.0.0, STU 4, based on FHIR R4.

• Pre-population: The $populate operation and expression extensions fill answers from the patient's record, such as name, date of birth or current medications.
• Calculations: Extensions such as calculatedExpression compute scores and derived values with FHIRPath, for example a screening instrument's total.
• Extraction: The $extract operation turns a completed response into Observations, Conditions or other resources, using definition-based, observation-based or mapping-based approaches.
• Modular forms: The $assemble operation combines a parent Questionnaire with reusable sub-questionnaires into one form.
• Adaptive forms: Questionnaires where the server picks the next question based on earlier answers.
• Rendering: Extensions for item control, such as drop-downs or sliders, entry formats, hidden items and other display behavior.

SDC describes system roles, such as form designer, form filler and form manager, with capability expectations for each. Decide early which roles your software plays and which SDC features it must support, because renderers vary in how much of the guide they implement.

How do you build a FHIR form step by step?

Building a FHIR form runs from clinical design to stored data in eight steps. The same steps apply whether the form is a short intake or a validated screening instrument.

• 1. Design with clinicians: Agree the questions, answer options, required items, skip logic and how the results will be used.
• 2. Choose codes: Find LOINC codes for the questions and answers where they exist, and terminology bindings for coded answers.
• 3. Author the Questionnaire: Write the resource with linkIds, item types, enableWhen rules and SDC extensions, using a form designer or code.
• 4. Validate: Run the Questionnaire through the FHIR Validator against SDC profiles to catch structural errors.
• 5. Publish: Store it on a FHIR server with a canonical URL, version and status of active.
• 6. Render: Show it in the app with an SDC-capable renderer, pre-populating from the patient's data where allowed.
• 7. Store the response: Save the QuestionnaireResponse with the subject, author, status and Questionnaire version.
• 8. Extract and file: Turn the answers that matter into Observations or other resources, and file them to the EHR where the workflow needs them.

Test with real users before publishing. A form that validates perfectly can still confuse patients, and wording or ordering changes are cheap before the first responses are stored.

Pre-population and extraction in practice

Pre-population saves patients from retyping what the record already holds, and extraction turns answers into data other systems can use. Both depend on access rights and mappings that are easy to get wrong.

For pre-population, the form filler needs read access to the resources its expressions query, which for a SMART on FHIR app means requesting the right scopes. Show pre-filled answers for the patient to confirm, rather than hiding them, so outdated data is corrected rather than resubmitted.

For extraction, decide which answers become clinical data. A depression screening total may become an Observation with its LOINC code, while a preferred appointment time stays in the response. Extracting everything floods the chart with low-value records. Record the rule for each extracted item in the Questionnaire itself, through SDC extraction extensions, so the mapping travels with the form and changes with its version.

Writing extracted data into an EHR needs a write path. Certified patient-facing EHR APIs are read-focused, so filing usually uses the vendor's write APIs, an HL7 v2 interface or a document attached to the chart.

How do you choose a form renderer?

Choose a form renderer by the SDC features your forms need, the platforms your users are on, and how the renderer handles accessibility and offline use. The renderer decides what patients actually see, so test it with your own Questionnaires rather than its demo forms.

List the features first. A short intake form may need only item types, enableWhen and answer value sets. A scored screening instrument needs calculated expressions. A pre-visit form needs pre-population. Score each candidate renderer against that list and note which SDC extensions it ignores, because unsupported extensions can be skipped without an error.

Check the platforms. Web, iOS, Android and EHR-embedded SMART on FHIR apps may each need a renderer, and the same Questionnaire should behave the same in all of them. Open source renderers exist for web and mobile, and some EHR vendors render Questionnaires in their own patient apps.

Accessibility and language matter. The renderer should label every control for screen readers, support keyboard entry and large text, and show translated text from the Questionnaire's translation extensions when a patient's language differs from the default.

Where Questionnaire projects go wrong

Questionnaire projects usually go wrong on versioning, coding and renderer support. These failure points are worth checking in design review.

• Edited in place: A live Questionnaire changed without a new version, so older responses no longer match their questions.
• Reused linkIds: A linkId given a new meaning after a change, which corrupts trend data across versions.
• Uncoded answers: Free-text options where coded answers were needed, leaving analytics to parse strings.
• Renderer gaps: Forms that rely on SDC extensions the chosen renderer does not support, which then fail silently.
• Licensed instruments: Validated screening tools published without checking the instrument's license terms.
• Over-extraction: Every answer turned into an Observation, cluttering the chart.
• Stale pre-population: Pre-filled answers submitted without patient confirmation.

How Agnotic can help

FHIR forms succeed when clinical design, coding, rendering and extraction are planned together. Agnotic Technologies builds Questionnaire-based forms for clients: authoring and validation against SDC, SMART on FHIR apps that render and pre-populate them, response storage on FHIR servers, and extraction pipelines that file the right answers to the EHR.

The client's clinicians own the questions and scoring. Agnotic turns them into versioned, coded Questionnaires with tests that prove each rule works.

Sources

• HL7 FHIR R4: Questionnaire resource
• HL7 FHIR R4: QuestionnaireResponse resource
• HL7: Structured Data Capture implementation guide