v2+ Vocabulary
0.2.0 - Working Draft to present the concept ideas (FO)

v2+ Vocabulary - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions


General Remarks

This page offers explanations about foundational issues for terminologies and classifcations.

What is a Terminology

A terminology is in principle a structured (optionally hierarchical) set of codes that denote a specific concept. The hierarchy, if introduced, does not allow for exceptions.


The hierarchy enables to stay on a certain level if more clarity cannot be achieved. In the above drawing that would allow to use “C” as a code, if specialisation into “C1” or “C2” cannot be determined.

What is a classification

A classification is a statistical categorization that strives for a coverage of 100%, and therefore is clearly oriented towards a specific use case. Therefore, it contains classes the cover the remaining concepts that do not fall into the other ones:

ClassificationRootThis is the root node.AThis is A, but morespecifics are not knownBThis is B, but morespecifics are not knownCThis is C, but morespecifics are not knownDThis is D, but morespecifics are not knownA1A2A3A_OtherThis is everything more specialthan A, but not the other.This is everything more specialthan A, but not A1, A2 or A3Adding A4 would change that to "not A1, A2, A3 or A4",thus changing the meaningB1B2B_OtherThis is everything more specialthan B, but not B1 or B2C1C2C_OtherThis is everything more specialthan C, but not C1 or C2

Mapping codes in a classification

Mapping from “one version” to the next is tricky. Only codes where the same semantics can be assured allows for a mapping. That especially excludes the “other” codes the meaning of which is unclear with regard to a target concept because the new concept was previously covered within “other”.

Classification MappingOld OtherOld OtherOld OtherA4A-OtherB3B-OtherC-OtherRoot (Version x)ABCA1A2A3A-OtherB1B2C-OtherC1C2C-OtherRoot (Version x+1)ABCA1A2A3B1B2C1C2mapmapmapmap?map?mapmapmap?map?mapmapmap

We can of course map “other” back to the previous version…

Or to the new version if no changes can be identified.

Mapping codes in a terminology

Mapping from “one version” to the next is simple: The codes with the same meaning can be mapped:

TerminologyRoot (Version x)ABCDA1A2A3B1B2C1C2Root (Version x+1)ABCDA1A2A3A4B1B2C1C2C3mapmapmapmapmap?mapmapmapmapmapmapmap?map

So, the new codes can be mapped back to the more general concept as they are subsumed by it. It is not decidable whether a general code in the old version may be used for a more specific in the new version, but that remains to further checking.


An important question is for versioning: How to create different versions for codesystems with regard to identification?

Technically, each codesystem has an identification - a canonical - in combination with a version. Together, both provide a unique identifier.

The primary question is how to identify, if a new version is incompatible with a previous one. Compatibility in this case refers to semantic equivalence of each concept. In other words, each concept of the prvious version is contained in exactly the same way in the new version. And each addition of new codes does not impact the semantics of old codes. That clearly refers to the previous explanation about classifications, that technically are also maintained as codesystems.

At this point, the way the version is maintained plays an important role. There are two options, that are explained following:

Version as an integer

A simple number just being comprised of a simple positive integer value does not allow for many options. Such a number can only be increased. It does not allow for indicating incompatiblities or differentiations between additions of codes and technical corrections. As a consequence, a new primary identifier must be introduced - with all associated other consequences for a solid maintenance.

Using semantic versioning

Semantic versionining according to semver makes use of the following schema with three components where the first two are pure integer values, whereas the third is an integer with optional appendices separated by a plus or minus sign:


As long as a new version is semantically compatible with the previous version, only the minor number is increased by one. (Even more minimal changes like typos can be corrected by using the patch number.) Incompatible changes, especially for classifcations may then be introduced by the next major number keeping the primary identification the same.


From this short introduction, semantic versioning seems to be more appropriate. A new codesystem, that is introduced by a new identifier, is cleary taken as new by that means. Increasing the major number alone does not necessarily impose the common understanding be everyone that simple comparisons and mappings of codes between those versions are not allowed by default, and require a thorough verification.

v2.x Impact

Changing the version numbering scheme from simple integers to semver simplifies the maintenance according to the aforementioned reasons but it also implies a major - incompatible - change for chapter 2C:


All version numbers will be changed!