@synanetics/fhir-fml-convert

Converts FHIR StructureMaps from FML format to deserialised FHIR StructureMap objects, using the @types/fhir NPM package.

Usage

import convert from '@synanetics/fhir-convert';

const fml = `
map "http://example.org/StructureMap/MyMap" = MyMap

group PatientToPerson(source src : Patient, target tgt : Person) {
}
`;

const structureMap = convert(fml);
assert(structureMap.name).toEqual('MyMap');

Detailed description

This package has been created to support the Interweave NRL project. Namely, to convert FML StructureMaps to JSON so that:

1. they can be stored in the Interweave Connect Appliance's data store
2. they can be parsed by the existing StructureMap transformer

This package makes use of "antlr4ts" to automatically generate some code that helps us parse the ANTLR4 grammar for the FHIR Mapping Language. The ANTLR4 grammar supplied by HL7 is riddled with mistakes and oversights that have been corrected in the file FhirMapper.g4 in this package. So that the grammar can be properly parsed, the fhirpath.g4 grammar has also been included. Without the inclusion of this grammar, the inclusion of any FHIR path expressions in the FML causes a parsing error.

Note: this is a CommonJS package, because the generated ANTLR helpers are CommonJS (and no ESM generation option is available).

Development dependencies

The "antlr4ts-cli", which is used to generate the ANTLR parser helpers depends on JRE 1.6 or above. Note that this is only a development dependency, and not a runtime dependency (the generated files are a runtime dependency).

Supported features

• Choice of output FHIR version for the StructureMap.
• Uses FHIR Path-style default value parsing. As such, all default values map to the defaultValueString choice element in produced STU3 and R4 StructureMaps, and the result is expected to be evaluated as a FHIR Path expression. Default values were always intended to be parsed as FHIR Path expressions and the inclusion of the choice element defaultValue[x] in STU3 and R4 was essentially a mistake, rectified in R5.
• Primitive metadata parsing: metadata elements in FML begin ///, and complex elements may be defined using the syntax described in the specification. In this implementation, only primitive values (e.g. 'url', 'name', 'title', 'experimental' and 'status' from the specification) are supported, whereas complex types (e.g. 'jurisdiction' from the specification) are not.

Unsupported features

• Constants are not currently supported, as we do not yet need them.
• list-option in source transformations, as we do not yet need this (side note: it is unclear how this actually works).
• check: StructureMap rules offer a "check" condition, which, if failed, should cause the program that evaluates the map to throw an exception. These instructions are not currently being parsed from the FML into the deserialised StructureMap object.
• list_modes have not been implemented and, like list-option, it is unclear how these work.