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

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

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

Query Parameters (GET)

For GET requests, parameters are passed as query parameters:

url - The canonical URL of the value set to expand (required if not using instance-level operation)
valueSetVersion - The version of the value set (optional)
filter - Filter text to apply to the expansion (optional)
count - Maximum number of codes to return (optional, default: server-defined)
offset - Offset for paging (optional, default: 0)
includeDesignations - Whether to include designations (optional, default: false)
designation - Specific designations to include (optional, can be repeated)
includeDefinition - Whether to include code definitions (optional, default: false)
activeOnly - Whether to exclude inactive codes (optional, default: false)
excludeNested - Exclude nested codes (optional, default: false)
excludeNotForUI - Exclude codes not suitable for UI (optional, default: false)
excludePostCoordinated - Exclude post-coordinated codes (optional, default: false)
displayLanguage - The preferred display language (optional)
system-version - Version of specific code system (optional, format: system|version)

Example: GET /w/{tenant}/{project}/api/v1/fhir/r4/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/administrative-gender&count=10

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"
    },
    {
      "name": "count",
      "valueInteger": 10
    },
    {
      "name": "includeDesignations",
      "valueBoolean": true
    },
    {
      "name": "displayLanguage",
      "valueCode": "en"
    }
  ]
}

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"
      }
    ]
  }
}

Key response fields in the expansion:

identifier - A unique identifier for this expansion
timestamp - When the expansion was created
total - Total number of codes in the expansion
offset - Offset used for paging
contains - Array of codes included in the expansion
- system - The code system URI
- code - The code value
- display - The display text for the code
- abstract - Whether the code is abstract (optional)
- inactive - Whether the code is inactive (optional)
- designation - Additional designations (if requested)

Filtered Expansion

You can filter the expansion using the filter parameter:

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

Response will include only codes matching the filter:

{
  "resourceType": "ValueSet",
  "expansion": {
    "total": 1,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "male",
        "display": "Male"
      }
    ]
  }
}

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"
    }
  ]
}

Example using cURL

Basic GET Request

curl -X GET "http://api.haste.health/w/{tenant}/{project}/api/v1/fhir/r4/ValueSet/\$expand?url=http://hl7.org/fhir/ValueSet/administrative-gender" \
     -H "Content-Type: application/fhir+json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET Request with Filter and Count

curl -X GET "http://api.haste.health/w/{tenant}/{project}/api/v1/fhir/r4/ValueSet/\$expand?url=http://hl7.org/fhir/ValueSet/administrative-gender&filter=mal&count=10" \
     -H "Content-Type: application/fhir+json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST Request with Parameters

curl -X POST "http://api.haste.health/w/{tenant}/{project}/api/v1/fhir/r4/ValueSet/\$expand" \
     -H "Content-Type: application/fhir+json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
           "resourceType": "Parameters",
           "parameter": [
             {
               "name": "url",
               "valueUri": "http://hl7.org/fhir/ValueSet/administrative-gender"
             },
             {
               "name": "count",
               "valueInteger": 10
             },
             {
               "name": "includeDesignations",
               "valueBoolean": true
             }
           ]
         }'

Instance-Level Expansion

curl -X GET "http://api.haste.health/w/{tenant}/{project}/api/v1/fhir/r4/ValueSet/administrative-gender/\$expand?count=10" \
     -H "Content-Type: application/fhir+json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This command expands the administrative-gender ValueSet instance and returns up to 10 codes.

Paging Large Expansions

For large value sets, use the count and offset parameters to page through results:

# First page (codes 0-99)
curl -X GET "http://api.haste.health/w/{tenant}/{project}/api/v1/fhir/r4/ValueSet/\$expand?url=http://example.org/large-valueset&count=100&offset=0" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Second page (codes 100-199)
curl -X GET "http://api.haste.health/w/{tenant}/{project}/api/v1/fhir/r4/ValueSet/\$expand?url=http://example.org/large-valueset&count=100&offset=100" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Endpoint​

Query Parameters (GET)​

Request Body (POST)​

Response​

Filtered Expansion​

Error Handling​

Example using cURL​

Basic GET Request​

GET Request with Filter and Count​

POST Request with Parameters​

Instance-Level Expansion​

Paging Large Expansions​