FHIR StructureMaps: Enabling Bi‑Directional Data Transformation
Healthcare interoperability work often starts with a simple premise: exchange data between systems in a consistent, reliable way. But as everyone who has ever been involved in a healthcare integration project knows, reality is rarely simple. Models differ, semantics vary, and entire concepts don’t always have equivalents across systems.
In a recent project, we needed to bridge exactly this kind of gap. The sector we were working in - unlike healthcare - had no defined interoperability standard. What it did have was a well‑defined operational dataset that is currently being adopted by software providers across the industry. That dataset became our de facto domain model, but we still needed a clean, scalable way to map it to and from standardised FHIR resources.
This is where FHIR’s StructureMaps and the $transform operation became invaluable. They provided a robust, standards-based mechanism to support bi-directional data transformation - without us having to invent yet another bespoke mapping engine.
TL;DR
✅ Delivering bi‑directional transformation between a domain‑specific operational dataset and FHIR, despite having no established interoperability standard.
✅ Leveraging existing capability instead of building a new tool by using FHIR StructureMaps and the $transform operation already available in our platform.
✅ Modelling each domain class as a FHIR Logical Model (StructureDefinition type = logical), giving $transform a formal schema for non‑FHIR structures.
✅ Creating paired StructureMaps to enable clean, deterministic round‑trip mappings.
✅ Keeping transformation logic declarative and governed by using $transform for version‑controlled mappings outside application code.
✅ Future‑proofing interoperability by aligning with FHIR‑based Shared Care Records and NHS services.
Why FHIR, Even Outside Healthcare?
Even though the domain we were working in wasn’t traditional healthcare, FHIR offered significant advantages.
First, it provides a mature, extensible modelling framework with strong conventions, governance patterns, and well‑established tooling. This made it an excellent candidate for serving as our canonical data layer.
But just as importantly, FHIR is one of the most widely adopted interoperability standards in modern healthcare, with adoption increasing across many countries and national health systems. Recent global surveys show that FHIR is now used for at least some use cases in over 70% of countries surveyed, and many national programmes mandate or encourage its use. By using FHIR as the canonical model we gained immediate strategic benefits:
- Future‑proofing for integration with Shared Care Records, many of which are increasingly FHIR-native.
- Alignment with strategic NHS interoperability programmes, which standardise on FHIR for structured data exchange.
- Compatibility with downstream health and care services, where FHIR is already widely adopted.
- The ability to surface data cleanly to health-facing systems, without building custom one-off or proprietary interfaces.
Even though our domain didn’t originally require a healthcare standard, choosing FHIR brought clear long‑term value. It positioned the platform to participate easily in broader care pathways, cross-sector collaborations, and national interoperability initiatives—all without additional transformation layers.
In short: adopting FHIR wasn’t just technically convenient. It was strategically smart.
The Core Challenge: Two Models, No Common Language
The platform needed to support bi-directional transformation:
Inbound: operational dataset → FHIR
Outbound: FHIR → operational dataset
However, this was far from straightforward. The operational dataset was designed for real-world workflows, not solely for interoperability. This introduced challenges such as:
- One-to-many and many-to-one mappings
- Conditional transformations based on business context
- Value harmonisation across different enumerations
- Mismatched optional/mandatory fields
- Conceptual gaps with no direct model equivalence
We needed a transformation approach that was reliable, transparent, and maintainable - without scattering mapping logic across application code.
Why $transform Was the Right Choice
When exploring transformation options, we were absolutely clear about one thing:
We did not want to build “yet another transform tool.”
The last thing we wanted was a bespoke, hand-crafted mapping engine buried in service/application code. We wanted to avoid using templating or code translations - this felt too close to what FHIR StructureMaps offered. In addition, encouraging an industry to procure a “traditional” healthcare integration engine was also not an idea worthy of practical consideration.
Instead, we wanted to reuse capability we already had: a standards-compliant FHIR server with built‑in support for:
Does a standards‑based transformer beat a bespoke one?
Using $transform provided key benefits:
- Mapping rules live outside application code.
- StructureMaps can be validated using standard tools.
- Transformations can be versioned, governed, and reviewed.
- Logic is readable to both domain and technical teams.
- Behaviour is consistent across environments and deployments.
- Transformations are portable to any compliant FHIR implementation.
By leaning on $transform and StructureMaps, we avoided reinventing the wheel and delivered a far more maintainable and future‑proof solution.
How We Built the Mapping Layer
1. Analyse the operational dataset
We documented and modelled:
- Entities, fields, and relationships
- Data types and enumerations
- Implicit workflow rules
- Natural groupings and lifecycle patterns
This became our authoritative domain model.
2. Identify the appropriate FHIR resources
We mapped domain concepts to their closest FHIR equivalents. For example:
- Subjects of Care →
PersonorPatient - Providers/workers →
OrganizationorPractitioner - Activities/instructions →
Task - Assessments →
Observations
Extensions were used sparingly and only when necessary. We also avoided the temptation to create custom resource profiles.
3. Create FHIR Logical Profiles for Each Domain Model Class
To support transformation from our operational dataset into FHIR, the transform engine needed a formal understanding of the structure of our non‑FHIR domain classes. To achieve this, we generated a FHIR logical profile for each class in the authoritative domain model.
These profiles:
- Described the fields, data types, cardinalities, and relationships present in the domain model
- Provided the
$transformengine with a FHIR-compatible StructureDefinition for each non‑FHIR source or target type - Enabled StructureMaps to reference the domain structures using fully qualified FHIR paths
- Ensured that our transformation logic was expressed within FHIR’s own modelling and validation ecosystem
We chose to use StructureDefinition resources of type = logical, because - according to the FHIR specification - logical models represent abstract patterns or templates, not full resources or complex types. This allowed us to model the operational dataset as a first‑class FHIR artefact without implying that these structures should exist as actual FHIR resources.
This step became an essential foundation for enabling clean, deterministic, and strongly-typed transformations in both directions.
4. Create StructureMaps
Each StructureMap defined:
- Field-to-field mapping
- Conditional logic
- Value transformations
- Iterations over lists/collections
- Enumeration lookups
- Conceptual translations where no direct mapping existed
Reversibility was planned from the start by creating paired maps for each direction. We used FHIR Mapping Language to create the StructureMap resources.
5. Execute transformations using $transform
The transformation layer invoked $transform to apply the appropriate StructureMap, ensuring:
- Consistent behaviour across integrations
- Version-controlled, testable mapping logic
- A clean separation between business logic and data transformation
- Predictability and traceability
Key Lessons Learned
1. StructureMaps are powerful, but require discipline
Without good conventions they become dense quickly. We established standards around:
- Naming conventions
- Rule grouping
- Documentation and comment patterns
- Modularisation through dependent maps
2. Bi-directional mapping must be designed intentionally
Round‑trip fidelity is not automatic. Paired maps ensured no information was lost.
3. FHIR works brilliantly beyond healthcare
Its extensibility, tooling, and governance model make it ideal for any structured domain.
4. Domain understanding matters more than technology
The operational dataset reflected real workflows. Deep domain knowledge was essential to designing meaningful transformations.
5. None of this comes for free
The predicate to embarking on this approach was having access to a concrete, battle-hardened, implementation of the FHIR $transform specification.
Conclusion
Using FHIR StructureMaps and the $transform operation allowed us to build a powerful, flexible, bi-directional transformation layer—without creating another custom mapping engine. By combining a domain‑driven operational dataset with a standards‑based transformation framework, we achieved an integration architecture that is:
- Maintainable
- Extensible
- Versioned
- Standards‑aligned
- Future-proof—especially for health-sector interoperability
This pattern isn’t limited to healthcare or social care. It applies to any domain where long-term, structured interoperability is essential.
