# Expand a ValueSet

Canonical page: https://docs.ovok.com/primitives/expand-valueset

`$expand` evaluates a ValueSet definition and returns an expanded `ValueSet` containing its included codes. Use it to build code pickers or inspect the concepts covered by a binding. The expansion is generated from the terminology content and versions available to the server, so treat it as a current result rather than a permanent copy.

| Method | Path |
| --- | --- |
| `GET` or `POST` | `/fhir/R4/ValueSet/$expand` |

## GET request [#get-request]

Use query parameters for a ValueSet already known to the server. At the type-level endpoint, provide a `url`, `context`, or `valueSet` input. This example expands a registered ValueSet by canonical URL, filters it for a matching term, and asks for the first 20 concepts.

```bash
curl --get 'https://api.sandbox.ovok.com/fhir/R4/ValueSet/$expand' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode 'url=https://example.org/fhir/ValueSet/vitals' \
  --data-urlencode 'filter=heart' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'count=20'
```

`filter` is a text filter interpreted by the terminology server. `offset` and `count` request a page when the server supports paging for a flat expansion.

## POST request [#post-request]

Use a FHIR `Parameters` body when supplying the ValueSet definition inline. The server may choose not to accept inline ValueSets; it must support the ValueSet or canonical URL otherwise.

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/ValueSet/$expand' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data @expand-valueset-parameters.json
```

Example `expand-valueset-parameters.json`:

```json
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "valueSet",
      "resource": {
        "resourceType": "ValueSet",
        "status": "active",
        "compose": {
          "include": [
            {
              "system": "http://loinc.org",
              "concept": [
                { "code": "8867-4", "display": "Heart rate" }
              ]
            }
          ]
        }
      }
    }
  ]
}
```

## Successful response [#successful-response]

The response is the expanded `ValueSet` itself, not a `Parameters` wrapper.

| Response path | Example | Meaning |
| --- | --- | --- |
| `resourceType` | `ValueSet` | Identifies the returned FHIR resource. |
| `status` | `active` | Status of the ValueSet. |
| `expansion.identifier` | `urn:uuid:<expansion-id>` | Identifier for this generated expansion. |
| `expansion.timestamp` | `<ISO-8601 timestamp>` | Time at which the expansion was produced. |
| `expansion.total` | `1` | Total number of matching concepts. |
| `expansion.offset` | `0` | Starting position when paging is used. |
| `expansion.contains[]` | `http://loinc.org` / `8867-4` / `Heart rate` | Expanded concepts, with their code system, code, display, and possibly designations or other properties. |

An oversized expansion may return an `OperationOutcome` instead. Use `offset` and `count` for supported flat expansions rather than requesting an unbounded result.

Reference: [HL7 FHIR R4 ValueSet `$expand`](https://hl7.org/fhir/R4/valueset-operation-expand.html).
