Adaptive Forms

Structured Data Capture
4.0.0 - STU 4 International flag

Structured Data Capture, published by HL7 International / FHIR Infrastructure. This guide is not an authorized publication; it is the continuous build for version 4.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/sdc/ and changes regularly. See the Directory of published versions

Page standards status: Trial-use

Contents:

Adaptive Questionnaire Background
Adaptive Questionnaire Administration Abstract Model and Actors
Data Flow Description for Adaptive Questionnaires Administration
Adaptive Population
Security Considerations

Adaptive Questionnaire Background

Adaptive Forms follow an architecture where a questionnaire is not pre-defined, rather the questionnaire is dynamically developed based on previous answers to questions chosen from an item bank of questions. This type of administration is also known as Computerized Adaptive Testing (CAT), or administration of Adaptive Questionnaires. In these cases, a set of questions (typically 4 to 12) are administered from a question bank containing numerous questions. The selected questions are based on Item Response Theory (IRT) algorithms which look at the answers provided and select the next question based on IRT algorithms. The questions are selected to quickly obtain the necessary outcomes (e.g. assessing a person's physical function) using fewer questions rather than administering a large question bank. These small sets of questions still provide the necessary confidence and scores required to interpret the data appropriately as if the whole questionnaire was administered. he adaptive process relies on the $next-question operation to dynamically determine and retrieve subsequent questions based on previous answers.

Adaptive Questionnaire Administration Abstract Model and Actors

Profiles:	Adaptive Questionnaire Profile Adaptive QuestionnaireResponse Profile Adaptive Questionnaire Search Profile
Relevant Extensions:	questionnaireAdaptive
Example Questionnaires:	Adaptive PHQ9 - Start Adaptive PHQ9 - Complete

Profiles:

Relevant Extensions:

questionnaireAdaptive

Example Questionnaires:

The section explains the process of administering an Adaptive Questionnaire and the actors (systems) involved. Figure 1 below shows the abstract model of the administration process.

Figure 1: Adaptive Questionnaire Administration Abstract Model

Actors, Definitions and Data Flow

External Assessment Center: The External IRT based Assessment Center is a system that can administer a questionnaire based on IRT algorithms. The data that is necessary for the administration is only the initial item bank. The External Assessment Center does not need to know about the specific patient identity or any other clinical information. The Assessment Center will use algorithms recommended by the Questionnaire designer to determine how to administer the questionnaire.

Patient Facing Administration App: The Patient Facing Administration App is the actual app that is being used to present the questions to the patient. It can be an EHR, a SMART on FHIR App, an Independent PRO Administration App.

Data Flow Description for Adaptive Questionnaires Administration

As shown in Figure 1 above, the Patient Facing Administration App (EHR, Care Delivery System, Independent App or SMART on FHIR App) acts as the client and initiates the administration process.

The following section describes the steps that take place when completing an adaptive Questionnaire and also provides examples of the content sent to and received back from the next question operation. With regard to the server's response, it is possible that more than one new question is returned in the questionnaire, and previously sent questions that were unanswered might not be sent back by the server.

Step 0:
Before initiating the administration process for an adaptive questionnaire, the app must first locate the appropriate questionnaire. This can be done through various mechanisms such as performing a search operation, referencing a Task resource, or other mechanism. The questionnaire being located SHALL conform to the Adaptive Questionnaire Search Profile, which ensures that it is discoverable and compliant with adaptive questionnaire requirements.

Additionally, the located questionnaire SHALL include the questionnaireAdaptive extension. This extension explicitly indicates that the questionnaire supports adaptiveness and may provide details about the endpoints where the $next-question operation can be invoked. If the questionnaireAdaptive extension doesn't specify a URL, the location must be independently negotiated, though as a fallback, try the server on which the Questionnaire is hosted. This step ensures that the app knows whether the questionnaire is adaptive and where to send subsequent requests for the adaptive process.
Step 1: The available adaptive questionnaires are loaded into the Assessment Center.

Step 2: The administration is initiated with a specific Adaptive Questionnaire.

Request

POST [base]/Questionnaire/$next-question

Request Body

JSON

{
  "resourceType" : "QuestionnaireResponse",
  ...
  "contained" : [
    {
      "resourceType" : "Questionnaire",
      "id" : "contained-adaptive-questionnaire-example-phq9-start",
      ...
      "derivedFrom" : [
        🔗 "http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9"
      ],
      "_derivedFrom" : [
        {
          🔗 "extension" : [
            {
              "url" : "http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType",
              "valueCoding" : {
                "system" : "http://hl7.org/fhir/questionnaire-derivationType",
                "code" : "compliesWith"
              }
            }
          ]
        }
      ],
      ...
    },
    ...
  ],
  "questionnaire" : "#contained-adaptive-questionnaire-example-phq9-start",
  "status" : "in-progress",
  ...
}

XML


<QuestionnaireResponse xmlns="http://hl7.org/fhir">
  ...
  <contained>
    <Questionnaire>
      <id value="contained-adaptive-questionnaire-example-phq9-start"/>
      ...
      <derivedFrom
                   value="http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9">🔗 
        <extension
                   url="http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType">
          <valueCoding>
            <system value="http://hl7.org/fhir/questionnaire-derivationType"/>
            <code value="compliesWith"/>
          </valueCoding>
        </extension>
      </derivedFrom>
      ...
    </Questionnaire>
  </contained>
  ...
  <questionnaire
                 value="#contained-adaptive-questionnaire-example-phq9-start"/>
  <status value="in-progress"/>
  ...
</QuestionnaireResponse>

NOTE: No items in QuestionnaireResponse or Questionnaire because process is just starting. (It's possible in some cases to have a pre-populated adaptive QuestionnaireResponse that includes initial items in both the Questionnaire and QuestionnaireResponse, but we're keeping the example simple/typical.)

Step 3: The Assessment Center responds to the start request with a Questionnaire and the first item for administration.

Response Body

JSON

{
  "resourceType" : "QuestionnaireResponse",
  ...
  "contained" : [
    {
      "resourceType" : "Questionnaire",
      "id" : "contained-adaptive-questionnaire-example-phq9-start",
      ...
      "derivedFrom" : [
        🔗 "http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9"
      ],
      "_derivedFrom" : [
        {
          🔗 "extension" : [
            {
              "url" : "http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType",
              "valueCoding" : {
                "system" : "http://hl7.org/fhir/questionnaire-derivationType",
                "code" : "compliesWith"
              }
            }
          ]
        }
      ],
      ...
      "item" : [
        {
          ...
          "item" : [
            {
              "linkId" : "H1/T1/Q1",
              "text" : "Little interest or pleasure in doing things?",
              "type" : "choice",
              "required" : true,
              "repeats" : false,
              "answerValueSet" : "#VSPHQ9B"
            },
            ...
          ]
        }
      ]
    },
    ...
  ],
  "questionnaire" : "#contained-adaptive-questionnaire-example-phq9-start",
  "status" : "in-progress",
  ...
}

XML


<QuestionnaireResponse xmlns="http://hl7.org/fhir">
  ...
  <contained>
    <Questionnaire>
      <id value="contained-adaptive-questionnaire-example-phq9-start"/>
      ...
      <derivedFrom
                   value="http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9">🔗 
        <extension
                   url="http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType">
          <valueCoding>
            <system value="http://hl7.org/fhir/questionnaire-derivationType"/>
            <code value="compliesWith"/>
          </valueCoding>
        </extension>
      </derivedFrom>
      ...
      <item>
        ...
        <item>
          <linkId value="H1/T1/Q1"/>
          <text value="Little interest or pleasure in doing things?"/>
          <type value="choice"/>
          <required value="true"/>
          <repeats value="false"/>
          <answerValueSet value="#VSPHQ9B"/>
        </item>
        ...
      </item>
    </Questionnaire>
  </contained>
  ...
  <questionnaire
                 value="#contained-adaptive-questionnaire-example-phq9-start"/>
  <status value="in-progress"/>
  ...
</QuestionnaireResponse>

Step 4: The Patient Facing Administration App will then display the question to the user and collect the response.

Step 5: The Patient Facing Administration App will then send the answer to the Assessment Center and ask for the next question. The Assessment Center will use the answer to determine the next question based on the algorithm and respond back with the next question until the assessment is done.

Request Body

JSON

{
  "resourceType" : "QuestionnaireResponse",
  ...
  "contained" : [
    {
      "resourceType" : "Questionnaire",
      "id" : "contained-adaptive-questionnaire-example-phq9-start",
      ...
      "derivedFrom" : [
        🔗 "http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9"
      ],
      "_derivedFrom" : [
        {
          🔗 "extension" : [
            {
              "url" : "http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType",
              "valueCoding" : {
                "system" : "http://hl7.org/fhir/questionnaire-derivationType",
                "code" : "compliesWith"
              }
            }
          ]
        }
      ],
      ...
      "item" : [
        {
          ...
          "item" : [
            {
              "linkId" : "H1/T1/Q1",
              "text" : "Little interest or pleasure in doing things?",
              "type" : "choice",
              "required" : true,
              "repeats" : false,
              "answerValueSet" : "#VSPHQ9B"
            },
            ...
          ]
        }
      ]
    },
    ...
  ],
  "questionnaire" : "#contained-adaptive-questionnaire-example-phq9-start",
  "status" : "in-progress",
  ...
}

XML


<QuestionnaireResponse xmlns="http://hl7.org/fhir">
  ...
  <contained>
    <Questionnaire>
      <id value="contained-adaptive-questionnaire-example-phq9-start"/>
      ...
      <derivedFrom
                   value="http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9">🔗 
        <extension
                   url="http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType">
          <valueCoding>
            <system value="http://hl7.org/fhir/questionnaire-derivationType"/>
            <code value="compliesWith"/>
          </valueCoding>
        </extension>
      </derivedFrom>
      ...
      <item>
        ...
        <item>
          <linkId value="H1/T1/Q1"/>
          <text value="Little interest or pleasure in doing things?"/>
          <type value="choice"/>
          <required value="true"/>
          <repeats value="false"/>
          <answerValueSet value="#VSPHQ9B"/>
        </item>
        ...
      </item>
    </Questionnaire>
  </contained>
  ...
  <questionnaire
                 value="#contained-adaptive-questionnaire-example-phq9-start"/>
  <status value="in-progress"/>
  ...
</QuestionnaireResponse>

Response Body

JSON

{
  "resourceType" : "QuestionnaireResponse",
  ...
  "contained" : [
    {
      "resourceType" : "Questionnaire",
      "id" : "contained-adaptive-questionnaire-example-phq9-start",
      ...
      "derivedFrom" : [
        🔗 "http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9"
      ],
      "_derivedFrom" : [
        {
          🔗 "extension" : [
            {
              "url" : "http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType",
              "valueCoding" : {
                "system" : "http://hl7.org/fhir/questionnaire-derivationType",
                "code" : "compliesWith"
              }
            }
          ]
        }
      ],
      ...
      "item" : [
        {
          ...
          "item" : [
            {
              "linkId" : "H1/T1/Q1",
              "text" : "Little interest or pleasure in doing things?",
              "type" : "choice",
              "required" : true,
              "repeats" : false,
              "answerValueSet" : "#VSPHQ9B"
            },
            ...
          ]
        }
      ]
    },
    ...
  ],
  "questionnaire" : "#contained-adaptive-questionnaire-example-phq9-start",
  "status" : "in-progress",
  ...
}

XML


<QuestionnaireResponse xmlns="http://hl7.org/fhir">
  ...
  <contained>
    <Questionnaire>
      <id value="contained-adaptive-questionnaire-example-phq9-start"/>
      ...
      <derivedFrom
                   value="http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9">🔗 
        <extension
                   url="http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType">
          <valueCoding>
            <system value="http://hl7.org/fhir/questionnaire-derivationType"/>
            <code value="compliesWith"/>
          </valueCoding>
        </extension>
      </derivedFrom>
      ...
      <item>
        ...
        <item>
          <linkId value="H1/T1/Q1"/>
          <text value="Little interest or pleasure in doing things?"/>
          <type value="choice"/>
          <required value="true"/>
          <repeats value="false"/>
          <answerValueSet value="#VSPHQ9B"/>
        </item>
        ...
      </item>
    </Questionnaire>
  </contained>
  ...
  <questionnaire
                 value="#contained-adaptive-questionnaire-example-phq9-start"/>
  <status value="in-progress"/>
  ...
</QuestionnaireResponse>

Step 4 is repeated as long as new questions are received and the status is "in-progress"

Step 6: If the Assessment Center determines that the assessment is done, it will respond with the final results which will contain all the questions that were answered, along with the answers, the individual scores and the overall score.

Request Body

JSON

{
  "resourceType" : "QuestionnaireResponse",
  ...
  "contained" : [
    {
      "resourceType" : "Questionnaire",
      "id" : "contained-adaptive-questionnaire-example-phq9-start",
      ...
      "derivedFrom" : [
        🔗 "http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9"
      ],
      "_derivedFrom" : [
        {
          🔗 "extension" : [
            {
              "url" : "http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType",
              "valueCoding" : {
                "system" : "http://hl7.org/fhir/questionnaire-derivationType",
                "code" : "compliesWith"
              }
            }
          ]
        }
      ],
      ...
      "item" : [
        {
          ...
          "item" : [
            ...
            {
              "linkId" : "H1/T1/Q9",
              "text" : "Thoughts that you would be better off dead, or thoughts of hurting yourself in some way?",
              "type" : "choice",
              "required" : true,
              "repeats" : false,
              "answerValueSet" : "#VSPHQ9B"
            }
          ]
        }
      ]
    },
    ...
  ],
  "questionnaire" : "#contained-adaptive-questionnaire-example-phq9-start",
  "status" : "in-progress",
  ...
}

XML


<QuestionnaireResponse xmlns="http://hl7.org/fhir">
  ...
  <contained>
    <Questionnaire>
      <id value="contained-adaptive-questionnaire-example-phq9-start"/>
      ...
      <derivedFrom
                   value="http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9">🔗 
        <extension
                   url="http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType">
          <valueCoding>
            <system value="http://hl7.org/fhir/questionnaire-derivationType"/>
            <code value="compliesWith"/>
          </valueCoding>
        </extension>
      </derivedFrom>
      ...
      <item>
        ...
        <item>
          <linkId value="H1/T1/Q9"/>
          <text
                value="Thoughts that you would be better off dead, or thoughts of hurting yourself in some way?"/>
          <type value="choice"/>
          <required value="true"/>
          <repeats value="false"/>
          <answerValueSet value="#VSPHQ9B"/>
        </item>
      </item>
    </Questionnaire>
  </contained>
  ...
  <questionnaire
                 value="#contained-adaptive-questionnaire-example-phq9-start"/>
  <status value="in-progress"/>
  ...
</QuestionnaireResponse>

Response Body with Completed Status indicating completion of Administration

JSON

{
  "resourceType" : "QuestionnaireResponse",
  ...
  "contained" : [
    {
      "resourceType" : "Questionnaire",
      "id" : "contained-adaptive-questionnaire-example-phq9",
      ...
      "derivedFrom" : [
        🔗 "http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9"
      ],
      "_derivedFrom" : [
        {
          🔗 "extension" : [
            {
              "url" : "http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType",
              "valueCoding" : {
                "system" : "http://hl7.org/fhir/questionnaire-derivationType",
                "code" : "compliesWith"
              }
            }
          ]
        }
      ],
      ...
      "item" : [
        {
          ...
          "item" : [
            ...
            {
              "linkId" : "H1/TS",
              "text" : "Patient health questionnaire 9 item total score",
              "type" : "quantity",
              "repeats" : false,
              "readOnly" : true
            }
          ]
        }
      ]
    },
    ...
  ],
  "questionnaire" : "#contained-adaptive-questionnaire-example-phq9",
  "status" : "completed",
  ...
}

XML


<QuestionnaireResponse xmlns="http://hl7.org/fhir">
  ...
  <contained>
    <Questionnaire>
      <id value="contained-adaptive-questionnaire-example-phq9"/>
      ...
      <derivedFrom
                   value="http://hl7.org/fhir/uv/sdc/Questionnaire/questionnaire-sdc-profile-example-PHQ9">🔗 
        <extension
                   url="http://hl7.org/fhir/StructureDefinition/questionnaire-derivationType">
          <valueCoding>
            <system value="http://hl7.org/fhir/questionnaire-derivationType"/>
            <code value="compliesWith"/>
          </valueCoding>
        </extension>
      </derivedFrom>
      ...
      <item>
        ...
        <item>
          <linkId value="H1/TS"/>
          <text value="Patient health questionnaire 9 item total score"/>
          <type value="quantity"/>
          <repeats value="false"/>
          <readOnly value="true"/>
        </item>
      </item>
    </Questionnaire>
  </contained>
  ...
  <questionnaire value="#contained-adaptive-questionnaire-example-phq9"/>
  <status value="completed"/>
  ...
</QuestionnaireResponse>

Adaptive Population

Adaptive questionnaires can support population under certain constraints. The following guidance applies when using population mechanisms with adaptive forms:

Can use observation-based or expression-based, but not StructureMap.
Systems should cache previously populated variable values between calls to $next-question.
New variables and even libraries may appear in subsequent iterations of the Questionnaire and clients will need to look for these.

Security Considerations

Because the adaptive process involves sending answers to a separate endpoint in order to determine the "next question", the connection should be appropriately protected based on the type of information that might be exchanged. (And given that there is no way to be completely certain what questions will be asked, it is best to err on the side of safety and presume that sensitive information might be shared.) As well, there should be trust between the Form Filler and the nextQuestion endpoint as the server performing the operation will obviously have access to that information. In general, servers performing the nextQuestion operation SHOULD NOT take any action with the data other than to return the response and potentially log the information. "Submission" of a completed form should always be a distinct action taken by the client.

<prev

top

next>

IG © 2022+ HL7 International / FHIR Infrastructure. Package hl7.fhir.uv.sdc#4.0.0 based on FHIR 4.0.1. Generated 2025-09-10
Links: Table of Contents | QA Report | Version History | | Propose a change