Supported source data formats

All components of the FHIR Mapper are designed to handle customs data formats as the source for a mapping to FHIR. By default the FHIR Mapper supports reading and writing ‘Custom FHIR resources’ (Custom Resources), however it is also possible to provide data in other formats besides the JSON / XML serialization format of FHIR. The mapping engine therefore supports different ‘adapters’ which can be used to read in other formats natively.

FHIR Version / Content format Custom Resources (FHIR) CSV HL7 v2 VCF HL7 (C)-CDA
FHIR R4 X X     X


The FHIR Mapper supports mapping a comma-separated values (CSV) file without any prior setup. You can POST the CSV file as the HTTP Body to the $transform operation and access its metadata and content within a StructureMap.

To enable CSV support, please adjust the BinaryWrapper settings in your appsettings.instance.json to allow Vonk to accept the text/csv Content-Type header:

  "RestrictToMimeTypes": ["application/pdf", "text/plain", "image/png", "image/jpeg", "text/fhir-mapping", "text/csv"]

In order to fully use the type-safety features of the FHIR Mapping Language, a StructureDefinition is generated automatically by the FHIR Mapper when a CSV file is received. Depending on the composition of the CSV, two different formats are used:

  1. CSV file contains a header with column metadata:

For example, given a CSV file that contains the following rows:

ID, Given,        Family,     Gender
1,  Peter James,  Chalmers,   M
2,  Sandy,        Notsowell,  F

The following StructureDefinition would be produced in the background while executing $transform:

The .hasHeader child element indicates if the CSV mapping adapter was configured to interpret the first row of the CSV file as a header record. This behaviour can be indicated according to RFC 4180 by using the header parameter in the Content-Type header.

All other column identifiers are exposed as child elements of the .record BackboneElement. They can directly be used in a mapping rule:

src.record as record then
  record.ID as id -> tgt.identifier = id('<system>', id);
  record.Given as given -> as name, name.given = given;
  record.Family as family -> as name collate, = family;
  record.Gener as gender -> tgt.gender = translate('<ConceptMap>', gender, 'code');
  1. CSV file contains no header metadata:

Regardless if the CSV file contains a header, all elements are accessible for the mapping to FHIR. For files not containing a metadata row, element names for the mapping source are generated dynamically as field#:

src.record as record then
  record.field1 as id -> tgt.identifier = id('<system>', id);
  record.field2 as given -> as name, name.given = given;
  record.field3 as family -> as name collate, = family;
  record.field4 as gender -> tgt.gender = translate('<ConceptMap>', gender, 'code');