Creating an Extension Definition – part 3: Coded items

A common data type that is likely to be added in an extension are coded types – those where the value in an instance comes from a pre-defined set of possible values. There are a couple of extra things that you need to do for these.

First, a quick review of the basics.

All coded elements in FHIR (whether in the core spec or a profile) are bound to a ValueSet that describes the set of possible values for the element. The ‘strength’ of the binding determines whether an element in an instance of the resource can have a value that is not in the set. This can vary from a ‘required’ strength where the value MUST be in the ValueSet, to ‘example’ where the ValueSet is, well, just an example. In general terms, you use the ‘required’ strength sparingly, and only where it is really important to do so (‘status’ elements are the most common examples in the spec).

The ValueSet gets its contents from one or more CodeSystems, where the CodeSystem contains the actual definition of each concept, and the ValueSet is just picking the ones you want for your Use Case. For example you might want to create a ValueSet that has the most common SNOMED diagnoses made in the Emergency Department to use as a simplified ‘pick list’ in an application. The ValueSet would list the SNOMED terms to be included, and you’d likely bind it to the extension with a ‘extensible’ strength to get consistency of use, but allow uncommon diagnoses to be selected.

‘Terminologies’ is another word used for CodeSystems (though is often used in a broader context, and can get *really* complicated). And to any terminology experts reading this, I know that this description is a simplification – it is a complex domain!

It is important to note that in STU2, the ValueSet was able to also define concepts – but in STU3 (Release 3) this is now done by CodeSystem resource

Next, a quick review of coded datatypes in FHIR – there are 3 ½ of them.

The most common type that you’ll use is the CodeableConcept. This is far and away the most flexible one, as it allows you to use codes from different terminologies to represent the same concept by using multiple copies of the Coding datatype (useful when you need to represent the concept in different code systems like a ‘custom’ code and it’s representation in, say, SNOMED) and also has a ‘text’ element that can be used to represent the description of the concept – or when the coded form is not available (distressingly common in the real world!)

Coding represent a single concept in a single CodeSystem. It has 3 main properties:

• System is the uri the identifies the CodeSystem
• Code identifies the concept in the code system
• Display is the description of the concept in the CodeSystem (This is NOT the same as CodeableConcept.text)

Generally you don’t use Coding, as the CodeableConcept is significantly more flexible – unless you are sure that you’ll never need text, or need to represent the concept in multiple CodeSystems.

Next up is the code datatype – this is mostly used when there’s a small set of codes and the code is descriptive (there’s no display element). Often used for ‘structural’ elements like Observation.status or where there’s a fixed set of codes that cannot change like AllergyIntolerance.type. The binding strength of a code should always be ‘required’. You can think of code as an enumeration in computer terms – and the libraries generally treat them in that way.

And the ½ coded datatype is Quantity, as it has a coded Quantity.unit / Quantity.system (generally UCUM)

 

So when creating an extension that has a coded element, you will need to follow these steps.

1. Decide on the actual datatype you need. A safe option will be CodeableConcept.
2. Determine the ValueSet to use. If you’re lucky there will be one available for you, but if not:

a) Find the CodeSystem/s that have the concepts you need. You may need to build one if they are custom codes, though using a standard is always better. A good starting point for the search is the terminology module in the spec as there are a number of lists there (including ValueSets).

If you do have to build a CodeSystem, then remember that in STU2 it is part of the ValueSet resource.

b) Build the ValueSet – referencing the CodeSystem/s
For both CodeSystem and ValueSet you’ll need a url – the previous post on url’s, though focussed on StructureDefinition is still applicable.

3. Determine the binding strength

4. Build the Extension Definition, selecting the coded datatype and referencing the ValueSet with the appropriate strength.

 

ClinFHIR does offer some tooling to assist with this – though the functionality is quite basic at the moment (and does need to be exercised to find the bugs!)

There are other terminology tools being developed (like Ontoserver in Australia, and Apelon in the US) that are far more sophisticated, but I’m not sure if they are openly available. Forge, is the official tool for creating profiles.

Enjoy your extending!

Other posts in this series:

• Part 1 – Creating an extension
• Part 2 – Choosing the URL