FHIR data transformation happens in most integrations — mapping legacy data to FHIR, converting between profiles, or restructuring for downstream consumption. Two approaches: StructureMap or application code. The choice matters for maintainability.
When StructureMap wins
1. Cross-profile transformations. National Patient profile → US Core Patient is textbook StructureMap. 2. Version-controlled mapping specifications. StructureMap resources live in Git; changes are reviewed. 3. Cross-team collaboration on mappings. Clinical informaticists can review StructureMap; application code less so. 4. Reusable across contexts. Same StructureMap used in multiple systems.
When application code wins
1. Complex business logic beyond mapping. Business rules, side effects, external lookups. 2. Performance-critical hot paths. Application code often faster. 3. Prototyping and iteration speed. Application code is easier to iterate. 4. When your team doesn't have StructureMap expertise. Learning curve is real.
Executing StructureMaps
`$transform` operation on a terminology-capable server. HAPI FHIR and Aidbox both support execution. MITRE's cqf-ruler is the reference implementation.
Common pitfalls
1. Missing target profile. StructureMap needs a target StructureDefinition. 2. Terminology mapping embedded. Should reference ConceptMaps, not embed. 3. No test coverage. StructureMaps deserve unit tests like any code. 4. Application code as fallback. Duplicating logic in both places creates drift.
Decision matrix
| Transformation type | StructureMap | Application code |
|---|---|---|
| Cross-profile | Preferred | Fallback |
| Business logic + mapping | Mapping part | Business part |
| High-volume hot path | Rare | Preferred |
| Prototype | Rare | Preferred |
FHIR transformations are a subsystem. Get the boundary between declarative (StructureMap) and imperative (code) right, and the transformation layer scales with the business.