Structured Data Capture
4.0.0-ballot - STU 4 ballot 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-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

Advanced Form Rendering

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.

Extension Overview

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:

  • Code: This is the name of the core element or the unique label for the extension. The extension label appears at the end of the URL of the 'source' (below). In this implementation guide, extensions are generally just referred to by their code.
  • Source: This will either be 'N/A', 'Core', 'Questionnaire' or 'SDC'. 'N/A' indicates that the element is part of the core spec, not an extension. 'Core' indicates that the extension is defined in the core specification and is not specific to the Questionnaire resource. The base URL for 'core' extensions is 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-
  • Location: This indicates where the element or extension can appear. Possible values are 'Questionnaire' (for those that appear directly on the 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.
  • Data Type: Indicates what content the element or extension can have.

Each extension will then have explanatory text that provides additional guidance on how the extension is used.

Text Appearance

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.

Control Appearance

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.

Additional Display Content

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 name.first().given.first() for the first name of a Patient or Practitioner.

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.

Other

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.

Additional rendering considerations

  • Questionnaires will be rendered by a variety of tools on a variety of devices. Not all tools will necessarily support all extensions - or even all core elements. Authors should recognize this and only depend on rendering extensions if they're confident that all systems using the Questionnaire will support the needed extensions. Note that this does not mean that extensions cannot be used, only that the Questionnaire should be safe to use if extensions that the author is not certain will be supported are not supported. For example, avoid referring to 'the red text' if you're not certain the text will be rendered as red (and that those who are color-impaired will have an alternative mechanism of recognizing the text as 'red').
  • Tools that use HTML to render forms should consider disabling browser-based auto-completion unless such behavior is desired

Example

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.

Language and translations

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 allows the language of a particular (or any other data type) to be identified
  • translation allows additional repetitions in alternate languages to be communicated. (The language for each translation would be communicated using the above 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.