# validate-terminology

Canonical page: https://docs.ovok.com/settings-and-features/features/validate-terminology

Makes the platform check coded values against required terminology bindings when a resource is created or updated. A code that is not in the required ValueSet makes the write fail.

| | |
| --- | --- |
| Type | Project feature |
| Value in `features` | `validate-terminology` |
| Change with | `PATCH /v1/projects/me/features` (replaces the whole list) |
| Who can change it | Project admin. Any practitioner can read the list. |
| On for new projects | **No** |
| Applies to | Creates and updates made with the project's own tokens |
| When off | Coded values are not checked against terminology bindings |

## What it does [#what-it-does]

With the feature on, creating or updating a resource whose coded element has a **required** binding is checked against that binding's ValueSet. A value outside it is rejected with `400` and an `OperationOutcome` issue of code `value`, whose text reads `Value "<code>" did not satisfy terminology binding <ValueSet URL>` and whose `expression` points at the offending element.

For example, `Observation.status` has a required binding to the observation-status ValueSet:

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/Observation' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data '{"resourceType":"Observation","status":"not-a-status","code":{"text":"Heart rate"}}'
```

With the feature on, this answers `400` and nothing is written:

| Response path | Example | Meaning |
| --- | --- | --- |
| `resourceType` | `OperationOutcome` | FHIR error resource returned for the rejected write. |
| `issue[0].severity` | `error` | Indicates the issue prevents the resource from being written. |
| `issue[0].code` | `value` | Identifies a value-level validation failure. |
| `issue[0].details.text` | `Value "not-a-status" did not satisfy terminology binding <ValueSet URL>` | Explains why the code failed the required binding. |
| `issue[0].expression[]` | `Observation.status` | Identifies the element that failed validation. |

The ValueSet URL carries a version suffix (`|4.0.1`). The check runs as part of strict validation, which is on for projects Ovok creates.

## What it does not do [#what-it-does-not-do]

It does not change the terminology operations. These work whether the feature is on or off:

| Operation | Reference |
| --- | --- |
| Validate a code against a ValueSet | [`$validate-code`](/primitives/validate-valueset-code) |
| Validate a code against a CodeSystem | [`$validate-code`](/primitives/validate-codesystem-code) |
| Expand a ValueSet | [`$expand`](/primitives/expand-valueset) |
| Validate a whole resource | [`$validate`](/primitives/validate-resource) |

The feature also does not re-check resources that are already stored. It applies when a resource is next written.

## Turn it on [#turn-it-on]

```bash
curl --request PATCH \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/features' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"features":["bots","cron","email","transaction-bundles","websocket-subscriptions","validate-terminology"]}'
```

Start from the list `GET /v1/projects/me/features` returns, and add `validate-terminology` to it.

## Gotchas [#gotchas]

- **Turning it on can make previously accepted writes fail.** An app that writes a code the binding does not allow starts receiving `400`. Try it in a sandbox project first, and use [`$validate`](/primitives/validate-resource) to test your resources before you write them.
- **Only required bindings reject.** Extensible, preferred and example bindings are not enforced.
- **In a transaction, one bad code rejects the lot.** With [transaction-bundles](/settings-and-features/features/transaction-bundles) on, a single entry that fails terminology validation rolls back the whole Bundle.
- **"Validate terminology" does not mean the `$validate-code` operations.** Those are always available.
- **Projects do not inherit it.** Turn it on in each project that needs it.

## Related [#related]

- [Validate a resource](/primitives/validate-resource)
- [Validate a code against a ValueSet](/primitives/validate-valueset-code)
- [ValueSet](/api/fhir/r4/value-set)
- [CodeSystem](/api/fhir/r4/code-system)
