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-ballot 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 |
The base questionnaire resource provides limited capabilities around rendering. The label
and text
elements for each item
are rendered in order, possibly with renderer-specific styles reflecting whether they represent the label for a group, the content of a display item or
the text of a question. As well, the options for choice questions (whether enumerated or expressed as a value set) are made available to the user through
renderer-determined controls. In fact, the render makes the choice of controls to capture the answers to all question types.
For many questionnaires, that's good enough. However, for some types of forms, there's a need for the author to have greater control. The core specification defines a few core elements and several extensions for this purpose - both questionnaire-specific as well as general-purpose that can appear in other places as well. This implementation guide defines several more. In addition, this guide defines the sdc-questionnaire-render profile which highlights what extensions are available and where they are intended to be used. It also identifies specific 'must support' extensions that systems that claim to support SDC rendering SHALL be capable of authoring and/or rendering, as befits the CapabilityStatement(s) they claim conformance to. An example for sdc-questionnaire-render profile can be found here.
The following sub-sections describe the different core elements and extensions available to control the 'rendering' of a questionnaire. Each extension includes the following information:
http://hl7.org/fhir/StructureDefinition/
. Questionnaire
indicates an extension defined in the core specification that is specific to Questionnaires. The base URL for 'Questionnaire' extensions is
http://hl7.org/fhir/StructureDefinition/questionnaire-
. SDC extensions are defined within this implementation guide. Their base URL
is http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-
Questionnaire
element), 'item' (for those that can appear on any type of item), 'question' (for those that can only appear on question
items), or 'group' (for those that can appear on group items). In some cases, additional restrictions/guidance will be provided.Each extension will then have explanatory text that provides additional guidance on how the extension is used.
The following extensions change the appearance of the item or text elements within the item - i.e. the item prefix and/or item text
Code | Source | Location | Data Type | Example |
rendering-style | Core | Questionnaire.title, item.prefix, item.text, item.answerOption.valueString, item.answerOption.valueCoding.display, valueset-label, Valueset.compose.include.concept.display, Valueset.compose.include.concept.designation.value (and expansion equivalents), CodeSystem.concept.designation.value | string | example |
This element allows the full capabilities of the HTML style attribute to be applied to the title of a questionnaire, or to the label or text of a questionnaire item or to the label of an option. This might mean changing the font or color, changing font style such as bold, italics, small caps, etc. Conformant systems are allowed to ignore this extension unless the rendering-styleSensitive flag is set to true. |
||||
rendering-xhtml | Core | Questionnaire.title, item.prefix, item.text, item.answerOption.valueString, item.answerOption.valueCoding.display, valueset-label, Valueset.compose.include.concept.display, Valueset.compose.include.concept.designation.value (and expansion equivalents), CodeSystem.concept.designation.value | string | example |
This element provides an alternate representation of the string value of the extended element that makes use of a subset XHTML. (Specifically, the XHTML subset allowed by the core specification.) This extension allows applying different styles to different portions of the text (via <span/>, <b/> and similar elements). It also allows embedding structure elements such as bullets or even tables in item.text elements. XHTML must be base64-encoded due to constraints on the values of extensions. For title and label, the XHTML should be an inline element, while text can also include block-level elements (paragraph, ul/ol, etc.). Conformant systems are allowed to ignore this extension unless the rendering-styleSensitive flag is set to true. |
||||
displayCategory | Questionnaire | item (where type='display') | code | example |
For items with a type of 'display', this indicates what kind of display item it is so that systems can apply differential formatting based on the purpose of the display element. In the absence of a declared itemControl this could influence the mechanism used to render the display text (e.g. help-button or separate page for help text). Regardless of the presence of itemControl, it can also influence the formatting of the text. For example, instructions might appear in a different font than security rules or with a different background or different surrounding box. The specific means of display are left open to the form filler, however systems that support this extension SHALL visually distinguish display items with different categories. |
||||
openLabel | SDC | item (where type='open-choice') | string | example |
For items with a type of 'open-choice', this extension provides a label text to display beside the free-text and/or unrestricted type values. E.g. 'Other, please specify', or 'Additional condition', or 'More reason(s)', etc. |
||||
hidden | Questionnaire | item | boolean | example |
This allows flagging items that should not be displayed at all. In theory, it can be used for any item, but in general, it only makes sense for questions and groups. It allows for answers to be captured behind the scenes using the behavior and/or population mechanisms. For example, hidden scores, hidden source data, hidden data needed for extraction. If an item is hidden, then all items below it will be hidden as well. Hidden items are automatically treated as readOnly - users cannot edit what they cannot see or navigate to. NOTE: Hiding data from the enterer is not a solution to data privacy/security concerns as any questionnaire answer must be presumed to be potentially available to any consumer of the questionnaire in some manner. |
||||
itemMedia | SDC | item | Attachment | example |
Media to render/make available accompanying the question being asked or group or display item being rendered. |
||||
itemAnswerMedia | SDC | item | Attachment | example |
Media to render/make available as an accompaniment to a specific answer option. |
The following extensions influence what controls are used to capture question answers - or how those controls are displayed.
Code | Source | Location | Data Type | Example |
itemControl | Questionnaire | item | CodeableConcept | example |
This allows the selection of a specific control type for the answer for a group, question or display item. The set of available codes has specific sub-sets for group, display and question items. Those for group provide control over how the child items within the group are organized or where the group appears within the overall questionnaire (e.g. as a header or footer). The 'text' items provide guidance about how the display item should be rendered, including relative position with respect to the question and answer and by what mechanism the display text should be rendered (fly-over, help-button, overlay on control or simple in-line text). Finally, the 'question' items allow the choice of control for selecting an answer. For choice, open-choice, and Reference items, it allows autocomplete, drop-down, check-box, radio-button and lookup controls. For numerics, dates and times, slider and spinner controls are also options, as well as the more traditional text-box. When groups are rendered as tables, the width and choiceColumn extensions can help control the formatting of the table. |
||||
choiceOrientation | Questionnaire | question (where type='choice','open-choice'), other items with choice options | code | example |
Normally, it's up to the render to determine whether to display choices horizontally or vertically or to define multiple columns of choice options. This extension allows forcing the choices to be rendered horizontally or vertically. |
||||
sliderStepValue | Questionnaire | question (where type='integer') | integer | example |
For questions with a type of 'integer' and a itemControl of 'slider', this allows indicating the increment with which the slider will move between the minValue and the maxValue. For example, incrementing by 2, by 5, by 10, etc. Only values at the specified interval increments can be selected as answers. |
||||
width | SDC | question | Quantity | example |
This is used for question items that are the child of a group item with an itemControl whose value is 'htable' or 'gtable' - i.e. where each question within the group occupies a column. This extension identifies what the permitted width is for the column that contains the question. It can either be specified as a percentage of the overall table width (quantity.code = '%' and system='http://unitsofmeasure.org') or pixels (quantity.code and system are omitted). See choiceColumn for guidance on setting column widths for choice-based columns. |
||||
collapsible | SDC | group, question | code | example |
This allows the child items of a group or question item to be displayed in a collapsible form (toggle between showing and hiding the child items). This is very useful for authors dealing with particularly long questionnaires. The author might choose to present certain sections collapsed which will provide the user brief overviews before digging into nested items. |
The following extensions cause additional information to be displayed as part of the form
Code | Source | Location | Data Type | Example |
supportLink | Questionnaire | item | uri | example |
This allows associating a link to a question, group or display item. When this extension is present, an icon indicating that a link is available should appear immediately following the text of the item. Clicking on the link will allow the user to navigate to additional descriptive detail, generally on a separate page/tab. This extension allows the use of links without injecting the need to support full HTML via the rendering-xhtml extension (which would also allow hyperlinks, though they could appear at any point within the text and would provide control over the text or image used to launch the link). |
||||
choiceColumn | SDC | question (where type='choice', 'open-choice' and 'reference') | complex | example |
This extension is used when users are selecting from a list of possible choices and there's a desire to control what information is displayed in the list of possible candidates. It has two modes of operation: With choice and open-choice, it allows selection of display names and/or code system properties that should appear. For example, if a 'Medication' code system includes properties for form, preferred route and strength, that information could be displayed alongside the 'display name' for the item. Alternatively, a questionnaire might present the display names for the concept in English, Spanish and French. The path is set to 'display' for the code's standard display name. It's set to the property.code for a property value. It's set to the language code for designations in a particular language (only works if there's only one designation for the language). It's set to the designation use code for a selected designation (only works if there's only one designation for that use).
With a Reference it allows selection of fields from the resource - for example the first name, last name and phone number of a provider.
The path is the FHIRPath to navigate to the element from the resource root. For example Regardless of the item.type, multiple repetitions of the extension can be specified to indicate multiple columns. The columns are displayed in the same order as the extensions appear on the Questionnaire.item. For each column, the extension indicates the label to be displayed at the top of the column and the width of the column (following the same guidelines as for width). It's also possible to indicate which column(s) should be used to construct the Coding.display or Reference.display value. For choice and open-choice which map to Coding, only one extension repetition can have 'forDisplay' set to 'true'. That column must either have a path of 'display' or must specify the language or use of a code designation (i.e. not a code property). For Reference items, if multiple columns are marked with 'forDisplay', the display value used will be a space-separated concatenation of all columns so-marked. NOTE: If no 'forDisplay' columns are marked, or no columns are listed for a Reference questionnaire item, it's up to the form filler to decide what to display and what, if anything, to capture in the display element. |
||||
optionPrefix | Questionnaire | Questionnaire.item.answerOption | string | example |
This allows declaring a prefix to be displayed in front of an option (e.g. "(a)", or "1."). It can be defined for options listed directly in the question, but also for entries in value sets referenced by a question. (Note that these prefixes can also be supplemented with the rendering-style and rendering-xhtml extensions. |
||||
valueset-label | Core | ValueSet.compose.include.concept, ValueSet.expansion.contains | string | example |
This serves the same purpose as optionPrefix, but allows the definition of the prefix to occur in a valueset referenced by answerValueSet instead of listing the options directly using answerOption. |
||||
entryFormat | Core | question | string | example |
This provides a string that helps to guide entry of formatted text and often appears directly "behind" the control to be filled. For example, "nnn-nnn-nnnn" for a North American phone number, "YYYY-MM-DD" for a date, "nnnn nnnn nnnn nnnn" for certain types of credit card numbers, etc. |
||||
shortText | SDC | item | string | example |
This provides a short text for an item. This is useful as an alternate display when rendering the questionnaire on smaller devices like a mobile phone. |
The following items provide general control over rendering of the form at large
Code | Source | Location | Data Type | Example |
required | N/A | group, question | boolean | example |
Both groups and questions can be marked as 'required'. For groups, that at least one question within a given repetition of the group must have an answer. For questions, it means the question must have at least one answer. Typically, items that are 'required' will have a visual cue indicating this. It could be managed by changing the background of the answer control, bolding the question text, or some other mechanism. Also see guidance for this element on the behavior page. |
||||
repeats | N/A | group, question | boolean | example |
Both groups and questions can be marked as repeating. For groups, that means all content within the group can be repeated multiple times. The itemControl extension can give specific guidance about this, for example treating each repetition as a row in a table. Without guidance, it's up to the Form Filler to decide how to handle allowing the creation of additional repetitions (or their removal) and how to handle labeling the questions within - whether they should be repeated on each repetition or just listed once for the first occurrence. For questions that are marked as repeating, the results will be captured as multiple answers for one question. In many cases, the question text will only need to appear once, and the user can fill in as many answers as they like. However, for question items that contain nested questions, it may be necessary to repeat the question text for each repetition to ensure that it still appears on the user's screen. Also see guidance for this element on the behavior page. |
||||
readOnly | N/A | question | boolean | example |
If an element is read-only, it means the user cannot adjust the value which can mean a change to the control used to render the form. Technically there's no need to display a text box, drop-down or other controls if the value cannot be changed. However, it's generally still desirable to use the same controls so that it's clear that the question answer is still an "answer" and so that read-only information does not stand out significantly from other answers. However, there should still be a visual indicator that the element cannot be edited. This might include changing the background color, changing the font for the question text or some similar visual cue. Also see guidance for this element on the behavior page. |
||||
rendering-styleSensitive | Core | Questionnaire | boolean | example |
If set to true, this indicates that the 'style' information conveyed by the rendering-style and/or rendering-xhtml are considered critical to the accurate rendering of the questionnaire (and appropriate capture of information using the questionnaire). For example, there are instructions or other text that refer to specific colors or styles and a user would not be able to fill out the questionnaire safely or appropriately if those colors or styles are not accurately rendered. As a result, only systems that can render all such extensions appropriately are considered 'safe' to render the Questionnaire. All other SDC systems SHALL raise an error. |
||||
optionalDisplay | SDC | item | boolean | example |
This extension is used when a Questionnaire is defined as a 'baseline' for derived Questionnaires - i.e. when organizations can adapt the Questionnaire to their specific workflow by excluding certain questions. This extension can be used to flag questions, groups and display items that can be removed from derived questionnaires. As such it affects rendering indirectly by adjusting the content displayed in the design phase. |
This implementation guide includes an example questionnaire. Each question in this questionnaire is itemized in the Examples page that shows how the extensions above are intended to be used and identifies how such controls might appear in a rendered questionnaire.
In some environments, it may be necessary for a questionnaire to support multiple languages. The rendering tool would select the appropriate language based on a configuration setting, or perhaps would display all available languages and the user would read the one they are familiar with. Systems MAY choose to provide support for identifying language and translations. If they do, they MAY do so using the generic language and translation extensions FHIR defines:
language
extension)These extensions can be used on absolutely any string or markdown element on Questionnaire, ValueSet, or any other resource. The base string should be the primary language of the questionnaire. It is what will be rendered by systems that do not support the translation extension or by systems whose language preference is other than one of the languages provided.
Work is underway to support a publishing process that allows maintenance of a set of language translations in separate .po files. This will allow for translation strings to be maintained using the same syntax as commonly used by professional translators and then automatically re-incorporated into FHIR resources, either through the insertion of translation instructions, or by substituting the primary language with an alternative language.
When work on this process is complete, it will be linked to on the HL7 Confluence page.