Concepts
What FHIR mapping is
FHIR (Fast Healthcare Interoperability Resources, an HL7 standard) models healthcare data as resources — for example a Patient, an Observation, a Medication, or a Claim. Each resource has defined fields (elements) with types and cardinality, and many fields carry terminology bindings — they expect a coded value drawn from a specific code system rather than free text.
FHIR mapping, then, is a three-part problem: figure out which FHIR resource a row of your data represents, line up each of your columns with the right field on that resource, and make sure coded fields carry values from the right terminology — LOINC for lab observations, ICD-10 for diagnoses, SNOMED CT for clinical findings, and so on. The standard spells out the resources and their fields in detail at hl7.org/fhir.
The hard part
Why CSV → FHIR is hard
The gap between a spreadsheet and a FHIR resource is wider than it looks. Three things make it hard:
- Free-text headers. A column called
DOB, birth_dt, or Patient Birthday all mean Patient.birthDate, but no two source systems agree on the spelling. - Locale variance. Headers, date formats, and gender values differ across German, French, Italian, English, and Spanish source systems — common in multi-region healthcare data.
- Code systems. FHIR’s coded fields expect values from specific terminologies — LOINC, SNOMED CT, ICD-10, CPT, ATC, NPI — and a raw export rarely arrives validated against them.
Get any of these wrong and the resulting resource is either rejected by the receiving system or — worse, for your-money-or-your-life healthcare data — silently incorrect.
The approach
How AdaptivMapr maps to FHIR
AdaptivMapr maps your inbound columns to a template’s canonical fields, and each healthcare template carries a fhir_resource mapping so you always know which FHIR resource and path a field corresponds to. It resolves and validates the mapping layer; your pipeline serialises the FHIR-ready fields into resources.
The 5-layer cascade
Header resolution runs through five layers, cheapest first. When a layer accepts a column, the layers below it never run — and the metered LLM is the last resort, not the first move.
- 1 · Statistics — free, deterministic; auto-accepts headers seen mapped the same way before.
- 2 · Heuristic — free; compares the normalised header against the column name, label, and every multilingual hint (DE / FR / IT / EN / ES).
- 3 · Fuzzy — free, pure compute; tolerates typos and reordered tokens.
- 4 · Semantic — cheap, cached embeddings for the long tail of paraphrases.
- 5 · LLM — metered; fires only on genuinely ambiguous columns, constrained to the template’s allowed field set so it cannot invent a field.
Validators & HITL gating
Healthcare templates attach field-level validators — LOINC, SNOMED, ICD-10, CPT, ATC, NPI, GTIN, IBAN and more — that run on every committed row. Each template also carries a risk level. Medium- and high-risk templates — patient_demographics, lab_results, claims_line_items, and drug_formulary — return requires_hitl: true with hitl_status: "pending_review" so you can gate your own commit workflow with a human review step.
On data handling: schema-only mapping is free and unlimited — only headers and up to three sample rows (≤80 characters each) leave your environment, with no DPA. Full-data mapping requires a PHI subscription, where the layer-5 LLM call is routed through phi-cloud with X-PHI and X-Region headers to force a PHI-eligible, in-region model. A BAA is available; AdaptivMapr is HIPAA-aware.
Worked examples
Three columns, mapped
Each example links to the live template page, where you can see the full canonical schema, validators, and FHIR resource mapping.
Geburtsdatum→date_of_birthFHIR · Patient.birthDate
Layer 2 · Heuristic
The German header matches a registered hint after the normalising pass, so the column resolves for free — no LLM call. The date_range validator (1900-01-01 to today) fires on commit.
Patient demographics template →code loinc→loinc_codeFHIR · Observation.code
Layer 2 · Heuristic
The French label resolves against the loinc hint, and the loinc_code validator checks the value against LOINC’s code format on commit.
Lab result catalog template →Diagnose (ICD)→icd10_codeFHIR · Claim.item
Layer 3 · Fuzzy
A messy header with extra tokens still resolves via the fuzzy layer. Because this template is risk medium, the mapping is returned with requires_hitl:true so your team can gate the commit.
Claims line items template →Get started
Map your first file
Schema-only mapping is free and needs no DPA — start there. The documentation covers the API, the MCP server, and the template catalogue.
Questions
FHIR mapping FAQ
Does AdaptivMapr output valid FHIR resources?+
AdaptivMapr maps your inbound columns to a template’s canonical fields, and each healthcare template carries a fhir_resource mapping (for example Patient, Observation, or Claim.item) so you know which FHIR resource and path each field corresponds to. AdaptivMapr resolves and validates the mapping layer — it does not, on its own, emit a fully conformance-checked FHIR bundle. The output is a clean, validated, FHIR-ready field set that your downstream pipeline serialises into resources.
What code systems are supported?+
Healthcare templates ship field-level validators for the common clinical and administrative code systems, including LOINC (lab observations), ICD-10 (diagnoses), CPT (procedures), ATC and GTIN (drugs), NPI and GLN (providers), and IBAN (payment). SNOMED CT bindings are described where a template references them. Validators run on every committed row and surface failures in the per-row validation report.
Is patient data sent to the cloud?+
Not in schema-only mode, which is free and unlimited: only your headers and up to three sample rows (each clamped to 80 characters) ever leave your environment, and no DPA is required. Full-data mapping requires a PHI subscription; the layer-5 LLM call is then routed through phi-cloud with X-PHI and X-Region headers so a PHI-eligible, in-region model is used. A BAA is available for full-data use.
How does AdaptivMapr handle multilingual and free-text headers?+
Templates carry multilingual hints in German, French, Italian, English, and Spanish. A normalising pass strips accents, punctuation, and whitespace before the heuristic, fuzzy, and semantic layers compare your header against the canonical column name, label, and every hint. Most real-world headers resolve in those free, deterministic or cheap layers before the metered LLM is ever called.