Skip to main content

ValueSet $expand

The $expand operation returns all codes contained in a ValueSet, making it ideal for populating dropdown menus, typeahead search fields, and code pickers in clinical applications. Instead of storing and managing large code lists client-side, you can dynamically fetch the allowed values for any coded field.

This operation supports filtering and pagination, enabling responsive user interfaces that can search through thousands of codes (like SNOMED CT or LOINC) while only loading relevant results as the user types.

Use Cases​

  • Dropdown Population: Fetch all valid options for coded fields like gender, marital status, or allergy types
  • Typeahead Search: Power autocomplete fields that search through large code systems as users type
  • Form Builders: Dynamically load code options when rendering questionnaires or data entry forms
  • Code Picker Components: Build searchable code selection interfaces with pagination support
  • Validation UI: Show users the valid options when they've entered an invalid code

Invoke the $expand operation​

[base]/ValueSet/$expand

Parameters​

NameTypeDescriptionRequired
urlstringThe URL of the value set to expandYes
filterstringA filter to apply to the value setNo
offsetnumberThe offset to start the expansionNo
countnumberThe number of results to returnNo
displayLanguagestringThe language code to search with filterNo
excludeNotForUIbooleanExclude abstract concepts that shouldn't be displayed in user interfacesNo
includeDesignationsbooleanInclude translations and synonyms (designations) in the expansion resultsNo
valueSetValueSetAn inline ValueSet resource to expand (alternative to providing a URL)No

Output​

The result of the expansion as a ValueSet resource. The results of the expansion operation are in the ValueSet.expansion field.

Examples​

Query all values for a ValueSet:

curl 'https://api.medplum.com/fhir/R4/ValueSet/$expand?url=http%3A%2F%2Fhl7.org%2Ffhir%2FValueSet%2Fadministrative-gender' \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer MY_ACCESS_TOKEN"
{
  "resourceType": "ValueSet",
  "url": "http://hl7.org/fhir/ValueSet/administrative-gender",
  "expansion": {
    "offset": 0,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "female",
        "display": "Female"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "male",
        "display": "Male"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "other",
        "display": "Other"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "unknown",
        "display": "Unknown"
      }
    ]
  }
}

Filter by search string:

curl 'https://api.medplum.com/fhir/R4/ValueSet/$expand?url=http%3A%2F%2Fhl7.org%2Ffhir%2FValueSet%2Fadministrative-gender&filter=f' \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer MY_ACCESS_TOKEN"
{
  "resourceType": "ValueSet",
  "url": "http://hl7.org/fhir/ValueSet/administrative-gender",
  "expansion": {
    "offset": 0,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "female",
        "display": "Female"
      }
    ]
  }
}

The MedplumClient TypeScript class provides a valueSetExpand convenience method:

const url = 'http://hl7.org/fhir/ValueSet/administrative-gender';
const input = 'f';
const result = await medplum.valueSetExpand({ url, filter: input });