Expand Value Set

The FHIR $expand operation expands a value set to return the list of codes that are included in the value set at a specific point in time. This operation can be invoked on ValueSet resources.

Endpoint

POST /w/{tenant}/{project}/api/v1/fhir/r4/ValueSet/$expand

Where {id} is the logical ID of a specific ValueSet resource (optional for type-level operations).

Request Body (POST)

For POST requests, the request body should contain a Parameters resource with the input parameters:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "url",
      "valueUri": "http://hl7.org/fhir/ValueSet/administrative-gender|4.0.1"
    }
  ]
}

Alternatively, you can pass the entire ValueSet to expand:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "valueSet",
      "resource": {
        "resourceType": "ValueSet",
        "compose": {
          "include": [
            {
              "system": "http://hl7.org/fhir/administrative-gender"
            }
          ]
        }
      }
    }
  ]
}

Response

If the expansion is successful, the server will respond with a 200 OK status code and a ValueSet resource containing the expanded codes:

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "ValueSet",
  "url": "http://hl7.org/fhir/ValueSet/administrative-gender",
  "version": "4.0.1",
  "name": "AdministrativeGender",
  "status": "active",
  "expansion": {
    "identifier": "urn:uuid:12345678-1234-1234-1234-123456789012",
    "timestamp": "2025-11-26T10:30:00Z",
    "total": 4,
    "offset": 0,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "male",
        "display": "Male"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "female",
        "display": "Female"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "other",
        "display": "Other"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "unknown",
        "display": "Unknown"
      }
    ]
  }
}

Error Handling

If there are any issues with the request (e.g., missing required parameters, invalid value set), the server will respond with an appropriate error status code and include an OperationOutcome resource in the response body.

HTTP/1.1 400 Bad Request
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "diagnostics": "ValueSet 'http://example.org/unknown-valueset' not found"
    }
  ]
}