FHIR Mapping Language (FML) is a declarative, syntax-driven language defined by HL7 to author the transformation logic that converts legacy healthcare data—such as HL7 v2, CDA, or custom formats—into standardized FHIR resources. It provides a formal, machine-executable grammar for defining how source data elements are extracted, manipulated, and assigned to target FHIR elements, ensuring deterministic and repeatable data conversion. FML is compiled into a StructureMap resource, which serves as the executable artifact for FHIR-based transformation engines.
Glossary
FHIR Mapping Language
A domain-specific language designed by HL7 to author the transformation rules that convert legacy healthcare data formats into FHIR resources.
HEALTHCARE DATA TRANSFORMATION
What is FHIR Mapping Language?
A domain-specific language designed by HL7 to author the transformation rules that convert legacy healthcare data formats into FHIR resources.
The language operates through a structured syntax of map, group, and rule constructs, where a map defines the overall transformation, groups organize related mappings, and rules specify the precise element-level assignments using FHIRPath expressions. FML supports conditional logic, data type conversions, and terminology translations, enabling complex semantic mapping beyond simple structural alignment. By externalizing transformation logic from hard-coded scripts into a standardized, version-controlled language, FML promotes interoperability and maintainability across healthcare integration projects.
CORE CAPABILITIES
Key Features of FHIR Mapping Language
The FHIR Mapping Language is a domain-specific grammar designed by HL7 to author deterministic transformation rules that convert legacy healthcare data formats into valid FHIR resources.
01
Declarative Transformation Syntax
FML uses a declarative, rule-based syntax rather than imperative code. You define what the output should look like, not how to build it. This allows the engine to optimize execution.
- Key Concept: Rules are grouped into
groupelements that correspond to input data structures. - Execution: The engine walks the input tree and applies the first matching rule.
- Benefit: The logic is auditable by non-programmers and directly represents the mapping specification.
02
StructureMap Resource Compilation
FML source code is compiled into a StructureMap resource, which is the executable artifact. This two-step process separates authoring from execution.
- Compilation: The FML compiler validates syntax and generates the StructureMap JSON or XML.
- Execution Engine: Any FHIR server or tool with a StructureMap engine can execute the compiled map.
- Portability: The compiled StructureMap is a standard FHIR resource, ensuring it can be shared and executed across different platforms without the original FML source.
03
Nested Context and Variable Scoping
FML manages complex hierarchical data through nested groups and context variables. This allows mapping from deeply nested legacy formats like HL7 v2 or CDA.
- Context Stack: Each
groupinvocation pushes a new context onto the stack, holding the current input element. - Variable Binding: Use
varto capture intermediate values andasto cast types. - Looping: Implicit looping occurs when a rule's input context is a repeating element, applying the rule to each instance automatically.
04
Type Casting and Conversion Functions
FML provides built-in functions for data type coercion and string manipulation, essential for converting legacy string representations into FHIR's strict data types.
- Casting: Use
castto convert strings to integers, decimals, dates, or booleans. - String Functions:
substring,trim,append, andtranslate(for code mapping) are first-class operations. - Date Handling: Special functions like
dateTimeparse ambiguous legacy date formats into precise FHIR dateTime values.
05
Conditional Logic and Dependencies
Rules can include conditional expressions to handle variations in source data. Dependencies between rules ensure correct execution order when output elements rely on each other.
- Conditions:
ifstatements evaluate boolean expressions on source data before executing a rule's body. - Dependencies: A rule can declare
dependenton another rule, ensuring the target FHIR element exists before attempting to reference it. - Default Values: Use
defaultto provide fallback values when source data is missing or null.
06
ConceptMap Integration for Terminology
FML has first-class support for invoking ConceptMap resources to translate local or legacy codes into standardized FHIR terminology during transformation.
- translate Function: The
translatefunction accepts a code, source system, and target system, returning the mapped code and display. - Dynamic Resolution: The engine can query a FHIR Terminology Service at runtime to resolve mappings.
- Error Handling: Configurable behavior for unmapped codes, including passing through the original code or throwing an error.
FHIR MAPPING LANGUAGE
Frequently Asked Questions
Explore the mechanics of the FHIR Mapping Language, the domain-specific grammar designed by HL7 to author the deterministic transformation rules that convert legacy healthcare data formats into FHIR resources.
The FHIR Mapping Language is a domain-specific, declarative language defined by HL7 for authoring the transformation rules that convert legacy healthcare data formats into FHIR resources. It works by defining a StructureMap resource that contains a series of mapping groups, each consisting of input sources, output targets, and transformation rules. The engine processes an input structure (like an HL7 v2 message or a CDA document) against the map, executing nested rules that copy, concatenate, translate, or compute data from source fields to target FHIR elements. Unlike imperative scripting, the language focuses on what the transformation should be, not how to execute it, ensuring deterministic, repeatable data conversion. The syntax uses a concise, text-based grammar that can be authored directly or generated by graphical tools, and it supports complex operations like conditional logic, data type casting, and terminology translation via ConceptMap references.
Enabling Efficiency, Speed & Accuracy
Intelligent Analysis, Decision & Execution
We build AI systems for teams that need search across company data, workflow automation across tools, or AI features inside products and internal software.
Talk to Us
Search across company data
Give teams answers from docs, tickets, runbooks, and product data with sources and permissions.
Useful when people spend too long searching or get different answers from different systems.
Enterprise searchRAGPermissions
Read more
Automate internal workflows
Use AI to route work, draft outputs, trigger actions, and keep approvals and logs in place.
Useful when repetitive work moves across multiple tools and teams.
AI agentsWorkflow automationGovernance
Read more
Add AI to products and internal tools
Build assistants, guided actions, or decision support into the software your team or customers already use.
Useful when AI needs to be part of the product, not a separate tool.
AI integrationDecision supportModel routing
Read more
About the author
Prasad Kumkar
CEO & MD, Inference Systems
Prasad Kumkar is the CEO & MD of Inference Systems and writes about AI systems architecture, LLM infrastructure, model serving, evaluation, and production deployment. Over 5+ years, he has worked across computer vision models, L5 autonomous vehicle systems, and LLM research, with a focus on taking complex AI ideas into real-world engineering systems.
His work and writing cover AI systems, large language models, AI agents, multimodal systems, autonomous systems, inference optimization, RAG, evaluation, and production AI engineering.
LinkedIn
Limited slotsGet a Free AI Consultation
Partnered with leading AI, data, and software stack.
How We Work
Custom AI workflows for your Business
One-fit-all AI don't work for modern businesses. At Inferensys, we aim to understand your business & custom requirements; which we use to define most efficient agentic workflows, the data, and the tools for your business.
01
Review the use case
We understand the task, the users, and where AI can actually help.
Read more02
Pick the right approach
We define what needs search, automation, or product integration.
Read more03
Build the first useful version
We implement the part that proves the value first.
Read more04
Improve from there
We add the checks and visibility needed to keep it useful.
Read moreThe first call is a practical review of your use case and the right next step.
Talk to Us