ValueSet

A ValueSet describes a selectable set of codes, usually by referencing one or more CodeSystems. It can list codes explicitly or define rules that include concepts by hierarchy, properties, filters, or other terminology criteria.

In Termbox, ValueSets are used to expand a definition into concrete codes and to validate whether a code belongs to that set. This is the resource to use when an application needs a controlled list of allowed answers or values.

See the official FHIR specification for the ValueSet resource: https://www.hl7.org/fhir/valueset.html.

Create

The example below creates a ValueSet that selects three concepts from an existing CodeSystem.

POST /ValueSet
Content-Type: application/json

{
  "resourceType": "ValueSet",
  "url": "http://example.org/ValueSet/vs1",
  "version": "0.1.0",
  "name": "ExampleValueSet",
  "title": "Example Value Set",
  "status": "active",
  "experimental": false,
  "date": "2026-05-15",
  "compose": {
    "include": [
      {
        "system": "http://example.org/CodeSystem/cs1",
        "concept": [
          { "code": "code1" },
          { "code": "code2" },
          { "code": "code3" }
        ]
      }
    ]
  }
}

The response includes a Location header pointing to the newly created resource.

HTTP/1.1 201 Created
Location: /ValueSet/a3f8e621-7c94-4b52-9d01-e2b345678901
Content-Type: application/json; charset=utf-8

{
  "resourceType": "ValueSet",
  "id": "a3f8e621-7c94-4b52-9d01-e2b345678901",
  "url": "http://example.org/ValueSet/vs1",
  "version": "0.1.0",
  "name": "ExampleValueSet",
  "title": "Example Value Set",
  "status": "active",
  "experimental": false,
  "date": "2026-04-09",
  "compose": {
    "include": [
      {
        "system": "http://example.org/CodeSystem/cs1",
        "concept": [
          { "code": "code1" },
          { "code": "code2" },
          { "code": "code3" }
        ]
      }
    ]
  }
}

Read

Reading a ValueSet returns the resource with the concepts enumerated in its compose.include and compose.exclude rules.

GET /ValueSet/a3f8e621-7c94-4b52-9d01-e2b345678901

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "resourceType": "ValueSet",
  "id": "a3f8e621-7c94-4b52-9d01-e2b345678901",
  "url": "http://example.org/ValueSet/vs1",
  "version": "0.1.0",
  "name": "ExampleValueSet",
  "status": "active",
  "compose": {
    "include": [
      {
        "system": "http://example.org/CodeSystem/cs1",
        "concept": [
          { "code": "code1" },
          { "code": "code2" },
          { "code": "code3" }
        ]
      }
    ]
  }
}

To keep responses bounded, a read returns at most FHIR_READ_ITEMS_LIMIT enumerated concepts across all include and exclude rules (default 1000, see Configuration). When the resource has more, the response is truncated and tagged with SUBSETTED in meta.tag. Rules whose concepts were cut off keep the http://health-samurai.io/extensions/excised-data extension, so a client can tell which parts of the compose are incomplete.

Reading a ValueSet does not expand it. Use ValueSet/$expand to get the concrete set of codes selected by the ValueSet.

If the ValueSet does not exist, the server responds with 404 Not Found and an OperationOutcome with the not-found issue code.

Delete

Deleting a ValueSet removes the resource from the server.

DELETE /ValueSet/a3f8e621-7c94-4b52-9d01-e2b345678901

HTTP/1.1 204 No Content

Supported Operations

Termbox supports the following FHIR operations for ValueSet resources:

Operation	Description
`ValueSet/$expand`	Expand a ValueSet into the concrete set of concepts selected by its compose rules.
`ValueSet/$validate-code`	Check whether a code, Coding, or CodeableConcept is a member of a ValueSet.