@synanetics/fhir-translate

This repository contains functionality for performing translate operations in FHIR.

Currently we support the translation of FHIR Coding and CodeableConcepts resources using a FHIR ConceptMap.

Usage

import { conceptMapTranslate as tranlsate } from '@synanetics/fhir-translate';

// or

const { conceptTranslate: translate } = require('@synanetics/fhir-translate');

const parameters: Stu3Parameters = {
  resourceType: 'Parameters',
  parameter: [
    {
      name: 'coding',
      valueCoding: { system: 'http://hl7.org/fhir/address-use', code: 'home' },
    },
  ],
};

const result = translate({ parameters, fhirVersion: 'stu3', conceptMaps: [Stu3ConceptMapAddressUse as Stu3ConceptMap] });

The conceptMapTranslate function accepts an object with four properties:

• parameters - A FHIR Parameters resource representing the translate Operation to be performed. The parameters resource can be in STU3 or R4 format.

• fhirVersion - one of 'stu3' and 'r4'. The fhirVersion controls the behaviour of the function, how it should interpret the input parameters and the structure of the output parameters. Note that while 'stu3' and 'r4' translate operations are largely the same they have been changed in 'r5', and so this is included for forward compatability if 'r5' translations are to be supported in the future.

• conceptMaps - an array of STU3 or R4 Concept Maps with which to do the translations.

• otherMaps - an optional object of STU3 or R4 ConceptMap resources keyed by the canonical url of the ConceptMap. These additional ConceptMap resources are used by the translate function when a ConceptMap group contains an unmapped property with mode other-map. In this situation the translate function will lookup the other-map url in the otherMaps object to continue attempting to map the Coding. The translate function will error if the maximum recursion depth is exceeded when recursively evaluating other-map resources.

FHIR Documentation

See the links below for the ConceptMap resources and the $translate Operation for different FHIR versions: STU3 ConceptMap STU3 $translate R4 ConceptMap R4 $translate R5 ConceptMap R5 $translate

Notes

Equivalence and 0..1 Cardinality

In stu3 the ConceptMap has 0..1 cardinality for equivalence, while r4 has 1..1 (and r5 renames it) to relationship (but also 1..1). If we compare STU3 and R4 example ConceptMaps we note that where the equivalence is empty is STU3 it is 'equivalent' in R4, suggesting an emtpy value defaults to 'equivalent'.

ValueSet Uri Validation

Each ConceptMap resource is concerned with mapping a given source ValueSet to a target ValueSet. The conceptMapTranslate function accepts an array of one or more ConceptMap resources and returns the applicable mapping for the input Coding, it does not however validate that the ConceptMaps it has been given are for the source and/or target ValueSets requested in the Operation. Due to the fact that ConceptMap.target and ConceptMap.source are choice elements (in stu3 this may be a Reference or a uri, and in R4 a uri or canonical url), the translate function is not capable of resolving these ValueSets to assert that they are indeed for the given Operation Parameters, but assumes that the ConceptMap(s) are correct for the given translation.

Reverse with Unmapped

In STU3 and R4 $translate operations a reverse parameter may be passed in. The function of the parameter is to change how the translate function operates. With reverse=true rather than map the input code to a target code in the ConceptMap, the translate function will instead determine what possible codes in the ConceptMap might result in a mapping to the input code.

In the case where the input code matched the group.unmapped code this would mean that we would need to determine all the codes in a ValueSet that would result in being unmapped. As the translate function does not know the source ValueSet for a given ConceptMap and does not have the capability to find the ValueSet, the group.unmapped section is ignored when reverse=true and the result will be a failed translation.