Case Studies
FHIR Meetups
Contact us

Two-phase FHIR terminology

Niquola Ryzhikov
April 30, 2019
2 min read

Terminology in Health IT is a very important and complicated aspect. A lot of interoperability depends on how accurately do you encode your data.

FHIR Terminology Service specification does a great job to provide developers with simple and straight-forward API for terminology service.

Terminology management is a complicated domain — you have to keep up-to-date external code systems, understand their internal structure, provide authoring, versioning and publishing tools.

We can imagine an architecture with separated FHIR server & Terminology service. But “good” FHIR server has a quite strong dependency on Terminology — for validation, lookups and subsumption queries. Implementing full terminology service specification in FHIR server is a big deal. Using external terminology service make your FHIR server non-autonomous. So we have a trade-off :(

Authoring vs Usage

If you look closer into FHIR terminology you might notice that terminology can be decomposed into two parts — authoring/manage and usage. For authoring cases, you need up-to-date CodeSystems, ValueSets design tools with expansion engine, versions management etc. For usage, you mostly will work with immutable ValueSets and have to provide efficient filtering and lookup for validation.

To reduce coupling between Terminology and FHIR server, we can separate responsibilities in the following way:

  • Design ValueSets on Terminology Service and publish in expanded form by some kind of bulk export API/format
  • Load and use ValueSets in an optimized form into FHIR servers

Here are the technical details of how we can do this.

Concept Resource

In Aidbox we split CodeSystem into header info and set of Concept (Non-FHIR-yet :) resources, which have a similar structure as CodeSystem.conceptelement and Coding datatype. This allows us to translate part of Terminology Service API into unified FHIR crud/search API over Concept Resources.

We convert popular terminologies into a set of Concept resources, which can be distributed as ndjson files for efficient bulk export/import. Here is an example for LOINC:

- code: 10000-8
  display: R wave duration in lead AVR
 - R wave dur L-AVR
 - Cardiac
 - "Durat"
 - "ECG"
          relatednames2: Cardiac; Durat; ECG; EKG.MEASUREMENTS; ...
          method_typ: EKG
          classtype: '2'
          system: Heart
          time_aspct: Pt
          common_order_rank: '0'
          property: Time
          order_obs: Observation
          unitsrequired: Y

Expansion denormalization

If we add to Concept Resource multiple links to Value Sets we can denormalize all sophisticated Value Set expansions like this:

code: 10000-8
display: R wave duration in lead AVR
reference: ValueSet/LL1162-8
reference: ValueSet/another-vs

Set of Concepts with denormalized ValueSets can be dumped into ndjson with kinda bulk export API and uploaded into FHIR server.

FHIR server runtime

Concept resource with links to ValueSets can be used in FHIR server to implement basic usage operations — $expand with filter, $validate-code and $lookup — by simple search API over Concept:

GET /ValueSet/v1/$expand?_filter=x
=> GET /Concept?vs=v1&display=???/ValueSet/v1/$validate-code?system=???&code=???
=> /Concept?vs=v1&system=???&code=???


To simplify usage of terminology and decouple FHIR servers from terminology, we can introduce new Concept resource type, do all ValueSet authoring on terminology service and bulk export/import denormalized (expanded) Concepts into FHIR servers with much more simple implementation of basic operations.

Your feedback is welcome!

Aidbox FHIR Platform Free Trial

How did you like the article?

Never miss a thing
Subscribe for more content!

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
By clicking “Subscribe” you agree to Health Samurai Privacy Policy and consent to Health Samurai using your contact data for newsletter purposes

Two-phase FHIR terminology

3415 S Sepulveda Blvd Ste 1000 Los Angeles, CA 90034
+1 (818) 731-1279