#30. Incorrect code system URIs

An incorrect system URI in a search query means the data may exist in FHIR, but you can’t find it. An incorrect system URI in a CodeableConcept in the FHIR server means the data effectively does not exist in FHIR.

There are three common mistakes made with system URIs.

1. A ValueSet URL is used in place of the code system URI

This is an easy mistake to make, especially when using HL7 ValueSets that are linked to from the FHIR resource documentation. Observation category is a good example. This element is bound to the ObservationCategoryCodes ValueSet, which has a canonical URL of:

http://hl7.org/fhir/ValueSet/observation-category

But this is not the code system URI. To find the correct system URI you need to look at the expansion table that documents each code. The correct system URI is:

http://terminology.hl7.org/CodeSystem/observation-category

2. http vs https

A URI is not a URL, though it can be one. There is no best practice that insists on https in system URIs. http://loinc.org is not the same as https://loinc.org. The first is the correct system URI for LOINC, the second is not. This problem can manifest when a developer makes a mistake, or when automated code cleaning tools insist on https, on the mistaken assumption that because a URI looks like a URL it actually is one and should be treated as one.

3. Embedding a version string in the URI

Code system versioning has its own set of processes and difficulties. Custom ways of handling versioning sometimes lead to a version string being appended to a system URI. Here’s an example:

http://loinc.org|2.83

If you’re unfamiliar with versioning in code systems, this mistake is understandable. Canonical URLs in FHIR’s conformance resource types are often rendered in this way. But it’s incorrect and will lead to the same search problems mentioned earlier. The Coding data type contains a version element that can be used to capture a code system version.

What makes these problems difficult to catch is that incorrect system URIs will often pass FHIR and profile validation. An incorrect URI in a search query can be easily fixed. An incorrect URI that has propagated across CodeableConcepts in your FHIR server is far more time-consuming to fix.

A well-structured project will define system URIs once – in code, configuration files or a database. Check that you have a process to minimize human error in these definitions.

---

Download my “FHIR Architecture Decisions” book

FHIR Weekly

Join 1,100+ business and technical leaders.