FHIR® tutorials

ConceptMap tutorial

ConceptMap is a FHIR resource that allows you to establish a one-way map between codes. We'll use latter as an example in this tutorial to demonstrate how two concepts can be related (mapped) to each other and how their equivalence (or lack of) can be specified.

This describes ConceptMap as it is in the FHIR STU3
Step 1: About ConceptMap

The ConceptMap resource in general has four parts to it:

  • Metadata about the resource
  • The source of the data
  • The target the data is mapped to, and
  • The groups of mappings themselves:

    • Metadata describes general information about the mapping - who made it, what version it is, copyright...etc.

    Source is a reference to the ValueSet that you are mapping from. Remember that ConceptMap is a one-way mapping so there's always a clear source and a target.

    Target is similar to source - it is a reference to the ValueSet you are mapping to.

    Mappings are the translations themselves, organised in groups. Each mapping (called an 'element' in the data) can have one or more target elements, which specify a connection between a code from one ValueSet to code(s) in another ValueSet. The type/strength of connection is described by the equivalence property. The equivalence expresses that the two elements are exactly the same, wider than, narrower than or the two concepts aren't related at all. The full list of equivalence values is available in the ConceptMap Equivalence ValueSet.

    Step 2: Sample data mapping

    As an example, let's say you have a (very poorly designed) ValueSet based on a CodeSystem representing employee presence at work with just three codes: present, not-present, and sick which is in use by your system. You start importing data from a new system which has finer granularity:

    Current valueset New system's valueset
    present in-office
    not-present away-travelling
    sick working-from-home
    annual-leave
    personal-leave
    jury-duty

    Your task is to create a FHIR ConceptMap translating the codes your receive to codes you already have, making use of the available equivalence values. You come up with this sample mapping that maps in the direction from the new system to your system's ValueSet:

    New system's valueset Current valueset Equivalence code
    in-office present equal
    away-travelling not-present wider
    working-from-home not-present wider
    annual-leave not-present wider
    personal-leave sick equal
    jury-duty not-present wider
    away-travelling present disjoint
    Step 3: Sample resources

    A sample ConceptMap resource containing these mappings is available. The supporting CodeSystem, old ValueSet and new ValueSet are available as well.

    Press the button below to upload these resources to the FHIR server!


    The ConceptMap resource will be available at this URL:

    (press Upload to get a ConceptMap)

    Once uploaded, it'll look something like thiswhen you GET the ConceptMap via Postman.

    Step 4: Advanced features

    ConceptMap is actually pretty powerful, and besides the basic code-to-code mapping described above, it also supports the following usecases:

    • Mapping one code to many codes at once given the same equivalence property (by utilising multiple target properties within one element property)
    • Having a dependency for a mapping, a mapping could only be applicable if a selected element exists in the data and has the specified value (see dependsOn)
    Step 5: $translate operation

    The $translate operation allows you to utilise a FHIR terminology server to get an equivalent code as specified by a ConceptMap mapping. To use it, you need to provide the ConceptMap you'd like to use, the input code and its CodeSystem, and the valueset you'd like to get a translation from. Try the $translate operation on the four sample resources uploaded above (a CodeSystem, two ValueSets, and a ConceptMap) via Postman using this template:

    https://ontoserver.csiro.au/stu3-latest/ConceptMap/ConceptMap/servers-conceptmap-id/$translate?code=my-code&system=codes-codesystem&target=target-valueset

    Here's a sample code you could try, once you've uploaded your conceptmap to a terminology server of choice:

    https://ontoserver.csiro.au/stu3-latest/ConceptMap/a912ee54-30e8-4a1a-8f2a-1a4337aaf69c/$translate?code=in-office&system=urn:uuid:bb6efb79-2b93-4569-a51e-6fcf103b6e9a&target=urn:uuid:a5f94e22-ddba-474e-80e3-b067d9c27a55

    That's it! You're done for now.