This expression sets a variable that is available for use in expressions within the same item and any descendant items. It has two main uses:

• It allows a complex calculation to be done once and used in multiple other places. (E.g. Determining the score for one group within the questionnaire response that will then be used in calculations on subsequent groups.)
• It allows a calculation to be done closer to the root of the questionnaire response or at the root of the questionnaire response where there is access to more of or all the answers from the questionnaire response. The calculated value might then be used as the answer to a descendant question. (Expressions cannot access answers that are not descendants of the current node.)

The content type of a variable can be pretty much anything. It can be a collection or an individual item. It can be a simple element, a complex type, a resource or even a Bundle of resources.

The variable can be referenced by its name. Variable expressions SHALL specify a name. It is not allowed to define variable names that are already reserved by the base specification. (E.g. %questionnaire, %ucum, etc.) It is also prohibited to define the same variable more than once on the same node, though it is possible to override a variable on descendent nodes. However, it's perfectly fine to have two variables with the same name if those extensions variables don't share the same context - for example the variables are declared on sibling items.

This is the most sophisticated of the three different mechanisms for defining the allowed set of answers to a set of questions. (The others being the Questionnaire.answerOption and the answerValueSet core elements. (This extension is mutually exclusive with the other two mechanisms.) This expression must evaluate to a collection of elements with the same type as the item.type or, if the type was Reference, to resources allowed as the referenced type.

This expression could be based on other answers within the questionnaire. If the allowed set of answers for a question change after an answer has been specified (whether via population or user entry), the prior answer SHOULD be retained in the user interface until such time as the questionnaire is marked as 'complete', even if invalid. This is to minimize the impact on users if they accidentally toggle elements within the form that govern the answerExpression. However, in some cases, this will not be possible depending on the data entry controls. Systems MAY wipe the answer on the grounds that a change to the list of possible answers might result in different answers.

If an answer becomes invalid based on evaluation of answerExpression, calculated values falling out of range, etc., the form SHALL flag the answer as invalid and prevent the QuestionnaireResponse from being marked as 'complete'.

Note that if the answerExpression relies on content outside the QuestionnaireResponse (e.g. launch context or query results), the ability to consistently check the validity of the QuestionnaireResponse - particularly for downstream systems - may be difficult. One potential solution is to populate internal (and potentially hidden questions) with information passed in by context or found through query such that validation of answers can be based entirely on information stored within the QuestionnaireResponse, though privacy and/or storage considerations may make this impractical in some cases.

This expression serves the same purpose as the initial.value on Questionnaire.item, except that rather than specifying a fixed value, the value is calculable. Like initial.value, initialExpression is evaluated only once. The value is set on initial creation of the QuestionnaireResponse or upon the question first becoming enabled. NOTE: This implementation guide does not prohibit lazy initialization (e.g., delayed calculation of an answer, delayed initialization of a field, etc.), but Questionnaire authors cannot assume implementors will use lazy initialization.

If used for a readOnly and/or hidden element, initialExpression essentially calculates a 'fixed value' for the element. If used for an editable element, this extension sets the initial value for the element. Since both initial.value and initialExpression generate values before the user has access to the form, it is not allowed to have both present on a Questionnaire.item. In scenarios where the user edits the response directly or edits other dependent elements that cause the re-evaluation of the response (e.g., calculatedExpression), the value MAY subsequently be overridden by the user authoring or editing the response (see considerations in Expression-based Population).

In theory, this expression can rely on the values of the answers to child questions or on variables calculated from the values of other questions, however such questions would have to have initial values (see the discussion below on dependencies). Most typically, it will draw on launchContext extension and itemPopulationContext extension to populate questionnaire elements based on information available from outside the QuestionnaireResponse.

Examples of use for Form Behavior might include defaulting one date or provider in a form to one entered earlier in the form, defaulting a selected location based on patient address, etc. For population, this is the primary mechanism of populating fields. Information passed in launchContext or queried from the health record is used to determine the initial value for the field. The response author then can review and potentially adjust the values. Finally, for extraction, this can be used to fill in 'hidden' elements that are needed for extraction but are not actually seen or edited by the user (e.g., FHIR resource ids when updating existing records).

It is possible for the value of an initialExpression to be referenced by name within other sibling expressions or by expressions on descendant items. However, this is not likely to be common. As such, initialExpressions only need to declare a name if their value will be referenced elsewhere.

This extension is used to support data entry. It is only invoked when the user is entering/editing the answer for the question linked to the candidateExpression. It is used when a population process cannot determine the specific value to fill in to a form (like when an answer depends on answers to other questions that are unknown at the population phase), but it can identify a list of candidates to choose from. For example, forms might ask for relevant co-morbidities, other practitioners to inform, etc. The specific answers require human decision-making, but this expression can provide a list of initial candidates based on the patient's recorded health conditions, the patient's care team members or others involved in their care, etc. Another example might be filtering a list of possible dosage instructions based on the patient's age, gender and the previously selected indication but where there are still possibly multiple recommended options.

While this expression could be based on other answers within the questionnaire, most typically it will be based on information found within the health record. The expression must evaluate to a collection of elements with the same type as the question answer. For choice and Reference questions, choiceColumn can be used to manage display.

NOTE: the set of candidate expressions is intended to be a starter set, not exhaustive. The user needs to be free to enter or look-up additional values. The overall set of values from which answers are allowed to be selected (typically independent of what happens to be in the patient record) is defined by answerExpression. Systems SHOULD allow multiple selections in situations where the question is marked as 'repeating' and multiple answers are therefore valid, but SHOULD only allow one answer for non-repeating questions.

As an example, a question might ask "Please identify any concurrent medications that might be related to the reaction". A candidateExpression could provide a list of all of a patient's known current medications (via medicationrequest, medicationstatement, etc. On the other hand, an answerExpression might evaluate to the value set of medications appropriate for the jurisdiction in which the questionnaire is being completed, allowing the user to select medications that were not listed in the patient's record in addition to the candidates found.

CandidateExpressions may use name in situations where a user will select a candidate for one question which will in turn lead to population of other questions. For example, if in the above example, a question about concomitant medications might have child questions that capture information about the dose, start date or other information. The query that returned the candidates might be referenced by name in initialExpressions for child questions that use the parent answer together with the candidates to grab the additional details about the selected medication to populate the child answers.

This is similar to candidateExpression extension, in that it is also only used when the user is editing the answer for the question associated with the candidateExpression. However, instead of giving candidate answers that can simply be "selected", this option instead presents potentially relevant information. For example, a question might be "Has the patient been admitted for this or a related condition in the past year?". To help guide the answers, the contextExpression could retrieve a list of admission reasons for that patient for encounters in the past year and display that with a label of "Reasons for admissions in the last year". The user completing the questionnaire could then use that information to guide whether they choose to answer 'yes' or 'no'. The extension is complex including both an expression that defines the results to make available as well as a label so the user completing the Questionnaire understands what the data being returned means.

ContextExpression is not intended for read-only questions. The user must answer a question - but the user may want to look at context information to help guide the answer.

Also, like candidateExpressions, contextExpressions will rarely, if ever, declare a name element.

This expression allows for dynamic calculation of answers to questions as other questions are answered. It behaves similarly to initialExpression extension, but instead of only setting its value when the QuestionnaireResponse is originally created or when a question is enabled, the value updates continuously as the answers to dependent questions change. This expression will be most used for displaying scores, but can be used for any calculated element - patient age (based on current date and birth date), BMI (based on recent weight and height), estimated cost (based on selected items and quantities), etc.

Managing the updating of calculatedExpressions can be tricky as they can have many dependencies. Implementing an event-based listener approach may prove more efficient than simply recalculating all expressions every time any value in the questionnaire changes anywhere. Also, refer to the section below on dependencies that explains how to handle order of evaluation and other concerns.

In most cases, 'calculated' answers will be marked as 'readOnly', however in some cases it may be legitimate to override a calculated element, for example if the calculation cannot be made due to non-available information, but the user still knows the calculated value. This statement applies to any context information of any sort. [For example, it might be possible to enter an age but not a date of birth. If a user has edited a calculated value, it SHOULD no longer be changed when other answers in the questionnaire response change. When loading a previously persisted QuestionnaireResponse, the determination of whether a user has edited the calculated field can be determined by whether the calculated value differs from invoking the calculation on the current values in the questionnaire. (As a side-effect, this means that calculated values based on 'context' information such as an age calculated based on 'now' SHALL be treated as user-edited when subsequently opening the QuestionnaireResponse and SHALL NOT update to reflect the new current date. Client systems MAY provide the user with the ability to reset calculated fields to the calculated value).]

Like initialExpression, it is possible for the value of a calculatedExpression to be referenced by name within other sibling expressions or by expressions on descendant items. However, this is not likely to be common. As such, calculatedExpressions only need to declare a name if their value will be referenced elsewhere.

NOTE: query information can change over time and thus influence the results of calculatedExpression.

This expression does the same thing as the Questionnaire.item.enableWhen structure (and is mutually exclusive with it), but allows for more complex logic like nested bracketed expressions with AND/OR, use of NOT, comparison of values across questions, etc. (If enableWhen can meet the need, it ought to be used instead as it will be more broadly supported.) Specifically, enableWhenExpression allows more complex logic such as support for different types of logic operators (e.g. 'and', 'or', 'not', 'nand', 'nor') among conditions and a mixture of them (e.g. "Enable if Q1=5 and Q2 nand Q3 are true"). It also allows for logic to be based on calculations across questions (possibly leveraging variable) or even based on values passed in by launchContext or queried from outside the questionnaire.

Like calculatedExpression extension, enableWhenExpression needs to be evaluated each time any of the answers it depends on changes. The same event monitoring approach may be appropriate (and even shared). And the dependencies section will be relevant here as well.

The Expression.name element only needs to be populated in the unlikely circumstance the expression is going to be referenced by other expressions on the same item or in descendant items.

This is a complex extension that performs a similar function to enableWhen, except that rather than acting on items, it acts on individual answer options within an item. The extension does NOT define what options exist. Instead, it toggles a subset of the possible options (specified in the option component) based on the result of evaluating the expression in the expression component.

The base set of options available comes from answerOption, answerValueSet or answerExpression. If any of the options listed in the option component of this extension is not one of the options available for the item, then that SHOULD be treated as an error in the Questionnaire when validating the Questionnaire. However, when completing forms it is safe to ignore any non-available options.

More than one repetition of this extension is possible. If an option appears in more than one repetition, then it SHALL be enabled if it appears in ANY of the extensions whose expressions are evaluated as true. I.e. the expressions that pertain to a given option are treated as 'or'.

AnswerOptionToggleExpressions will generally never need a 'name' declared.

This expression identifies the resource(s) that correspond either to an overall questionnaire, a group within the questionnaire or, occasionally, a single question. The results of executing the specified expression are used to indicate the resources used to populate the item when performing population and also indicate the relevant resource type.

If an expression results in multiple repetitions for a single for the root Questionnaire or for an item where 'repeat' is false, it is an error and no population can occur.

This expression does not actually populate an element (that's handled by initialExpression). Instead, it establishes a variable that is used to aid in population, often by providing a variable that can be used within the initialExpression that determines what the element is be populated with.

Expression.name SHALL be populated when this extension is being used for expression-based population.

An invariant that SHALL or SHOULD be satisfied before responses to the questionnaire can be considered "complete". It contains an expression as part of the complex extension, but SHALL never have a 'name'.

Note: The relative path SHOULD follow the same syntax as OperationOutcome.expression.

Library allows queries, CQL and FHIRPath expressions to be maintained independently from the Questionnaires that use them. This means that the "programmatic" content of the Questionnaire can be updated and adjusted without revising the Questionnaire, which may be appropriate in certain form management environments. It also means that the population and extraction mechanisms can be adjusted as data representations evolve or be adjusted to reflect the needs of additional data repositories. Additionally, it allows re-use of expressions across questionnaires.

This extension identifies libraries that the questionnaire relies on for some or all its expressions. (The mechanism by which expressions point to library content is discussed above.)

The launch context allows information to be passed into the execution environment based on the context in which the Questionnaire is being evaluated. For example, what patient, what encounter, what user, etc. is "in context" at the time the questionnaire response is being completed. Note that this context could potentially change if a questionnaire is edited after it was initially created, which means that if launchContext elements drive calculatedExpression elements rather than initialExpression elements, they'll be updated to reflect the new user.

Launch context information is passed to the QuestionnaireResponse evaluation process by the launching application. It SHOULD pass whatever contexts it is aware of. SDC systems SHOULD support all four of the contexts defined in this specification (e.g. Patient, Encounter, Location, User), but are free to support others. The selected contexts mirror those used by the SMART on FHIR specification.

The resource corresponding to each context SHALL be made available at the indicated launch context name as if the value had been set in a variable. It is not allowed to define names that are already reserved by the base specification or by other variables in the questionnaire.

The allocateId extension is used to allocate a new uuid to be able to use in fhirpath expressions during extraction, specifically to support cross referencing resources in the output transaction bundle which still using server side ID allocation and POST(s).

It's value is allocated once for each context that it appears in the QR.
i.e. if it is defined at the root, it will be allocated once.
If it is allocated on a repeating group, it will have a new value for each iteration of the group.
Any child items SHALL use the value that was allocated for the parent item.

The fhirpath expressions in the definitionExtract are used to provide dynamic values for the bundle.entry.request and bundle.entry.fullUrl properties. These will be evaluated after the allocateId variables have been resolved on the item (and any parent items).

The fhirpath expressions in the definitionExtractValue provides dynamic values to set a value in the output resource property (based on the definition property in the extension).
These will be evaluated after the allocateId variables have been resolved on the item (and any parent items).

Note: This extension has been deprecated, migrate to the definitionExtract extension

This expression identifies the resource(s) that correspond either to an overall questionnaire, a group within the questionnaire or, occasionally, a single question. The results of executing the specified expression are used to indicate the resources used to identify the data to replace when performing an extraction and also indicate the relevant resource type.

If an expression results in multiple repetitions for a single for the root Questionnaire or for an item where 'repeat' is false, it is an error and no extraction can occur. When performing an extraction and the expression is executed, if a record is found, the data in the QuestionnaireResponse will be used to update that record. If the expression returns no results, the data in the QuestionnaireResponse will be used to create a new record.

Expression.name does not necessarily need to be present for definition-based extraction, as that relies on item.definition rather than other expressions. However, including it is generally a good idea.

Selects a new context in the QuestionnaireResponse to be used by subsequent child templateExtractContexts or templateExtractValue expressions.

Selects a value to replace a value in the extracted resource template.
If the value returns multiple, and the resource property can have multiple values, the values will be added to the resource property.
If the value returns multiple, and the resource property can only have one value, the first value SHALL be used and a warning will be generated.

If there is no result, then the property with the template extension will be removed. With jason, that means removing both the value and _value properties for primitives.

For collections, there may be more than 1 template value to replace in the template collection, so don't just clear the collection, remove the templated item.