Skip to main content

ValueSet Operations

The terminology service provides operations to expand value sets into their constituent codes, validate codes against value set membership, and manage ValueSet resources.

$expand​

Expands a ValueSet into a flat list of codes. This resolves all includes, excludes, and filters to produce the final set of valid codes.

ValueSet.compose.include.filter supports is-a / descendent-of, =, and regex operators. Multiple filters on the same include are combined with AND (each narrows the same member set further), while multiple include entries are combined with OR.

GET Request​

curl 'http://localhost:9090/fhir/r4/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/observation-status'

With filtering:

curl 'http://localhost:9090/fhir/r4/ValueSet/snomed-diabetes-example/$expand?filter=type'

POST Request​

curl -X POST http://localhost:9090/fhir/r4/ValueSet/$expand \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "Parameters",
"parameter": [
{"name": "url", "valueUri": "http://example.org/fhir/ValueSet/snomed-diabetes-example"}
]
}'

Expand by ID​

curl 'http://localhost:9090/fhir/r4/ValueSet/snomed-diabetes-example/$expand'

Response​

{
"resourceType": "ValueSet",
"meta": {
"profile": [
"http://hl7.org/fhir/StructureDefinition/ValueSet"
]
},
"title": "SNOMED diabetes example",
"id": "snomed-diabetes-example",
"version": "1.0.0",
"url": "http://example.org/fhir/ValueSet/snomed-diabetes-example",
"compose": {
"include": [
{
"system": "http://snomed.info/sct",
"concept": [
{
"code": "73211009"
},
{
"code": "44054006"
}
]
}
]
},
"name": "SnomedDiabetesExample",
"status": "active",
"expansion": {
"contains": [
{
"code": "44054006",
"display": "Diabetes mellitus type II",
"system": "http://snomed.info/sct"
},
{
"code": "73211009",
"display": "Diabetes mellitus",
"system": "http://snomed.info/sct"
}
],
"total": 2,
"offset": 0,
"timestamp": "2026-10-05T11:21:47.964149200Z",
"identifier": "urn:uuid:f62f87d8-9304-4bb1-8768-6f90ef46b847",
"parameter": [
{
"name": "used-codesystem",
"valueUri": "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/20260401"
}
]
}
}

Parameters​

ParameterTypeDescription
urluriCanonical URL of the ValueSet
filterstringText filter on display names
offsetintegerPagination start index
countintegerMaximum codes to return (default 20, maximum 300 -- returns 413 if exceeded)
activeOnlybooleanWhen true, drops inactive concepts from the expansion and recomputes expansion.total

$validate-code​

Checks whether a specific code is a member of a value set. Accepts either a url referencing an already-persisted ValueSet, or an inline valueSet resource in the request body -- including one that was never separately uploaded.

GET Request​

curl 'http://localhost:9090/fhir/r4/ValueSet/snomed-diabetes-example/$validate-code?system=http://snomed.info/sct&code=73211009'

Validate by ID​

curl 'http://localhost:9090/fhir/r4/ValueSet/snomed-diabetes-example/$validate-code?code=44054006'

POST Request​

curl -X POST http://localhost:9090/fhir/r4/ValueSet/$validate-code \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "Parameters",
"parameter": [
{ "name": "valueSet", "resource": {
"resourceType": "ValueSet",
"url": "http://example.org/fhir/ValueSet/snomed-diabetes-example",
"status": "active"
}},
{ "name": "coding", "valueCoding": { "system": "http://snomed.info/sct", "code": "73211009" } }
]
}'

Response​

{
"resourceType": "Parameters",
"parameter": [
{
"name": "result",
"valueBoolean": true
},
{
"valueCode": "73211009",
"name": "code"
},
{
"name": "display",
"valueString": "Diabetes mellitus"
}
]
}

Search ValueSets​

Retrieve ValueSets matching search criteria.

curl 'http://localhost:9090/fhir/r4/ValueSet?url=http://example.org/fhir/ValueSet/snomed-diabetes-example'

Returns a FHIR Bundle of matching ValueSet resources.

Create a ValueSet​

Upload a new ValueSet resource.

curl -X POST http://localhost:9090/fhir/r4/ValueSet \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "ValueSet",
"id": "icd10-diabetes-example",
"url": "http://example.org/fhir/ValueSet/icd10-diabetes-example",
"version": "1.0.0",
"name": "Icd10DiabetesExample",
"title": "ICD-10-CM diabetes example",
"status": "active",
"compose": {
"include": [
{
"system": "http://hl7.org/fhir/sid/icd-10-cm",
"concept": [
{ "code": "E11.9" },
{ "code": "E10.9" },
{ "code": "E11.65" },
{ "code": "E11.21" },
{ "code": "E08.9" }
]
}
]
}
}'

Returns 201 Created on success.

Common Value Sets​

Frequently used value sets in FHIR R4:

ValueSetURLDescription
Observation Statushttp://hl7.org/fhir/ValueSet/observation-statusStatus of an observation
Condition Clinical Statushttp://hl7.org/fhir/ValueSet/condition-clinicalActive, recurrence, etc.
Encounter Statushttp://hl7.org/fhir/ValueSet/encounter-statusPlanned, in-progress, finished
Medication Request Statushttp://hl7.org/fhir/ValueSet/medicationrequest-statusActive, completed, cancelled
Administrative Genderhttp://hl7.org/fhir/ValueSet/administrative-genderMale, female, other, unknown