StructureMap — Mapping between data models

The FHIR transformation engine: convert HL7 v2 to FHIR, CDA to FHIR, FHIR R4 to R5, a project resource to its standardised version. Expressed in the FHIR Mapping Language.

Purpose of the resource

StructureMap describes a transformation between two data models. The language used is the FHIR Mapping Language, designed by HL7 for that purpose. The transformation is typically written by an integrator, validated by an editor, and then executed server-side by the $transform operation.

The Matchbox FHIR server, HAPI Mapping Engine, IBM Mapping Server, and most commercial integration platforms (Mirth Connect FHIR, Rhapsody) consume StructureMap.

Key fields

JSON example

{
  "resourceType": "StructureMap",
  "id": "example-pid-to-patient",
  "url": "http://example.org/StructureMap/pid-to-patient",
  "version": "5.0.0",
  "name": "PIDToPatient",
  "status": "active",
  "structure": [{
    "url": "http://hl7.org/fhir/StructureDefinition/Patient",
    "mode": "target"
  }],
  "group": [{
    "name": "PIDtoPatient",
    "typeMode": "none",
    "input": [{
      "name": "source",
      "mode": "source"
    }, {
      "name": "target",
      "mode": "target"
    }],
    "rule": [{
      "name": "pid3-to-identifier",
      "source": [{
        "context": "source",
        "element": "PID-3"
      }],
      "target": [{
        "context": "target",
        "element": "identifier",
        "transform": "create",
        "parameter": [{ "valueString": "Identifier" }]
      }]
    }]
  }]
}

$transform operation

• POST /StructureMap/{id}/$transform with a source resource (Bundle, Parameters).
• The server applies the StructureMap rules and returns the target resource.
• Lets you expose v2 → FHIR or cross-version conversion as a simple REST service.

Common pitfalls

• FHIR Mapping Language as free text — always serialise into JSON for server-side execution.
• No structure — the server does not know which models to expect.
• Duplicate ruleId — prevents rules from cleanly wiring input/output.

Related resources

• StructureDefinition — source/target model.
• ImplementationGuide.
• ConceptMap — code mapping.
• GraphDefinition.
• FHIR R5 hub.