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.