Is it even possible to have varying healthcare forms that comply with a unified standard? FHIR’s Questionnaire resource is a step in the right direction. Let's explore how this can be done.
Collecting accurate patient information is critical towards providing informed care. Designing hospital forms and storing their structure and any updates are essential in preserving data integrity.
Similarly, forms help doctors process vast amounts of structured and unstructured information. Having a predictable interface is a useful tool in reducing cognitive load and making sure doctors notice key data points quickly.
What is a Questionnaire resource?#
In FHIR, this essential requirement is supported by the Questionnaire resource. A Questionnaire helps to define and communicate forms, and allows for logical organization of questions in a form as lists or hierarchical groups. The results of a Questionnaire are communicated using the QuestionnaireResponse resource.
A Questionnaire contains questions, information about their grouping and ordering, additional instructional text and constraints placed on the allowed answers. It also defines the presentation of its data in a standardized and predictable way.
A Questionnaire has two main components, Questionnaire and item. The first section contains metadata or information about the questionnaire such as version, name, title and status. The ‘item’ is a recursive structure which can be one of three sub-types - display, groups and questions. They’re identified by the ‘type’ element
- Display: Contains text that will be displayed on the screen, but doesn’t take in a response e.g. instructions, copyright information
- Groups: This organizes the content of a Questionnaire into sections and sub-sections
- Questions: These are the questions included in the form and usually expect a response from the user
The open source LHC FHIR Tools by the National Library of Medicine (LHNCBC) are a great resource for beginning your FHIR Questionnaire exploration. Here I’m using the LHC-Forms Widget that renders FHIR Questionnaire resources, and looking at the ‘Weight height tracking panel’ sample form provided.
To see the JSON form definition, you can select ‘FHIR SDC Questionnaire’ from the ‘Show Form Data As…’ dropdown menu.
You can copy the form definition and save it as a .json file, or you can copy it from below.
{
"id": "55418-8-x",
"meta": {
"versionId": "1",
"lastUpdated": "2024-07-29T02:08:36.000-04:00",
"profile": [
"http://hl7.org/fhir/4.0/StructureDefinition/Questionnaire"
],
"tag": [
{
"code": "lformsVersion: 36.8.1"
}
]
},
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/variable",
"valueExpression": {
"name": "weight",
"language": "text/fhirpath",
"expression": "%resource.item.where(linkId='/29463-7').answer.value"
}
},
{
"url": "http://hl7.org/fhir/StructureDefinition/variable",
"valueExpression": {
"name": "height",
"language": "text/fhirpath",
"expression": "%resource.item.where(linkId='/8302-2').answer.value*0.0254"
}
}
],
"date": "2018-09-12T18:03:40-04:00",
"identifier": [
{
"system": "http://loinc.org",
"value": "55418-8"
}
],
"code": [
{
"system": "http://loinc.org",
"code": "55418-8",
"display": "Weight and Height tracking panel"
}
],
"subjectType": [
"Patient"
],
"status": "draft",
"url": "https://lforms-fhir.nlm.nih.gov/baseR4/Questionnaire/55418-8-x",
"name": "weight_height_tracking_panel",
"title": "Weight & Height tracking panel",
"resourceType": "Questionnaire",
"item": [
{
"type": "decimal",
"code": [
{
"system": "http://loinc.org",
"code": "29463-7",
"display": "Weight"
}
],
"extension": [
{
"url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-observationLinkPeriod",
"valueDuration": {
"value": 100,
"unit": "year",
"system": "http://unitsofmeasure.org",
"code": "a"
}
},
{
"url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-observationExtract",
"valueBoolean": true
},
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-unit",
"valueCoding": {
"code": "kg",
"system": "http://unitsofmeasure.org"
}
}
],
"linkId": "/29463-7",
"text": "Weight"
},
{
"type": "choice",
"code": [
{
"system": "http://loinc.org",
"code": "8352-7",
"display": "Clothing worn during measure"
}
],
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
"valueCodeableConcept": {
"coding": [
{
"system": "http://hl7.org/fhir/questionnaire-item-control",
"code": "drop-down",
"display": "Drop down"
}
],
"text": "Drop down"
}
}
],
"linkId": "/8352-7",
"text": "Clothing worn during measure",
"answerOption": [
{
"valueCoding": {
"code": "LA11871-3",
"display": "Underwear or less",
"system": "http://loinc.org"
}
},
{
"valueCoding": {
"code": "LA11872-1",
"display": "Street clothes, no shoes",
"system": "http://loinc.org"
}
},
{
"valueCoding": {
"code": "LA11873-9",
"display": "Street clothes & shoes",
"system": "http://loinc.org"
}
}
]
},
{
"type": "decimal",
"code": [
{
"system": "http://loinc.org",
"code": "8302-2",
"display": "Body height"
}
],
"extension": [
{
"url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-observationLinkPeriod",
"valueDuration": {
"value": 100,
"unit": "year",
"system": "http://unitsofmeasure.org",
"code": "a"
}
},
{
"url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-observationExtract",
"valueBoolean": true
},
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-unit",
"valueCoding": {
"code": "[in_i]",
"system": "http://unitsofmeasure.org"
}
}
],
"linkId": "/8302-2",
"text": "Body height"
},
{
"type": "decimal",
"code": [
{
"system": "http://loinc.org",
"code": "39156-5",
"display": "BMI"
}
],
"extension": [
{
"url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-calculatedExpression",
"valueExpression": {
"description": "BMI calculation",
"language": "text/fhirpath",
"expression": "(%weight/(%height.power(2))).round(1)"
}
},
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-unit",
"valueCoding": {
"code": "kg/m2",
"system": "http://unitsofmeasure.org"
}
}
],
"linkId": "/39156-5",
"text": "BMI"
},
{
"type": "choice",
"code": [
{
"system": "http://loinc.org",
"code": "8361-8",
"display": "Bdy position with respect to gravity"
}
],
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
"valueCodeableConcept": {
"coding": [
{
"system": "http://hl7.org/fhir/questionnaire-item-control",
"code": "drop-down",
"display": "Drop down"
}
],
"text": "Drop down"
}
}
],
"linkId": "/8361-8",
"text": "Bdy position with respect to gravity",
"answerOption": [
{
"valueCoding": {
"code": "LA11868-9",
"display": "Sitting",
"system": "http://loinc.org"
}
},
{
"valueCoding": {
"code": "LA11869-7",
"display": "Lying",
"system": "http://loinc.org"
}
},
{
"valueCoding": {
"code": "LA11870-5",
"display": "Standing",
"system": "http://loinc.org"
}
}
]
}
]
}
To edit this form and build a corresponding updated Questionnaire resource, you can use the NLM Form Builder, also by the National Library of Medicine.
Here you can upload the file you just saved, and edit the form attributes and questions.
When you're done, you can save the updated form in the .json format through Export > Export to file in FHIR R4 format
What is a QuestionnaireResponse resource?#
The QuestionnaireResponse contains the complete or partial set of answers to questions that correspond to a questionnaire. It usually references the Questionnaire that is being answered by URL. It also distinguishes between the ‘author’ who records the information, ‘subject’ who the information is about and the ‘source’ who provides the information.
The structure of a QuestionnaireResponse reflects that of the Questionnaire it corresponds to. It contains similar metadata and ‘item’ tags that reflect the order and grouping of Questionnaire items, and are also affected by whether certain questions repeat or mandate answers.
In the LHC-Forms Widget, you can enter any information in the ‘Weight height tracking panel’ we selected earlier, or in your edited form.
You’ll notice that the BMI is filled automatically once you enter weight and height.
To save the Questionnaire response, select ‘FHIR SDC QuestionnaireResponse’ from the ‘Show Form Data As…’ dropdown menu.
You have successfully generated a FHIR QuestionnaireResponse! Here it is for easy access and reference.
{
"resourceType": "QuestionnaireResponse",
"meta": {
"profile": [
"http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse|3.0"
],
"tag": [
{
"code": "lformsVersion: 36.8.1"
}
]
},
"status": "completed",
"authored": "2025-01-21T09:23:11.864Z",
"questionnaire": "https://lforms-fhir.nlm.nih.gov/baseR4/Questionnaire/55418-8-x",
"item": [
{
"answer": [
{
"valueDecimal": 83
}
],
"linkId": "/29463-7",
"text": "Weight"
},
{
"answer": [
{
"valueCoding": {
"system": "http://loinc.org",
"code": "LA11872-1",
"display": "Street clothes, no shoes"
}
}
],
"linkId": "/8352-7",
"text": "Clothing worn during measure"
},
{
"answer": [
{
"valueDecimal": 72
}
],
"linkId": "/8302-2",
"text": "Body height"
},
{
"answer": [
{
"valueDecimal": 24.8
}
],
"linkId": "/39156-5",
"text": "BMI"
},
{
"answer": [
{
"valueCoding": {
"system": "http://loinc.org",
"code": "LA11869-7",
"display": "Lying"
}
}
],
"linkId": "/8361-8",
"text": "Bdy position with respect to gravity"
}
]
}
Understanding the JSON representations#
Questionnaire resource#
Here is a simplified representation of the metadata elements present in the Weight and Height Tracking Panel Questionnaire resource that we just downloaded. Please note that the JSON is not syntactically complete.
{
"id": "55418-8-x",
"meta": {
"versionId": "1",
"lastUpdated": "2024-07-29T02:08:36.000-04:00",
"profile": ["http://hl7.org/fhir/4.0/StructureDefinition/Questionnaire"],
"tag": [{"code": "lformsVersion: 36.8.1"}]
},
...
"date": "2018-09-12T18:03:40-04:00",
"identifier": [{
"system": "http://loinc.org",
"value": "55418-8"
}],
"code": [{
"system": "http://loinc.org",
"code": "55418-8",
"display": "Weight and Height tracking panel"
}],
"subjectType": ["Patient"],
"status": "draft",
"url": "https://lforms-fhir.nlm.nih.gov/baseR4/Questionnaire/55418-8-x",
"name": "weight_height_tracking_panel",
"title": "Weight & Height tracking panel",
"resourceType": "Questionnaire",
//incomplete JSON
You can see elements such as:
- "id" and "identifier": we’ll differentiate between them in detail later on
- "lastUpdated" date and time stamp
- "code" the standard terminology concept that represents the overall questionnaire
- "subjectType": the Resource that is the subject of QuestionnaireResponse
- "status" representing the publication status of the Questionnaire
- "name", "title": internal and external names of the Questionnaire
- "resourceType": which will always be “Questionnaire”
Now let’s take a look at the first two ‘item’ elements from within the Questionnaire json, and compare it against the visual representation of the form.
"item": [ //this indicates that item is a list
{"type": "decimal",
"code": [{
"system": "http://loinc.org",
"code": "29463-7",
"display": "Weight"
}],
"extension": [...],
"linkId": "/29463-7",
"text": "Weight"
},
//second ‘item’
{
"type": "choice",
"code": [{
"system": "http://loinc.org",
"code": "8352-7",
"display": "Clothing worn during measure"
}],
"extension": [{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
"valueCodeableConcept": {
"coding": [{
"system": "http://hl7.org/fhir/questionnaire-item-control",
"code": "drop-down",
"display": "Drop down"
}],
"text": "Drop down"
}}],
"linkId": "/8352-7",
"text": "Clothing worn during measure",
"answerOption": [{
"valueCoding": {
"code": "LA11871-3",
"display": "Underwear or less",
"system": "http://loinc.org"
}},
{
"valueCoding": {
"code": "LA11872-1",
"display": "Street clothes, no shoes",
"system": "http://loinc.org"
}},
{
"valueCoding": {
"code": "LA11873-9",
"display": "Street clothes & shoes",
"system": "http://loinc.org"
}}]}
The first form component represents the Weight field
- “type”: “decimal” says that answer expected is a decimal number, in the screenshot you can see that it has a simple text box
- “code” corresponds to the concept for this item in a standard terminology, in this case LOINC
- “linkID” is a unique ID for an item, and we’ll see it again in the answer recorded in QuestionnaireResponse
- “text” is the label associated with the field.
The second component is a dropdown for Clothing worn during measure
- “type”: “choice” is a coded text and the question provides answer options to choose from and this is further expanded in the “extension” as a “drop-down”
- “code” is used similarly as in the first item
- “answerOption” is a list that defines the options presented in the drop down, the text displayed and the terminology code that it represents
QuestionnaireResponse resource#
In the QuestionnaireResponse JSON snippet, we can observe the following metadata elements
- “status”: “completed” indicating that the form entry is complete and saved
- “authored” containing the timestamp of submission
- “questionnaire” with a URL to the Questionnaire it corresponds to
{
"resourceType": "QuestionnaireResponse",
"meta": {
"profile": [
"http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse|3.0"
],
"tag": [{
"code": "lformsVersion: 36.8.1"
}]},
"status": "completed",
"authored": "2025-01-21T09:23:11.864Z",
"questionnaire": "https://lforms-fhir.nlm.nih.gov/baseR4/Questionnaire/55418-8-x",
Now let's compare the "item" elements in the QuestionnaireResponse to the input provided via the visual interface.
"item": [
{
"answer": [{
"valueDecimal": 83
}],
"linkId": "/29463-7",
"text": "Weight"
},
{
"answer": [{
"valueCoding": {
"system": "http://loinc.org",
"code": "LA11872-1",
"display": "Street clothes, no shoes"
}}],
"linkId": "/8352-7",
"text": "Clothing worn during measure"
},
{
"answer": [{
"valueDecimal": 72
}],
"linkId": "/8302-2",
"text": "Body height"
},
{
"answer": [{
"valueDecimal": 24.8
}],
"linkId": "/39156-5",
"text": "BMI"
},
{
"answer": [{
"valueCoding": {
"system": "http://loinc.org",
"code": "LA11869-7",
"display": "Lying"
}}],
"linkId": "/8361-8",
"text": "Bdy position with respect to gravity"
}
]
}
What are the different ‘identifying’ elements in a Questionnaire and QuestionnaireResponse?#
There are three different ‘identifying’ elements in a Questionnaire that are important to distinguish between, they are the ‘identifier’, ‘linkid’ and ‘id’.
- ‘identifier’: This is part of the Questionnaire metadata and contains the business identifier for the questionnaire
- ‘linkid’: This is a unique identifier for each question or group in a Questionnaire, and connects items in a QuestionnaireResponse to the corresponding Questionnaire item
- ‘id’: These correspond to each element and are used for internal reference within a resource
Closing thoughts#
There is a compelling case for using FHIR Questionnaire and QuestionnaireResponse to effectively build and manage healthcare forms. It holds comprehensive information about forms and form responses and maps easily to other FHIR resources for information transfer and querying.
Open source tools such as the LHC FHIR Tools by the National Library of Medicine are an easy way to begin hands-on exploration of the FHIR Questionnaire and QuestionnaireResponse resources. Try out the Form Widget to render forms and extract QuestionnaireResponses, and the Form Builder to build your own forms and generate corresponding Questionnaire resources.
Hands-on exploration is one of the best ways we’ve found to get comfortable with implementing FHIR. Another great way is to learn from an expert - join our free, 90-minute FHIR Masterclass by Dr. Sidharth Ramesh, who has 8+ years of experience working with FHIR and other interoperability standards. Register here to grab the last few seats.