• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles & Extensions
• R3 Conversions

2.38 Resource Questionnaire - Content

FHIR Infrastructure Work Group

Maturity Level: 3

Trial Use

Security Category: Business

Compartments: Not linked to any defined compartments

This resource has been identified by it's owning workgroup as a normative candidate for R5. Ballot comment is requested on this.

A structured set of questions intended to guide the collection of answers from end-users. Questionnaires provide detailed control over order, presentation, phraseology and grouping to allow coherent, consistent data collection.

2.38.4 References

This resource is referenced by CarePlan, Communication, ConditionDefinition, FamilyMemberHistory, ObservationDefinition, PlanDefinition, Procedure, itself and QuestionnaireResponse.

This resource implements the Definition pattern.

2.38.5 Resource Content

 

See the Profiles & Extensions and the alternate definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) , the spreadsheet version & the dependency analysis a

2.38.5.1 Terminology Bindings

Path	Definition	Type	Reference
Questionnaire.status		Required	PublicationStatus
Questionnaire.subjectType		Required	ResourceType
Questionnaire.jurisdiction		Extensible	Jurisdiction ValueSet
Questionnaire.code		Example	QuestionnaireQuestionCodes
Questionnaire.item.code		Example	QuestionnaireQuestionCodes
Questionnaire.item.type		Required	QuestionnaireItemType
Questionnaire.item.enableWhen.operator		Required	QuestionnaireItemOperator
Questionnaire.item.enableWhen.answer[x]		Example	QuestionnaireAnswerCodes
Questionnaire.item.enableBehavior		Required	EnableWhenBehavior
Questionnaire.item.disabledDisplay		Required	QuestionnaireItemDisabledDisplay
Questionnaire.item.answerConstraint		Required	QuestionnaireAnswerConstraint
Questionnaire.item.answerOption.value[x]		Example	QuestionnaireAnswerCodes
Questionnaire.item.initial.value[x]		Example	QuestionnaireAnswerCodes

2.38.5.2 Constraints

id	Level	Location	Description	Expression
cnl-0	Warning	(base)	Name should be usable as an identifier for the module by machine processing applications such as code generation	name.matches('[A-Z]([A-Za-z0-9_]){0,254}')
que-1	Rule	Questionnaire.item	Group items must have nested items, display items cannot have nested items	(type='group' implies item.empty().not()) and (type.trace('type')='display' implies item.trace('item').empty())
que-2	Rule	(base)	The link ids for groups and questions must be unique within the questionnaire	descendants().linkId.isDistinct()
que-3	Rule	Questionnaire.item	Display items cannot have a "code" asserted	type!='display' or code.empty()
que-4	Rule	Questionnaire.item	A question cannot have both answerOption and answerValueSet	answerOption.empty() or answerValueSet.empty()
que-5	Rule	Questionnaire.item	Only coding, decimal, integer, date, dateTime, time, string or quantity items can have answerOption or answerValueSet	(type='coding' or type = 'decimal' or type = 'integer' or type = 'date' or type = 'dateTime' or type = 'time' or type = 'string' or type = 'quantity') or (answerValueSet.empty() and answerOption.empty())
que-6	Rule	Questionnaire.item	Required and repeat aren't permitted for display items	type!='display' or (required.empty() and repeats.empty())
que-7	Rule	Questionnaire.item.enableWhen	If the operator is 'exists', the value must be a boolean	operator = 'exists' implies (answer is Boolean)
que-8	Rule	Questionnaire.item	Initial values can't be specified for groups or display items	(type!='group' and type!='display') or initial.empty()
que-9	Rule	Questionnaire.item	Read-only can't be specified for "display" items	type!='display' or readOnly.empty()
que-10	Rule	Questionnaire.item	Maximum length can only be declared for simple question types	(type in ('boolean' | 'decimal' | 'integer' | 'string' | 'text' | 'url')) or answerConstraint='optionOrString' or maxLength.empty()
que-11	Rule	Questionnaire.item	If one or more answerOption is present, initial cannot be present. Use answerOption.initialSelected instead	answerOption.empty() or initial.empty()
que-12	Rule	Questionnaire.item	If there are more than one enableWhen, enableBehavior must be specified	enableWhen.count() > 2 implies enableBehavior.exists()
que-13	Rule	Questionnaire.item	Can only have multiple initial values for repeating items	repeats=true or initial.count() <= 1
que-14	Rule	Questionnaire.item	Can only have answerConstraint if answerOption or answerValueset are present	answerConstraint.exists() implies answerOption.exists() or answerValueset.exists()

