Parameterised ValueSet

Overview

Parameterised ValueSet is a FHIR feature that allows you to dynamically filter ValueSet answer options based on parameters derived from other fields in the questionnaire. This is particularly useful for creating dependent dropdowns, such as filtering states based on a selected country.

The feature is specified in the FHIR Tools IG: Parameterized ValueSets .

Use Case Example

A common use case is a Country/State relationship:

• User selects a country from a dropdown
• The state/province dropdown is automatically filtered to show only states belonging to the selected country
• This is achieved by passing the country code as a parameter to the ValueSet expansion

How to Configure in Aidbox Forms Builder

Prerequisites

1. 1.
   Configure an external terminology server (e.g., Ontoserver) in your Aidbox instance
2. 2.
   Have a parameterized ValueSet available on the terminology server
3. 3.
   Ensure your questionnaire has the source field (e.g., country) that will provide the parameter value

Step-by-Step Configuration

1. Add the Source Field

First, add the field that will provide the parameter value. For example, a country selection:

{
  "type": "choice",
  "text": "Country",
  "linkId": "countryCode",
  "answerValueSet": "http://example.com/countries/vs"
}

2. Add the Dependent Choice Field

Create a new Choice item in the form builder (e.g., "State"):

1. 1.
   Click "Add Item" and select "Choice"
2. 2.
   Enter the item text (e.g., "State")
3. 3.
   In the settings panel, configure the terminology server:

   • Select or enter your terminology server URL (e.g., https://r4.ontoserver.csiro.au/fhir)
   • Select or enter the ValueSet URL for the parameterized ValueSet

3. Enable Expansion Parameters

1. 1.
   Check the "Expansion Parameters" checkbox in the settings panel
2. 2.
   Click "Add Parameter" to add a new expansion parameter

4. Configure the Parameter

For each parameter:

1. 1.
   Name: Enter the parameter name as defined in the ValueSet (e.g., p-country)
2. 2.
   Expression: Enter a FHIRPath expression to extract the value from the questionnaire response

Example FHIRPath expression to get the country code:

%resource.item.where(linkId = 'countryCode').answer.value.code

This expression:

• Uses %resource to reference the current QuestionnaireResponse
• Finds the item with linkId = 'countryCode'
• Extracts the code from the answer's value

How It Works at Runtime

When requesting answer options from the terminology server:

1. 1.
   The FHIRPath expression is evaluated against the current QuestionnaireResponse
2. 2.
   If the expression evaluates to AU (for Australia), the parameter becomes p-country=AU
3. 3.
   This parameter is added to the ValueSet $expand request
4. 4.
   The final request looks like: https://r4.ontoserver.csiro.au/fhir/ValueSet/$expand?url=http://example.com/limited-states/vs&p-country=AU
5. 5.
   The terminology server uses this parameter to filter the ValueSet expansion and return only relevant states

Full Example Questionnaire

{
  "item": [
    {
      "text": "Country",
      "type": "choice",
      "linkId": "countryCode",
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-preferredTerminologyServer",
          "valueUrl": "https://r4.ontoserver.csiro.au/fhir"
        }
      ],
      "answerValueSet": "http://example.com/countries/vs"
    },
    {
      "text": "State GET request url: https://r4.ontoserver.csiro.au/fhir/ValueSet/$expand?url=https://example.com/limited-states&includeDefinition=true",
      "type": "display",
      "_text": {
        "extension": [
          {
            "url": "http://hl7.org/fhir/StructureDefinition/cqf-expression",
            "valueExpression": {
              "language": "text/fhirpath",
              "expression": "'State GET request url: https://r4.ontoserver.csiro.au/fhir/ValueSet/$expand?url=https://example.com/limited-states&p-country=' + %resource.item.where(linkId = 'countryCode').answer.value.code + '&includeDefinition=true'"
            }
          }
        ]
      },
      "linkId": "requestDisplay"
    },
    {
      "text": "State",
      "type": "choice",
      "linkId": "stateCodeDropdown",
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-preferredTerminologyServer",
          "valueUrl": "https://r4.ontoserver.csiro.au/fhir"
        }
      ],
      "answerValueSet": "http://example.com/limited-states/vs",
      "_answerValueSet": {
        "extension": [
          {
            "url": "http://hl7.org/fhir/tools/StructureDefinition/binding-parameter",
            "extension": [
              {
                "url": "name",
                "valueString": "p-country"
              },
              {
                "url": "expression",
                "valueExpression": {
                  "language": "text/fhirpath",
                  "expression": "%resource.item.where(linkId = 'countryCode').answer.value.code"
                }
              }
            ]
          },
          {
            "url": "http://hl7.org/fhir/tools/StructureDefinition/binding-parameter",
            "extension": [
              {
                "url": "name",
                "valueString": "includeDefinition"
              },
              {
                "url": "expression",
                "valueExpression": {
                  "language": "text/fhirpath",
                  "expression": "true"
                }
              }
            ]
          }
        ]
      }
    }
  ],
  "resourceType": "Questionnaire",
  "title": "Parameterised ValueSet Example",
  "status": "draft",
  "url": "https://forms.aidbox.io/parameterised-valueset",
  "version": "0.1.0"
}