ValueSet
The FHIR Specification defines two resource types that are used as a part of defining and using codes.
- The CodeSystem resource defines a collection of codes.
- The ValueSet resource creates a collection of codes drawn from one or more CodeSystems.
ValueSets are defined by a collection of rules, it means the composition. These rules can be simple rules (e.g. include codes P, Q, and R) or much more complex rules (ex: include any codes that are a child of code P, etc).
Pre-Calculation for ValueSet Expansion
When a ValueSet is uploaded into HDR FHIR Repository, a scheduler job will be triggered in the background to calculate the expansion of the valueset and store it in a dedicated set of database tables. When you perform a ValueSet expansion, an extension will be added to the ValueSet.meta element. This extension shows the status of the pre-calculation.
Pre-Calculation Status
To test whether a ValueSet has been pre-calculated, simply request the expansion using the $expand operation. For example, the following request can be used to request the expansion of the my_custom_value_set ValueSet:
GET ValueSet/$expand?url= http://example.com/my_custom_value_set
If this ValueSet has not been precalculated, the system will send a response similar to the following:
{
"resourceType": "ValueSet",
"id": "200007",
"meta": {
"extension": [ {
"url": "http://hapifhir.io/fhir/StructureDefinition/valueset-expansion-message",
"valueString": "ValueSet \"ValueSet.url[http://example.com/t_custom_value_set]\" has not yet been pre-expanded. Performing in-memory expansion without parameters. Current status: NOT_EXPANDED | The ValueSet is waiting to be picked up and pre-expanded by a scheduled task."
} ],
"versionId": "1"
},
"url": "http://example.com/my_custom_value_set",
"status": "active",
[ ... Remaining Fields Not Shown ... ]
}
After the pre-calculation has completed, you will see a response similar to the following:
{
"resourceType": "ValueSet",
"id": "200007",
"meta": {
"extension": [ {
"url": "http://hapifhir.io/fhir/StructureDefinition/valueset-expansion-message",
"valueString": "ValueSet was expanded using an expansion that was pre-calculated at 2023-08-16T20:14:35.055+05:30 (00:24:06 ago)"
} ],
"versionId": "1"
},
"url": "http://example.com/t_custom_value_set",
"status": "active",
[ ... Remaining Fields Not Shown ... ]
}
Invalidating Pre-Calculated Expansion
It is also possible to manually request that the existing pre-calculated valueset expansion be invalidated and a new one can be calculated. This is useful in cases where the underlying CodeSystem has been changed.
To invalidate an existing Pre-Calculated valueset expansion, use the $invalidate-expansion operation by using a POST against the ValueSet resource ID such as the following:
POST ValueSet/200007/$invalidate-expansion
The response will be similar to the following:
{
"resourceType": "Parameters",
"parameter": [ {
"name": "message",
"valueString": "ValueSet with URL \"http://example.com/my_custom_value_set\" precaluclated expansion with 4 concept(s) has been invalidated"
} ]
}
- Expanding Hierarchical CodeSystems and ValueSets
Many CodeSystem resources define concepts in a hierarchy, ex: parent code and child codes. - Requesting A ValueSet Expansion
ValueSet expansion can be invoked using the HTTP GET on the following URL: - Requesting a ValueSet Hierarchical Expansion
If you would like to request parent-child relationships to be reflected in the response, you can add the includeHierarchy parameter in your request.
Parent topic: Terminology