Skip to main content

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.

TypeProject feature
Value in featuresvalidate-terminology
Change withPATCH /v1/projects/me/features (replaces the whole list)
Who can change itProject admin. Any practitioner can read the list.
On for new projectsNo
Applies toCreates and updates made with the project's own tokens
When offCoded values are not checked against terminology bindings

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:

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 pathExampleMeaning
resourceTypeOperationOutcomeFHIR error resource returned for the rejected write.
issue[0].severityerrorIndicates the issue prevents the resource from being written.
issue[0].codevalueIdentifies a value-level validation failure.
issue[0].details.textValue "not-a-status" did not satisfy terminology binding <ValueSet URL>Explains why the code failed the required binding.
issue[0].expression[]Observation.statusIdentifies 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​

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

OperationReference
Validate a code against a ValueSet$validate-code
Validate a code against a CodeSystem$validate-code
Expand a ValueSet$expand
Validate a whole resource$validate

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

Turn it on​

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​

  • 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 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 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.