Using the NHS Terminology Server in a product: environments, operations, and design choices

/
/
13 min read
Using the NHS Terminology Server in a product: environments, operations, and design choices
NHS England Terminology Server: What It Provides and How to Use It | Digitals for Health

Most integration failures in health data are not transport failures. They are meaning failures. Two systems exchange a message without error, and one of them records a diagnosis, a medicine, or an observation in a way the other cannot interpret. The NHS England Terminology Server exists to reduce that risk, by giving products one assured source for the codes, value sets, and mappings that clinical data depends on. This article covers what it provides, how to connect to it, and the design decisions that decide whether it makes a product safer or only more dependent.


What the Terminology Server is

The server is an NHS England service that makes terminologies and classifications available through a FHIR API. Its content includes international standards such as SNOMED CT and ICD-10, and national content such as NHS Data Model and Dictionary codes and dm+d. It publishes CodeSystems, ValueSets, and ConceptMaps, and it makes both current and previous versions available.

The API is RESTful and conforms to FHIR R4, version 4.0.1, with one exception worth knowing early. It does not support the capabilities interaction, so a client should not depend on a capability statement to discover what the server can do. Build against the documented operations instead.

Access to content follows its licence. Some content, such as dm+d, is freely available for read access. Other content, SNOMED CT among it, is subject to access controls appropriate to its licence. A team should confirm its licensing position for the terminologies it intends to use before the design is fixed, not after.


The environments, and which one to use

There are three environments, and they exist for different purposes.

The general use environment, known as production 1, is where most teams should start. It suits exploration, development, testing, and general analytical use. The direct care clinical use environment, known as production 2, is dedicated to clinical use and has its own access route, so plan for it early if the product will support direct care. The authoring environment is for creating and maintaining content, and most product teams will never need it.

A common mistake is to treat production 1 as a safe place to run live clinical logic because it is the easiest to reach. Decide deliberately which environment each part of the product depends on, and record the reasoning in the safety case.


Getting access

An individual can browse the content through end-user tools. A software application, or a system that syndicates content to its own server, needs a system-to-system account. Request it early, because it is a dependency for development, and confirm how credentials will be stored, rotated, and separated between environments. NHS England also publishes a library of example queries in a GitHub repository, which is the fastest way to see what a working request looks like.


What a product can do with it

The server supports the standard FHIR terminology operations, so the useful capabilities map to familiar calls.

Look up a code to retrieve its display text, properties, and relationships. Validate that a code belongs to a code system or a value set, which is how a product enforces that a field holds only permitted values. Expand a value set, which powers search and autocomplete in a clinical entry screen. Translate a code from one system to another using a ConceptMap, which is how local codes are aligned with national ones. And test subsumption, asking whether one concept is a kind of another, which is what lets a query for a general condition find its specific forms.

Analytics and decision support benefit most from the last of these. A rule that fires on a class of conditions, rather than a hand-maintained list of codes, stays correct as the terminology changes.


Querying live or syndicating

There are two ways to consume the content, and the choice shapes the architecture.

Querying the server in real time is the simplest. The product calls the API when it needs a lookup or validation. It always sees current content, and there is nothing to maintain. The cost is a runtime dependency. If the server is slow or unreachable, a clinical workflow that depends on it is affected, and request volumes are monitored as part of the service, so check the limits that apply to your account.

Syndication means receiving a feed of terminology content through an API and holding it in a terminology server of your own, so runtime queries go to a server you control. That removes the external runtime dependency, and it gives you control over local content and mappings. The cost is that you now own the update process, the hosting, and the proof that your copy matches the national one. A common pattern is to syndicate for runtime clinical use and query the national server for development and analytics.


Design choices that decide whether it helps

  • Store the whole code, not the label. Persist the code, the code system, and the version it came from, alongside the display text. Display text changes and is ambiguous. A stored label with no code cannot be validated, mapped, or queried later.
  • Pin and record versions. Terminologies change, and the server provides previous versions so that behaviour can be reproduced. A product should know which version it validated against, and should treat a version change as a release event with testing, not a silent update.
  • Fail safely. Decide what happens when the server cannot be reached. Never fall back to unvalidated free text in a field that is meant to be coded without making that visible, and without a clear rule for how it is resolved later.
  • Control local mappings. Mapping local codes to national ones is where terminology work does harm if it is careless. Keep each mapping reviewed, versioned, and owned by someone clinically accountable, and record what is not mapped as well as what is.
  • Bind value sets in code. Which codes a field accepts is a design decision that affects clinical safety. Define it in version-controlled configuration with review, not in a settings screen that anyone can change.
  • Test the edges. Retired codes, inactive concepts, codes that exist in a newer version only, and expansions that return very large result sets all occur in live data.

The safety angle

Terminology errors become clinical errors. A mis-mapped medicine code or a stale value set can put the wrong item in front of a clinician. Treat the terminology dependency as a hazard in the DCB0129 hazard log, with named mitigations, and revisit it whenever a version, mapping, or environment changes.


Where this connects to build work

A terminology integration is a validation and normalisation problem, in the same family as any system that has to decide whether incoming data means what it appears to mean. The closest work we have delivered is a validation and matching layer for a UK healthcare services provider integrating around a legacy ERP on Microsoft Azure. Services normalised and validated incoming data, applied configurable matching rules, and produced reconciliation outcomes with clear reason codes, with audit records behind each decision. The domain was patient demographics rather than clinical coding, and the discipline carries across.


If you are building a product that depends on coded clinical data, and you want the terminology integration, the mappings, and the safety evidence built together, that is work we take on end to end.

Get in touch
Share this article:

Ready to Transform Your Healthcare Data Integration?

Our team of healthcare technology experts can help you implement FHIR integration that improves patient outcomes and operational efficiency.

Related Insights

/
/
/
/