StructureMap

StructureMap defines transformations using a declarative syntax, not procedural code. Each rule specifies a source context, a target context, and a transform expression. This allows the engine to optimize execution order and enables static analysis of the map for correctness. Rules can be conditional, using FHIRPath expressions to gate execution based on source data values. The declarative model separates the what from the how, making maps auditable by clinical informaticists without requiring deep programming knowledge.

Maps are organized into groups, which are logical containers for related rules. Each group has:

• Input: One or more source resource types or data structures
• Output: The target resource or element being constructed
• Rule set: The transformations to execute

Groups can be nested and invoked like functions, enabling reuse. A group that maps a Patient resource can be called from multiple parent groups, ensuring consistent transformation logic across an entire implementation guide.

StructureMap uses FHIRPath as its expression language for all value computation and conditional logic. This provides:

• Source extraction: source.name.given to pull a patient's first name
• Conditional execution: source.birthDate < today() - 18 years to gate rules
• String manipulation: source.name.family & ', ' & source.name.given for formatting
• Type checking: source.value is Quantity to branch logic

Because FHIRPath is a standardized, implementation-independent language, maps remain portable across different FHIR server implementations.

StructureMap supports typed variables that hold intermediate results during transformation. Variables are scoped to their defining group and can store:

• Primitive values: Strings, integers, booleans
• FHIR resources: Fully constructed resources for later reference
• Lists: Collections of elements for iteration

This enables complex multi-step transformations where a value extracted early in the map can be referenced in multiple target elements later, avoiding redundant extraction logic and ensuring consistency.

Maps can declare dependencies on other StructureMaps, enabling modular composition. A high-level map for converting a CDA document to a FHIR Bundle might invoke:

• A CDAtoPatient map for the subject
• A CDAtoMedicationRequest map for prescribed medications
• A CDAtoObservation map for vital signs

Each dependency is resolved at execution time. This promotes a library of reusable, tested transformation components rather than monolithic, single-use maps. Circular dependencies are detected and rejected during parsing.

StructureMap provides explicit directives for how targets should be constructed:

• create: Instantiate a new resource or element
• copy: Duplicate a source element to the target
• truncate: Copy but limit to a specified length
• escape: Apply FHIR escaping rules to the value
• cast: Convert between compatible data types
• append: Add to an existing list rather than replacing
• translate: Apply a ConceptMap to convert codes

These directives give precise control over data shaping, ensuring the output conforms exactly to the target FHIR profile's constraints.