Terminology servers (TX servers) are FHIR services specialized in managing knowledge artifact resources related to terminology and vocabulary. A single TX server can provide terminology operation capabilities for many FHIR servers. TX servers generally don't manage clinical resources like patients, observations, medications, or diagnostic reports, but rather resources used to integrate knowledge into healthcare systems. TX services help solve issues such as:
85354-9 a valid LOINC code?" ($validate-code)$expand)$lookup)$translate)TX servers commonly manage content-heavy standard terminologies, also called external terminologies. These terminologies present massive storage and maintenance challenges:
TX servers also manage community terminologies included in Implementation Guides (IGs) such as US Core (which contains terminology tailored for United States healthcare practices) and organization-specific custom terminologies represented as local CodeSystems and ValueSets.
Organizations implementing FHIR need comprehensive coverage of external terminologies in combination with custom terminologies and community terminologies. They rarely use terminologies in isolation. Let's call this the mixed terminologies problem. A typical electronic health record deployment might require:
resourceType: ValueSet
compose:
include:
- system: http://loinc.org
filter:
- property: SCALE_TYP
op: "="
value: Qn
- system: http://example.org/fhir/CodeSystem/custom-vitals
concept:
- code: pain-scale-1-10
- code: mobility-assessment
- system: http://hl7.org/fhir/us/core/CodeSystem/us-core-category
concept:
- code: vital-signsThis single ValueSet combines:
The traditional approach to this mixed terminologies requirement is to manage all three kinds of terminologies in the same TX server.
Local-only means using the FHIR server for managing both clinical and terminology resources. This approach implies treating the knowledge artifacts related to terminologies similarly to clinical resources, sharing the same engine, the same storage and the same infrastructure.
External terminology servers are hosted TX services that give access to large standard terminologies without requiring local storage. Examples include community services like HL7's tx server and Ontoserver, as well as commercial SaaS offerings like Health Samurai's Termbox. These services excel at providing comprehensive coverage of massive terminologies like SNOMED CT and LOINC. However, relying entirely on external delegation creates several operational challenges, especially when an organization also needs to manage context-specific terminologies, like those from Implementation Guides or custom local code systems.
Both local-only and external-only approaches fall short for the mixed terminologies scenario, forcing trade-offs in functionality or performance. The core issue is that content-heavy terminologies like SNOMED CT, LOINC, and RxNorm have broad applicability, while community and custom terminologies are context-specific and should not affect unrelated terminology service clients.
Solving the infrastructure challenges of massive terminologies (storage, indexing, updates) requires entirely different approaches than managing small, rapidly-changing local vocabularies (agility, customization, governance). Traditional TX services cannot optimize for both scenarios simultaneously, leading to either over-engineered solutions for simple local terminology or inadequate infrastructure for large standard terminologies.
Hybrid terminology service solves this challenge through intelligent request analysis and partitioning. Rather than forcing a binary choice between local and external processing, the hybrid engine examines each request to determine which resources are available locally and which require external delegation, then reassembling the results.
To demonstrate the hybrid algorithm, consider a healthcare organization with:
http://hl7.org/fhir/test/CodeSystem/simplehttp://hl7.org/fhir/sid/icd-10Local CodeSystem Definition:
resourceType: CodeSystem
language: en
url: http://hl7.org/fhir/test/CodeSystem/simple
version: 0.1.0
hierarchyMeaning: is-a
content: complete
concept:
- code: code1
display: Display 1
Let's validate an ICD-10 code that requires external delegation.
Request:
POST /fhir/ValueSet/$validate-coderesourceType: Parameters
parameter:
- name: code
valueCode: S920
- name: system
valueUri: http://hl7.org/fhir/sid/icd-10
- name: valueSet
resource:
resourceType: ValueSet
url: http://example.org/fhir/ValueSet/vs1
compose:
include:
- system: http://hl7.org/fhir/test/CodeSystem/simple
- system: http://hl7.org/fhir/sid/icd-10Response:
resourceType: Parameters
parameter:
- name: result
valueBoolean: true
- name: code
valueCode: S920
- name: system
valueUri: http://hl7.org/fhir/sid/icd-10
- name: version
valueString: 2019-covid-expanded
- name: display
valueString: 'Fracture of foot, except ankle : closed'The system detects that http://hl7.org/fhir/sid/icd-10 isn't available locally and delegates the validation to the external terminology server.
The hybrid engine processes ValueSet/$validate-code request through the following phases:
The ValueSet is the entry point to the terminology execution context. The hybrid engine resolves the complete dependency graph locally, including all referenced CodeSystems and nested ValueSets.
It builds a dependency map from the ValueSet’s composition rules. The dependency resolution relies on FHIR's canonical resolution algorithm to pick the most recent compatible versions.
The hybrid engine analyzes the terminology execution context to detect resource requirements. This analysis examines:
content: "not-present" require external processingIf everything is local or everything is remote, it routes to that single target and returns the result.
When the analysis determines that portions of the dependency graph require external processing, the request is first executed locally. If the local validation succeeds, the result is returned to the client. If it fails, the hybrid engine strips local components and delegates the remaining request to the configured external terminology server.
The hybrid algorithm applies similarly to $expand operations with one key difference: the capability for merging results coming from different sources. Consider expanding a ValueSet that combines local and remote terminology systems.
Locally Available ValueSets
resourceType: ValueSet
url: http://example.org/vs-local1
compose:
include:
- system: http://hl7.org/fhir/administrative-gender
filter:
- property: concept
op: "="
value: female
---
resourceType: ValueSet
url: http://example.org/vs-remote1
compose:
include:
- system: http://loinc.org
filter:
- property: concept
op: in
value: 1751-7,2339-0
---
resourceType: ValueSet
url: http://example.org/vs-remote2
compose:
include:
- system: http://loinc.org
filter:
- property: concept
op: "="
value: 2339-0Request:
POST /fhir/ValueSet/$expandresourceType: Parameters
parameter:
- name: valueSet
resource:
resourceType: ValueSet
compose:
include:
- valueSet:
- http://example.org/vs-local1
- valueSet:
- http://example.org/vs-remote1
exclude:
- valueSet:
- http://example.org/vs-remote2Response:
resourceType: ValueSet
expansion:
total: 2
parameter:
- name: used-valueset
valueUri: http://example.org/vs-local1
- name: used-valueset
valueUri: http://example.org/vs-remote1
- name: used-valueset
valueUri: http://example.org/vs-remote2
- name: used-codesystem
valueUri: http://hl7.org/fhir/administrative-gender|4.0.1
- name: used-codesystem
valueUri: http://loinc.org|3.1.0
- name: used-codesystem
valueUri: http://loinc.org|2.76
- name: version
valueUri: http://loinc.org|2.76
contains:
- code: female
system: http://hl7.org/fhir/administrative-gender
display: Female
- system: http://loinc.org
code: 1751-7
display: Albumin [Mass/volume] in Serum or Plasma
The hybrid engine processes the administrative-gender concept locally while delegating LOINC filtering to the configured external TX server. While $validate-code operations require binary validation results, $expand operations must combine concept lists from both local and remote sources.
The hybrid algorithm for $expand operations includes two additional steps:
If local expansion can't fully satisfy the request, the hybrid engine strips local components from the original request and delegates the remaining parts to the configured external terminology server to resolve the remote expansion.
The hybrid engine then combines the local and remote expansions, deduplicates concepts, and produces the final expansion metadata with contributions from both sources.
Aidbox introduced The Hybrid TX engine in release 2507, with support (as of the publication of this article) for:
$lookup and $validate-code operations$validate-code and $expand operations$translate operationSee the capabilities registry for details.
Run Aidbox locally following the Run Aidbox locally guide. Notice the downloaded docker-compose.yaml file includes environment variables to enable hybrid mode:
services:
aidbox:
environment:
BOX_FHIR_TERMINOLOGY_ENGINE: hybrid
BOX_FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: https://tx.health-samurai.io/fhirFor more configuration details, see Aidbox terminology module setup.
Open Aidbox's REST Console and send:
POST /fhir/ValueSet
resourceType: ValueSet
status: active
url: http://example.org/vs-local1
compose:
include:
- system: http://hl7.org/fhir/administrative-gender
filter:
- property: concept
op: "="
value: female
POST /fhir/ValueSet
resourceType: ValueSet
status: active
url: http://example.org/vs-remote1
compose:
include:
- system: http://loinc.org
filter:
- property: concept
op: in
value: 1751-7,2339-0
POST /fhir/ValueSet
resourceType: ValueSet
status: active
url: http://example.org/vs-remote2
compose:
include:
- system: http://loinc.org
filter:
- property: concept
op: "="
value: 2339-0
Now expand a ValueSet composed of local and remote terminologies.
Request:
POST /fhir/ValueSet/$expand
resourceType: Parameters
parameter:
- name: valueSet
resource:
resourceType: ValueSet
compose:
include:
- valueSet:
- http://example.org/vs-local1
- valueSet:
- http://example.org/vs-remote1
exclude:
- valueSet:
- http://example.org/vs-remote2Response:
resourceType: ValueSet
expansion:
identifier: urn:uuid:f087ced0-b9b7-4277-a4d7-e97d23ff44fe
timestamp: '2025-09-05T14:27:07.118905554Z'
total: 2
parameter:
- {name: used-valueset, valueUri: 'http://example.org/vs-local1'}
- {name: used-valueset, valueUri: 'http://example.org/vs-remote1'}
- {name: used-valueset, valueUri: 'http://example.org/vs-remote2'}
- {name: used-codesystem, valueUri: 'http://hl7.org/fhir/administrative-gender|4.0.1'}
- {name: used-codesystem, valueUri: 'http://loinc.org|2.76'}
- {name: version, valueUri: 'http://loinc.org|2.76'}
contains:
- {code: female, system: 'http://hl7.org/fhir/administrative-gender', display: Female}
- {system: 'http://loinc.org', code: 1751-7, display: 'Albumin [Mass/volume] in Serum or Plasma'}See the Aidbox's terminology module documentation for more examples.
The hybrid terminology engine is a production-ready way to handle what traditional TX services struggle with: delivering broad coverage and local control at the same time.
Get in touch with us today!
