FHIR Terminology Ecosystem IG, published by HL7 FHIR Product Director. This guide is not an authorized publication; it is the continuous build for version 1.11.1-snapshot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-tx-ecosystem-ig/ and changes regularly. See the Directory of published versions
| Official URL: http://hl7.org/fhir/uv/tx-ecosystem/ImplementationGuide/hl7.fhir.uv.tx-ecosystem | Version: 1.11.1-snapshot | ||||
| IG Standards status: Informative | Maturity Level: 4 | Computable Name: FHIRTerminologyEcosystemIG | |||
| Other Identifiers: OID:2.16.840.1.113883.4.642.40.50 | |||||
This IG defines the HL7 terminology ecosystem framework: a set of terminology servers that serve different code systems on behalf of different code system authorities, and a coordination server that routes each terminology request to the server that can answer it.
HL7 defines one instance of an ecosystem, the public one which is what HL7's tools use for terminology - validators, the IG publisher, code generators, and profile and terminology authoring tools.
Other authorities and networks maybe define their own terminology ecosystems using the same framework.
This specification has two jobs. It sets out what a server has to do to be part of the ecosystem, with the test cases that check it; and, because the tools depend on getting the same answer from every server, it pins down how the terminology operations behave wherever the FHIR specification leaves room for interpretation - which messages are returned, how inactive codes, versions, languages and post-coordinated expressions are handled, and so on. The second job is now the larger one: the requirements and the test cases are, in effect, a detailed operational specification of the FHIR terminology services.
The test cases in this specification are maintained in association with the terminology authorities that publish the terminologies that are tested, and in many cases, serve to define the behaviour of the terminologies that are tested. In some cases, they are jointly maintained and official:
The LOINC and OMOP tests may become official; this is work-in-progress.
The current release of the test cases is 1.11.0 (6 November 2026). The
Version History lists what changed in each release. Test against a released
version: the default, current, is the ci-build, and changes whenever the tests do.
| Area | Status |
|---|---|
The core operations - $expand, $validate-code, $lookup, $translate, $subsumes - with versions and languages |
Stable. Releases add tests and correct expected responses, but the rules change rarely |
| SNOMED CT post-coordination | Settling. The scope servers have to support was agreed by the SNOMED Computable Languages Group in October 2026 (see the requirements), and the tests have been written to it and are being evaluated |
$closure, and features |
New in 1.10.0; still being evaluated |
| ICD-11 and ICF | Draft. The ICD-11 and ICF notes will move to terminology.hl7.org in time |
The tx.fhir.org mode |
Tests specific to tx.fhir.org. No other server is expected to pass them, though some do; some tests in this suite will be moved to other suites in time |
The test cases will be migrated to TestPlan and matchetypes at some stage. They are written for R5, and also run against R4 servers (see R4 and the Test Cases).
The test cases in the current build, by mode:
| Mode | Tests |
| general | 828 |
| tx.fhir.org | 208 |
| loinc | 126 |
| snomed | 373 |
| omop | 27 |
| mimetypes | 39 |
| icd-11 | 132 |
| icf | 83 |
| Total | 1802 in 47 suites |
A server becomes an Approved Server by passing the test cases for the modes it claims, against a released version, on a public test endpoint, and being approved by the FHIR Product Director. Problems with the test cases, or with the requirements, are firstly discussed on the Terminology Service Test Cases at chat.fhir.org, and then can be raised as issues or PRs on the IG's repository. Changes to the tests are worked through with the authors of the servers, and agreed with the FHIR Product Director.
This specification is maintained by Grahame Grieve, as FHIR Product Director, and Reuben Daniels, as Deputy FHIR Product Director. Contributions are made under the HL7 GOM, and the IG is built with the standard HL7 ci-build for IGs, which checks the generated QA. The license is in the repository. The content is used by, and built into, the base FHIR tools, which use the ecosystem for every version of FHIR after R4.
This IG contains no active content. If you think there is a security issue in the terminology ecosystem as it is documented here, report it privately using GitHub's security reporting on the IG's repository, or email the FHIR Product Director. A security issue with one of the servers in the ecosystem should be reported to that server's operators.