2.38.6 Notes:

• Questionnaires may be used to represent predefined forms or panels, referenced using items of type "group"
• Questions may be nested. The Questionnaire resource supports nested items beneath both items of type "group" (which doesn't capture an answer of its own) as well as beneath questions
• Groups and Questions may have linkIds allowing groups and question answers captured in a QuestionnaireResponse to be associated with their corresponding group or question.
• Questionnaire allows for flexible naming and structuring of its contents to reflect the flexible and varying nature of forms and questionnaires. It explicitly does not try to standardize or streamline exchange of its contents outside its context of use, although exchanging partners may further constrain its structure and flexibility using profiles to define standardized, reusable forms.
• Because of the lack of explicit support for Questionnaires in HL7 v3 , CDA Documents frequently used named sections with Observations to model Questionnaires. Such use cases should now use the Questionnaire Resource instead.
• The order of questions within groups, groups within groups and groups within questions is relevant and must be retained for display and capture.
• Display items allow the inclusion of instructions, background information and similar content within a questionnaire.
• In cases where it is necessary or appropriate to capture the reason why a response is missing (that is, why a particular question was not answered), there should be an explicit child item defined for the relevant question(s) in the Questionnaire; e.g. add a child question of "Reason not specified:" with an enableWhen operator "not exists" to the parent question.

2.38.6.1 Structured Data Capture

The base questionnaire resource is aimed at the capabilities of "most" healthcare systems that deal with forms and questionnaires. While the resource structure supports a reasonable degree of complexity, it doesn't provide the degree of control over rendering, question flow and data management needed by some portions of the healthcare space. Many of these more sophisticated requirements are addressed by a supplemental implementation guide called Structured Data Capture (SDC) . This implementation guide covers the following capabilities, plus several others:

• Rendering grids of questions, multi-column drop-downs, multi-language questionnaires, and other 'advanced' formatting capabilities
• Advanced dynamic questionnaires including calculated scores, enabling of questions and groups based on complex logic, drop-downs driven by answers to other questions
• Support for populating questionnaires from existing clinical data based on the current patient, encounter, etc., including the ability to render the form as HTML or to redirect to a website to complete unanswered items
• Support for extracting information from a completed QuestionnaireResponse to generate other FHIR resources such as Observations, MedicationUsages, etc.
• Support for completing 'adaptive' questionnaires (see below)

2.38.6.2 Adaptive Questionnaires

Some questionnaires might not provide a full listing of questions, instead relying on a service to interactively sending partially completed forms to a server which generates the next set of questions. As such, some questionnaires might be 'active' but have either no questions or an insufficient set of questions for their purpose. Further guidance on the use of such forms, can be found in the SDC implementation guide.

2.38.6.3 Using Questionnaires versus using Resources

There is considerable overlap between the information covered by Questionnaires and other Resources (especially FamilyMemberHistory, MedicationUsage, Observation, Procedure, etc.). Questionnaire's flexible structure can easily be misused to capture any data, even data that should be captured as separate Resources. The choice between using Questionnaires or separate Resources may be dictated by the procedure of collection and recording; e.g. if the data is captured as a physician-agreed (electronic) form, it might be impossible or undesirable to distill separate resources from it and capturing the data in a Questionnaire would be most appropriate.

However, data captured only in Questionnaires can be difficult to query after-the-fact. Queries against other Resources will not return data captured only in Questionnaires and querying against Questionnaires directly might not find all desired data, depending on how the questions may have been phrased or encoded over time or by different clinicians. Moreover, interoperability of such Questionnaires is limited, as interpretation of its contents is only known to the circle of parties that were involved in its definition: encoding data from such Questionnaires using more specific resources increases the availability of the information they contain.

It is entirely possible for data to exist in both QuestionnaireResponse and in other resources. For example, data may be captured in QuestionnaireResponse as part of an intake questionnaire. That data may then be propagated into the Patient resource (demographics), FamilyMemberHistory, AllergyIntolerance, MedicationUsage and Observation resources to allow the data to be queried and analyzed. The original QuestionnaireResponse instance can be retained for traceability purposes. If desired, a Provenance resource can be used to identify the Questionnaire as the data source for the other resources. For example, if a questionnaire question asks "what is your weight", an Observation with the appropriate Observation.code and the specified answer as the Observation.valueQuantity can be created.

2.38.6.4 Profiling Questionnaires

Profiling can be used to define the constraints of a set of Questionnaires - for example that a particular system only supports Questionnaires where answers have certain data types, only recognizes certain extensions, mandates the presence of certain metadata, etc. However, profiling should NOT be used to define the content of a specific Questionnaire instance. To define a Questionnaire instance, simply create an instance of Questionnaire as you would any other resource.

2.38.6.5 Structure of the Questionnaire

A Questionnaire is built out of two components, Questionnaire and item:

• The main component is Questionnaire, which holds information about the Questionnaire, like the identifier, publisher, date authored, title, etc. The Questionnaire contains zero or more items which define the content of the questionnaire (zero items allows for the possibility of narrative-only questionnaires, though these provide little computable information).
• Items have one of three sub-types, distinguished by the type element:
  • display items convey text to be rendered on the form that won't capture data and which won't contain nested items. This might include copyright or authorship information, instructions or other background information.
  • group items organize content of the questionnaire into sections, sub-sections, etc. Groups don't have answers associated with them directly, but generally contain child 'question' items which do.
  • question items ask a specific question to which an answer may be given. There isn't a single type for question items. Instead, the type conveys the data type of the answer for the question. If an item isn't a 'display' or a 'group', then it's a question which allows a particular type of answer to be gathered. Questions may also have nested content - groups and/or other questions. This way, one can model "panels" of questions which would only be relevant (and thus would only be displayed) depending on the answers of a parent question; e.g. a question "Did the patient receive treatment in the past six months?" would contain a nested group of questions asking for further details about the treatment. See an example from the Australian New South Wales blue book

Specific controls on dynamic display of groups, questions, etc. based on the answers to other questions is outside the scope of the base resource and are handled using extensions.

Group text is intended to provide a "label" for a collection of nested items. The text will often be rendered in a "heading" style. As such, it should be kept relatively short. Detailed instructions should be conveyed by a nested "display" item. It's not necessary to create groups in order to relate an instruction to a collection of questions - you can simply intermix display items and questions or groups, with the expectation that users will see the display text before encountering the following questions.

2.38.6.6 Group properties

Some properties defined at the 'group' level will impact the behavior of everything within the group. For example, if a 'group' item is marked as readOnly=true, then all items within that group are automatically treated as readOnly - even if they explicitly declare readOnly=false. The same holds for enableWhen. If a group is 'disabled' based on its enableWhen settings, then all child items are automatically disabled - regardless of whether they have enableWhen declared or how those enableWhen conditions might resolve. Some extensions (e.g. the SDC 'hidden' extension) behave in the same manner. Systems MAY choose to raise errors or warnings if questionnaires have conflicting settings. E.g. if a group is marked as readOnly=true and a descendant item explicitly declares readOnly=false. This wouldn't be because the behavior is unclear, but more to draw the author's attention to the fact that their desired behavior for the child will not be realized due to the setting of the ancestor group.

Behavior of parent 'question' items (i.e. questions with child groups or questions) can also influence descendant elements, but not as strongly. If a question is readOnly, that doesn't mean that child items are also readOnly. However, if a question is disabled, all descendant items are also disabled. Similarly, a 'hidden' question, would hide child elements as well.

2.38.6.7 Identifiers within Questionnaire

There are three different "identifying" elements within Questionnaire: identifier, id and linkId. Each serves very distinct purposes:

• The identifier element is used to reference the overall questionnaire in business terms. It is the number printed across the top of the form or listed beside the form when making a choice between alternate forms.
• The id attribute supported on each element is used for references within a resource, for example linking narrative to discrete elements. Ids are not generally displayed to end users
• The linkId element on questions and groups establishes a link between elements in a QuestionnaireResponse and their definition inside a Questionnaire. This is the only way to link between the groups and questions in a Questionnaire and QuestionnaireResponse. These are also not displayed to end users

2.38.6.8 Question Definitions

Questionnaires can be crafted using any questions the author can conceive and can be phrased in whatever manner is appropriate or convenient. However, standardization of questions and the constraints enforced on the accompanying answers increases the ability to compare data gathered across questionnaires. Items can be directly linked to an ElementDefinition using Questionnaire.item.definition which provides details for the item. If a definition is provided, then the following element values can be derived from the definition:

• code (from ElementDefinition.code)
• text (from ElementDefinition.label)
• required (inferred from ElementDefinition.min)
• repeats (inferred from ElementDefinition.max)
• maxLength (from ElementDefinition.maxLength)
• answerValueSet (from ElementDefinition.binding.valueSet)
• initial.value[x] or fixed[x] (from ElementDefinition.defaultValue[x] - depending on whether readOnly is set)

QuestionnaireResponse.item.type corresponds to ElementDefinition.type, however item.type is madatory in Questionniare, so it can't be 'populated' because it must exist for the item to exist at all. However, the values specified for item.type and ElementDefinition.type do need to correspond. Complex types such as Address or anything based on BackboneElement would correspond to 'group', while simple types would normally map directly.

In addition, extensions and elements that have corresponding extensions should also propagate. Specifically:

• Any extensions that have a context of both ElementDefinition and Questionnaire.item (e.g. maxSize) should propagate
• Any extensions defined for Questionnaire.item that directly correspond to elements on ElementDefinition should also propagate. E.g.:
  • ElementDefinition.minValue[x] -> minValue
  • ElementDefinition.maxValue[x] -> maxValue
  • There are Questionnaire extensions defined in the SDC IG that correspond to min, max, type.targetProfile and constraint

Any information provided in these elements overrides the information from the definition, and some are always required to be populated so that invariants can be enforced, etc. The url refers to an ElementDefinition in StructureDefinition, and always starts with the canonical URL for the target resource. When referring to a StructureDefinition, a fragment identifier is used to specify the element definition by its id (Element.id). E.g. http://hl7.org/fhir/StructureDefinition/Observation#Observation.value[x]. In the absence of a fragment identifier, the first/root element definition in the target is the matching element definition. Examples:

Value of definition	Explanation
http://hl7.org/fhir/StructureDefinition/Observation#Observation.effectiveDateTime	A reference to the standard Observation element effectiveDateTime
http://example.org/definitions/xxx	A reference to the logical model "xxx" that represents a data element
http://example.org/StructureDefinition/Oedema#Observation.category:XXX	A reference to slice XXX on the Observation category element on an Oedema Scale profile
http://example.org/StructureDefinition/Oedema|2.0#Observation.category:XXX	A reference to slice XXX on the Observation category element on an Oedema Scale profile, specifying version 2.0

The definitions may also be used to automatically pre-populate answers, or extract data from a corresponding pre-existing QuestionnaireResponse resource.

Note that LOINC codes implicitly define logical models whose elements can be considered question definitions.

NOTE: Even if a standard question definition is provided , information such as the question text, data type and value set SHOULD still be declared for the question. Systems processing the questionnaire might not have access to or support the ability to look up the question definitions from external sources. If the information is not included in-line within the questionnaire, other systems might not be able to render or use the Questionnaire. The questionnaire-definitionBased extension can be used to flag that a questionnaire requires the ability to resolve and use item.definition information to fully understand the Questionnaire. Systems that validate, render or otherwise process the questionnaire SHOULD check for this extension.

If an external definition is included along with question information such as question text, data type or value set, it is expected that the content for the question and the referenced definition would be in alignment. However, FHIR does not dictate what degree of alignment is required; e.g. Does the question text need to match exactly? Is it legitimate for a question to constrain the allowed value set of possible answers? These rules will need to be established within implementation environments.

2.38.6.9 Question types

The codes for the data type for each question are slightly different than the data types allowed in the QuestionnaireResponse resource. Where the names are the same (ignoring case), the "answer" must use the specified type. Where the names are different, the mappings are as follows:

Questionnaire AnswerFormat code	QuestionnaireResponse data type
text	string
url	uri
coding	Coding

2.38.6.10 Permitted values for questions

Many questionnaires place constraints on the allowed list of values for a given question. FHIR supports this notion through the item.answerValueSet or the item.answerOption element.

The "answerOption" mechanism is simplest - all possible answers are listed in-line with the question using the item.answerOption element. Maintenance of the set of permitted question answers involves maintenance of the questionnaire itself.

The "answerValueSet" mechanism is more sophisticated. Rather than listing the possible answers directly, the item.answerValueSet element refers to a ValueSet resource. This approach adds complexity for questionnaires having a simple list of strings as choices for a question, but provides several benefits, including:

• Questionnaires that reference codes from externally defined code systems have a means of doing so
• Answer sets can be shared across questions (and there are many questionnaires where this capability is useful)
• The full capability of value sets can be brought into play, including the ability to use ConceptMap to link and translate from questionnaire-specific codes to other codes, the use of multiple display names (e.g. different languages), the ability to use coded ordinals, and the ability to allow choices from larger value sets (e.g. "all SNOMED CT procedure codes")

In many cases, the set of code choices will be specific to a given questionnaire and should be maintained as part of the questionnaire. In this case, the referenced ValueSet can be included as a contained resource. All contained ValueSets are listed together and then are referenced by the individual questions as necessary. Alternatively, the item.answerValueSet element can reference the value set in a version-specific manner. This ensures that the Questionnaire will not adopt a new version of the referenced value set without revising the Questionnaire to point to that new version - putting the author of the Questionnaire in control of any changes.

2.38.6.11 Useful Value Sets

Many questions have a common set of possible codes for their answer. These value sets may be useful to help, and when referenced by full URL, do not need to be provided as part of the questionnaire:

• Yes | No | Don't Know: http://hl7.org/fhir/ValueSet/yesnodontknow

2.38.6.12 Handling Boolean Answers

In a questionnaire response, a question of type 'boolean' can have 3 possible states - unanswered, answered true, and answered false. Users will generally need to be able to toggle through all three states. If a default value is specified and the element is mandatory, a simple control with only true and false options will suffice. However, if a three-state selection is required, the typical controls used in HTML and other rendering technologies for booleans might not be appropriate. E.g. a checkbox that can only convey 'true' or 'false' will not be able to differentiate 'unanswered' and thus is generally not appropriate. If a tri-state control is available, that would work well. Alternatively, a set of radio buttons allow choices of true, false or "no answer" could also work.

As well, when enableWhen expressions are used that reference boolean elements, designers should consider whether "non-answered" is a possible value for boolean questions and design their enableWhen logic accordingly.

2.38.6.13 Questions with multiple answer types

In some questionnaires, it may be possible to respond to a question with multiple types of answers. For example, capturing a coded answer plus free text, capturing a coded value plus a numeric priority, etc. In FHIR, this is handled through nested questions. Each question has a single data type. However, each question can have nested child questions. These nested child questions can have text (e.g. "Please specify") or can have no text at all if the appropriate guidance is provided by the parent question or group.

2.38.6.14 Questionnaires with Math

Many questionnaires involve computations on questionnaire answers, e.g. tabulating scores. To help with associating numeric values to coded answers, the ordinalValue extension can be used to define the numeric weighting of a code defined in a value set or in the questionnaire itself.

In addition, there are extensions for defining the dynamic value of an element using expressions. For more information, see the Using Expressions and Documentation Template topics in the Clinical Reasoning module.

2.38.6.15 Questionnaire workflow

Once a Questionnaire is defined, there's often a need to 'assign' a Questionnaire to a particular individual to request them to complete it. This is not done using the Questionnaire resource directly. Instead, the Questionnaire is referenced as an 'input' or argument using one of FHIR's workflow patterns. The most common mechanism is by defining a stand-alone Task that references the Questionnaire and seeks completion. The SDC implementation guide defines profiles and guidance for using this mechanism.

2.38.6.16 More advanced questionnaires

The capabilities of the Questionnaire resource are fairly simple and try to adhere to what most systems that deal with questionnaires would be capable of. However, there are lots of systems that require more sophisticated capabilities, such as:

• Greater control over rendering, including tables, read-only values, hidden answers, multi-column drop-downs
• Greater control over question flow, including formula-based rules for conditional display of elements
• Ability to pre-populate forms with data found in the client system
• Ability to define how to convert a completed QuestionnaireResponse for a Questionnaire into a collection of Observations and/or other resources

Extensions have been defined for all of these purposes and many more. (Questionnaire has the most 'core' extensions of any resource to-date.) A list of these extensions can be found here. However, some of the extensions are complex and work together in particular ways. To support more advanced questionnaire implementation, the Structured Data Capture (SDC) implementation guide has been created to provide non-country-specific guidance on the use of most of these extensions and sets expectations for systems wishing to support more complex forms.

2.38.7 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Expression	In Common
combo-code	token	A code that corresponds to one of its items in the questionnaire	Questionnaire.code | Questionnaire.item.code
context	token	A use context assigned to the questionnaire	(Questionnaire.useContext.value as CodeableConcept)
context-quantity	quantity	A quantity- or range-valued use context assigned to the questionnaire	(Questionnaire.useContext.value as Quantity) | (Questionnaire.useContext.value as Range)
context-type	token	A type of use context assigned to the questionnaire	Questionnaire.useContext.code
context-type-quantity	composite	A use context type and quantity- or range-based value assigned to the questionnaire	On Questionnaire.useContext:   context-type: code   context-quantity: value.as(Quantity) | value.as(Range)
context-type-value	composite	A use context type and value assigned to the questionnaire	On Questionnaire.useContext:   context-type: code   context: value.as(CodeableConcept)
date N	date	The questionnaire publication date	Questionnaire.date
definition N	uri	ElementDefinition - details for the item	Questionnaire.item.definition
description N	string	The description of the questionnaire	Questionnaire.description
effective	date	The time during which the questionnaire is intended to be in use	Questionnaire.effectivePeriod
identifier	token	External identifier for the questionnaire	Questionnaire.identifier
item-code	token	A code that corresponds to one of the items in the questionnaire	Questionnaire.item.code
jurisdiction	token	Intended jurisdiction for the questionnaire	Questionnaire.jurisdiction
name N	string	Computationally friendly name of the questionnaire	Questionnaire.name
publisher N	string	Name of the publisher of the questionnaire	Questionnaire.publisher
questionnaire-code	token	A code that matches one of the Questionnaire.code codings	Questionnaire.code
status N	token	The current status of the questionnaire	Questionnaire.status
subject-type N	token	Resource that can be subject of QuestionnaireResponse	Questionnaire.subjectType
title N	string	The human-friendly name of the questionnaire	Questionnaire.title
url N	uri	The uri that identifies the questionnaire	Questionnaire.url
version N	token	The business version of the questionnaire	Questionnaire.version