FHIR coding, and the codeableConcept datatype

Many elements in the FHIR resources have a coded value, of which one of the more common types is the  codeableConcept.  (The other two are the code and the coding datatypes – which we’ll meet shortly). Coded data allows for precision of data collection, more accurate reporting, and lays the foundation for Decision Support and so is very important in the recording of healthcare information.

(I’m going to preface this discussion by stating that coding clinical data is a complex topic, and this post does not go into all the details of coding data – it is intended to make sure that you have a basic understanding of how to use this datatype in FHIR. There are lots of links where you can go to get more information if you need it.)

In the words of the specification:  “A CodeableConcept represents a value that is usually supplied by providing a reference to one or more terminologies or ontologies, but may also be defined by the provision of text”. It’s actually quite well described in the specification (as most things are, in truth), but I thought I’d write a short note about it – mostly because I said I would at the end of the last post – but also because it’s so commonly used in FHIR that’s it’s worth being familiar with it.

Examples of where you might use it include:

• The code for a problem (called a condition in FHIR)
• The medication code in a prescription
• The patients gender
• Symptoms observed during an adverse reaction

and there are lots of other situations as well – apart from a string it’s probably the most commonly used datatype in FHIR (I should write a short program to check that – perhaps I’ll leave it as ‘an exercise for the reader’!)

If you look at the definition of the codeableConcept, you will see that is actually a combination datatype:

• a text property of type string
• 0 or more coding properties of type coding

Evidently the coding datatype does most of the work. This structure allows you to capture the clinical information that is being coded (ie the description in plain text) as well as multiple representations of that text in the coding system of choice.

Confused? Well, imagine that the clinician entered “atopic asthma” and you wanted to represent that in a problem list. You might want to code that as “Allergic Asthma” in snomed (389145006) and “Extrinsic asthma – unspecified”  in ICD-9 (493.00). The codeableConcept allows you to have both of these codes, plus the original text entered by the clinician, and upon which the encoding was performed.

The coding datatype is the actual representation of the code in the coding system of choice. It has the following properties – all of them optional.

• System. This is a URI that identifies the terminology (or collection of codes) from which the actual code value is chosen. Although marked as optional, if it is not present, then the value of the code is severely diminished. There are a number of places you can get this from:
  • There is a set of named lists in FHIR that has the most commonly used terminologies
  • The HL7 OID registry
  • Any other option that uniquely identifies the set of codes.
• Version. The version of the terminology that the code is drawn from. This applies particularly to SNOMED, LOINC & ICD.
• Code. The actual code from the terminology. If this is absent but there is a system property, then the meaning is that no suitable code could be found in that terminology. In all other circumstances, it doesn’t make a lot of sense not to include it.
• Display. This is the display of this code in the terminology (which may not be the same as the text being coded).
• Primary. If this is true, then it means that this code was explicitly chosen by the user – eg it was in a drop down or autocomplete that the user selected, rather than being generated ‘second hand’ – say by some coding algorithm, or mapping from some other terminology. The significance is that it will be the most accurate, if there is more than one coding present.
• Valueset. This is included for 2 reasons:
  1. In some cases, the valueSet itself defines the code system and there’s no other way to determine the meaning of the codes (e.g. the codes are “a”, “b” or “c” from a questionnaire)
  2. There are some use cases where the set of choices available when the code was chosen is relevant to interpreting the code. – eg if the user only had 10 choices, they may have made a different choice than if there had been 100.

  However, even when using value set, you still need to populate the system.

So, lets create a  rendering of the asthma  example given above, assuming that we are placing this in a condition resource in the code property:

    <code>
        <!-- SNOMED code -->
        <coding>
            <system value="http://snomed.info/id"/>
            <version value="International Release – 20130731"/>
            <code value="389145006"/>
            <display value="Allergic Asthma"/>
            <primary value="true"/>
        </coding>
        <!-- ICD code -->
        <coding>
            <system value="urn:oid:2.16.840.1.113883.6.42"/>
            <version value="9"/>
            <code value="493.00"/>
            <display value="Extrinsic asthma - unspecified"/>
            <primary value="false"/>
        </coding>
        <text value="Atopic Asthma"/>
    </code>

From this we can tell that the clinician entered ‘atopic asthma’ but accepted the SNOMED code of allergic asthma.

When a terminology or codeset is associated with a particular resource property, this is called a binding. Each resource description in FHIR displays the bindings that are defined for that resource immediately below the description of the resource content. Each binding has the following properties:

• Path. The resource property that is being bound.
• Definition. Describes the binding.
• Type. The ‘strength’ of the bindings. Options are:
  • Fixed means that there is a specific set of values defined in the spec than cannot be extended. Usually this is for ‘code’ datatypes (see below)
  • Incomplete means there is a recommended set of values but can be extended by implementers
  • Example – it is really up to each implementation to decide
  • Unknown – not yet decided
• Reference. A link to the terminology or codeset.

Some other things to note:

• In theory a resource could have a property with a datatype of coding – in practice this is not often done (if at all). The codeableConcept is far more flexible than coding – for example, it would support a property that *can* be coded, but for some reason is not in this specific instance – such a patient problem/condition where the problem description has been captured, but not yet formally coded.
• There is also a code datatype that many resources employ. Generally this is used for ‘workflow’ type purposes, and the codeset from which it is drawn is defined – and fixed – by the designers of the resource. The mode property of the List resource is an example of this – it is important  that any user of a List resource should be able to correctly interpret this property on any list, with clinical safety issues if not.
• The equivalent to the codeableConcept in v3 (or CDA) is the CD – Concept Descriptor – datatype. CD is more complex than codeableConcept, though the extra functionality it offers (such as translations) are not often needed in practice (which is why it was simplified in FHIR). Should you find that you need to do so, then the FHIR extension mechanism can be applied to datatypes as well as resources.

So, enjoy the codeableConcept!