1 of 23

Usage of parameterized ValueSets in Questionnaires

Sean Fong | CSIRO

Organized by

FHIR® SDC Conference

June 2025

2 of 23

Usage of parameterized ValueSets in Questionnaires

Sean Fong

CSIRO

FHIR® SDC Conference | June 2025

3 of 23

Speaker Intro

Software Engineer from the AEHRC (Australian e-Health Research Centre) @ CSIRO�
From the Health Data Semantics and Interoperability group

I mainly work on web technologies focused on SDC and SMART on FHIR

Software Engineer

CSIRO

Sean Fong

FHIR® SDC Conference | June 2025

4 of 23

FHIR® SDC Conference | June 2025

5 of 23

Background - Smart Forms and CSIRO renderer

An open-source web-based FHIR-powered forms application
Integrates with EHRs via SMART on FHIR for data exchange
Primary use case is for practitioners to conduct health assessments digitally in a seamless and secure manner

Aboriginal And Torres Strait Islander Health Check (MBS715)

FHIR® SDC Conference | June 2025

6 of 23

Interacts with the EHR
Provides save, preview, �re-population interactions
Decides which questionnaire to render

Questionnaire Renderer

Contains rendering logic
Allows interaction with the form
Takes a Questionnaire (and optionally a pre-filled QuestionnaireResponse) as input
Outputs a filled QuestionnaireResponse

Smart Forms App

FHIR® SDC Conference | June 2025

7 of 23

Parameterized ValueSets

A common use case in forms is to make one question’s options depend on the answer to another question. �
Example: Show states/territories relevant to the selected country

State options driven by the selected country

FHIR® SDC Conference | June 2025

8 of 23

It is surprisingly difficult to build this in a Questionnaire!
You would have to do something like this in a cqf-expression in AnswerValueSet:

"iif(item.where(linkId = 'country').answer.value = 'Australia', 'http://example.com/fhir/ValueSet/states-au', iif(item.where(linkId = 'country').answer.value = 'United States', 'http://example.com/fhir/ValueSet/states-us', iif(item.where(linkId = 'country').answer.value = 'Canada', 'http://example.com/fhir/ValueSet/states-ca’, 'http://example.com/fhir/ValueSet/states-all'))))"

Which roughly translates to this in code:

3 ValueSets minimum, 4 if you need a ValueSet for all states.

Not scalable - there are 193 countries in the world (recognised by the UN).

FHIR® SDC Conference | June 2025

9 of 23

Parameterized ValueSets

Solution: Dynamic ValueSet expansion based on a generic �“p-{value}” filter search parameter�
Original proposal: https://gist.github.com/lawley/2b3b407b9998a1b537bb25f6302c1e38�
Draft spec page: https://build.fhir.org/ig/FHIR/fhir-tools-ig/parameterized-valuesets.html

State options driven by the selected country

FHIR® SDC Conference | June 2025

10 of 23

Parameterized ValueSets

Demo example available on R4 Ontoserver sandbox
All states: ValueSet/$expand?url=http://example.com/limited-states/vs
Filtered states: ValueSet/$expand?url=http://example.com/limited-states/vs&p-country={code}
Available p–country codes: AU, CA, US

	CodeSystem URL	ValueSet URL
Countries	https://r4.ontoserver.csiro.au/fhir/CodeSystem?url=http://example.com/countries	https://r4.ontoserver.csiro.au/fhir/ValueSet/$expand?url=http://example.com/countries/vs
States/ Territories	https://r4.ontoserver.csiro.au/fhir/CodeSystem/world-states� �Canonical: http://example.com/limited-states	https://r4.ontoserver.csiro.au/fhir/ValueSet/$expand?url=http://example.com/limited-states/vs
US states example		https://r4.ontoserver.csiro.au/fhir/ValueSet/$expand?url=http://example.com/limited-states/vs& p-country=US

FHIR® SDC Conference | June 2025

11 of 23

Parameterized ValueSets

https://r4.ontoserver.csiro.au/fhir/ValueSet/$expand?url=http://example.com/limited-states/vs p-country=AU

Code	Display
ACT	Australian Capital Territory
NSW	New South Wales
NT-AU	Northern Territory
QLD	Queensland
SA	South Australia
TAS	Tasmania
VIC	Victoria
WA-AU	Western Australia

Expansion from p-country=AU

FHIR® SDC Conference | June 2025

12 of 23

Parameterized ValueSets

How does $expand performs filtering based on p-value?�
This information is stored in CodeSystem.concept.property�
A concept can have multiple p-value filters!

FHIR® SDC Conference | June 2025

13 of 23

Usage in Questionnaires

Apply p-value filter in _AnswerValueSet using a new extension called http://hl7.org/fhir/tools/StructureDefinition/binding-parameter to be used in $expand and $validate-code calls�
Designed to be generic, works on other $expand and $validate-code parameters too:�e.g. count, activeOnly, displayLanguage, etc

FHIR® SDC Conference | June 2025

14 of 23

Usage in Questionnaires

Base expand call:�https://r4.ontoserver.csiro.au/fhir/ValueSet/$expand�
URL param: url=http://example.com/limited-states/vs

P-country param:�p-country=“%resource.item .where(linkId = 'countryCode’)�.answer.value.code”

FHIR® SDC Conference | June 2025

15 of 23

Demo

FHIR® SDC Conference | June 2025

16 of 23

Usage in Questionnaires - Demo

Demo Questionnaire:�https://smartforms.csiro.au/api/fhir/Questionnaire/ParameterisedValueSetMultiple�
Try it out in alpha.smartforms.io/playground

FHIR® SDC Conference | June 2025

17 of 23

ValueSet Search Demo

https://valueset-search-demo.netlify.app

FHIR® SDC Conference | June 2025

18 of 23

Set preferred terminology server URL with SDC extension: �http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-preferredTerminologyServer�
Set ValueSet URL to Questionnaire.answerValueSet�
Questionnaire contains a single item

drop-down: ValueSet expansion <150000
autocomplete: ValueSet expansion >150000