Model Mappings

The first layer of mappings are the model mappings. These serve as a reusable base for FHIR-to-openEHR mappings and form the core of FHIRconnect. Each of these mappings connects either a FHIR DomainResource or a BackboneElement to an openEHR archetype.

FHIRConnect is designed with the vision of creating a generically valid library of archetype-to-FHIR mappings. This library is the core strength of FHIRconnect. The goal is for this library to be maintained by the community, with everyone contributing their basic mappings, correcting existing ones, and adding new ones. In this way, the library will grow over time, containing an ever-increasing number of refined archetype mappings.

The model mapping header was already introduced in the first chapter under Header.

engine: FHIRConnect/v0.0.1  # Specifies the grammar and version used in this file
type: model  # The type of mapping: model, extension, or context
metadata:
  name: ACTION.informed_consent.v0  # The name of the mapping
  version: 1.0.0  # The version of this particular mapping
spec:  # Schema specific to the FHIRConnect v0.0.1 engine
  system: FHIR  # Specifies what is being mapped
  version: R4
  openEhrConfig:
    archetype: ACTION.informed_consent.v0  # The openEHR archetype being mapped in this model mapping
  fhirConfig:
    structureDefinition: http://hl7.org/fhir/StructureDefinition/Consent  # The FHIR StructureDefinition to which this is mapped

Folders and Namespaces

In general the folder structure of each FHIRconnect project is up to the provider. The official library follows the pattern described here. Each of these model mappings aims to be as generically valid as possible. They can be found in the mapping/model folder. Here, the models are organized based on their openEHR archetype type.

OpenEHR has several model libraries, being the international CKM the most important one. This contains the international models used by openEHR platforms. Model mappings for these can be found under the folder org.openehr, which indicates the namespace of an archetype. Sometimes, local models are created to meet national requirements. For example, the models from HiGHmed are located under org.highmed.

Inside these folders, the model mappings are stored. Occasionally, there will be more than one model mapping for the same archetype that differ in their FHIR output. For example, the dosage archetype has two mappings: one for dosage-to-dosage and another for dosage-to-backboneElement. The dosage-to-dosage mapping is treated as the default, so its name is simply dosage.v2.

This naming convention was chosen because the dosage-to-dosage mapping is naturally more comprehensive compared to the backboneElement mapping. For processing, these files are called by their metadata.name, making them distinguishable. The name of a model mapping file always starts with the name of the archetype (excluding the openEHR-EHR-TYPE).

Model Mapping Examples

To illustrate the explained methods, here is an example of a mapping between the problem_diagnosis archetype and the FHIR Condition resource.

engine: FHIRConnect/v0.0.1
type: model
metadata:
  name: EVALUATION.problem_diagnosis.v1
  version: 0.0.1-alpha
spec:
  system: FHIR
  version: R4
  openEhrConfig:
    archetype: openEHR-EHR-EVALUATION.problem_diagnosis.v1
  fhirConfig:
    structureDefinition: http://hl7.org/fhir/StructureDefinition/Condition

mappings:

  - name: "contextStartTime"
    with:
      fhir: "$resource.recordedDate"
      openehr: "$composition/context/start_time"

  - name: "participations"
    with:
      fhir: "$resource.asserter"
      openehr: "$composition/context/participations"
    participationsFunction: "asserter"

  - name: "composer"
    with:
      fhir: "$resource.recorder"
      openehr: "$composition/composer"

  - name: "other_participations"
    with:
      fhir: "$resource.asserter"
      openehr: "$archetype/other_participations"
    participationsFunction: "asserter"

  - name: "provider"
    with:
      fhir: "$resource.recorder"
      openehr: "$archetype/provider"  # Often required, so the simplified mapping engine resolves Reference -> Participations

  - name: "problemDiagnose"
    with:
      fhir: "$resource.code"
      openehr: "$archetype"
      type: "NONE"
    followedBy:
      mappings:
        - name: "problemDiagnoseName"
          with:
            fhir: "coding"
            openehr: "data[at0001]/items[at0002]"
        - name: "problemDiagnoseText"
          with:
            fhir: "text"
            openehr: "data[at0001]/items[at0009]"

  - name: "note"
    with:
      fhir: "$resource.note.text"
      openehr: "$archetype/data[at0001]/items[at0069]"

  - name: "dateTime"
    with:
      fhir: "$resource.onset"
      openehr: "$archetype/data[at0001]/items[at0077]"

  - name: "bodySite"
    with:
      fhir: "$resource.bodySite"
      openehr: "$archetype/data[at0012]"

  - name: "bodySiteCluster"
    with:
      fhir: "$resource"
      openehr: "$archetype/data[at0001]/items[openEHR-EHR-CLUSTER.anatomical_location.v1]"
    slotArchetype: "CLUSTER.anatomical_location.v1"

  - name: "severity"
    with:
      fhir: "$resource.severity"
      openehr: "$archetype/data[at0005]"

Mapping 0..0 fields

Since model mappings should include all archetype to resource mappings, these will contain some mappings that are not part of the corresponding Profile/Templates, as they have (0..0) occurrences. These are ignored and not executed.