FHIR to OMOP: How to Convert Clinical Data for Research
FHIR to OMOP conversion takes clinical data exchanged in HL7 FHIR resources and transforms it into the tables and standard vocabularies of the OMOP Common Data Model so it can be analyzed for research. The work has three parts: mapping each FHIR resource to the right OMOP table, translating local and source codes into OMOP standard concepts, and validating the result with data quality checks before researchers use it.
Why FHIR to OMOP conversion matters now
Health systems have spent the past decade exposing data through FHIR APIs. Fast Healthcare Interoperability Resources (FHIR) is built for exchange: moving one patient’s record between applications in real time. Research needs something different. It needs the same question asked consistently across millions of records and across many institutions, which is what the Observational Medical Outcomes Partnership (OMOP) Common Data Model was designed for.
The two standards are complementary, not competing. FHIR is often the easiest way to get data out of an electronic health record. OMOP is the best-supported way to analyze it at scale, with a large open-source toolset from the OHDSI community. Converting FHIR to OMOP lets an organization reuse the integration work it has already done for care and turn it into a research asset.
Regulation is pushing in the same direction. The European Health Data Space (EHDS) regulation sets up secondary use of health data across member states, and national programs increasingly expect data to arrive in a common research model. For a deeper grounding in the target model, see our guide to the OMOP CDM.
How FHIR resources map to OMOP tables
The first design task is structural. FHIR organizes data into resources; OMOP organizes it into person-centered tables organized by clinical domain. Most mappings follow a predictable pattern.
| FHIR R4 resource | Main OMOP CDM v5.4 table | Notes |
|---|---|---|
| Patient | PERSON | Birth date, sex and ethnicity; identifiers move to a separate linkage step |
| Encounter | VISIT_OCCURRENCE | Encounter class maps to visit concept (inpatient, outpatient, emergency) |
| Condition | CONDITION_OCCURRENCE | Codes may land in another domain after vocabulary mapping |
| MedicationRequest, MedicationStatement, MedicationAdministration | DRUG_EXPOSURE | Choose drug type concept to record which source it came from |
| Observation (laboratory, vital signs) | MEASUREMENT | Numeric values, units and reference ranges |
| Observation (social history, survey) | OBSERVATION | Facts without a standard numeric result |
| Procedure | PROCEDURE_OCCURRENCE | Often coded in CPT, SNOMED CT or local systems |
| Immunization | DRUG_EXPOSURE | Vaccines are treated as drugs in OMOP |
The table is a starting point, not a rule. In OMOP the domain of the standard concept decides the destination table. A FHIR Condition coded with a term that maps to a procedure concept belongs in PROCEDURE_OCCURRENCE, not CONDITION_OCCURRENCE. Conversion logic must therefore route records after vocabulary mapping, not before.
The vocabulary step is where most effort goes
Structural mapping is usually the quick part. Translating codes is where projects spend most of their time.
Standard codes
Where FHIR resources carry standard terminologies such as SNOMED CT, LOINC, RxNorm or ICD-10, the OHDSI standardized vocabularies already contain the relationships needed to reach a standard concept. These are loaded from the OHDSI Athena service and applied with lookups on the concept and concept relationship tables.
Local codes
Many FHIR feeds still carry local codes, free text or vendor-specific value sets. These need manual or assisted mapping. The OHDSI Usagi tool suggests candidate concepts based on text similarity, and a clinical reviewer confirms each one. AI-assisted mapping can shorten this considerably, but every suggestion should still be reviewed and recorded.
Units and values
Laboratory results need unit normalization as well as code mapping. A glucose value in mmol/L and one in mg/dL must both be recorded with the correct unit concept, or analyses across sites will silently mix scales.
Vocabulary mapping is the core of data harmonization. Keep mapping tables under version control so that every analysis can state which mapping release it used.
A step-by-step FHIR to OMOP conversion pipeline
- Profile the source. Extract a representative sample of FHIR bundles and list the resources, profiles and code systems actually present. Tools such as OHDSI WhiteRabbit help summarize source content.
- Design the mapping. Document resource-to-table and field-to-column rules. The HL7 FHIR to OMOP implementation guide, developed through the Vulcan accelerator, offers a shared reference for common patterns.
- Map vocabularies. Apply standard relationships for known code systems, then review and record local code mappings.
- Transform and load. Run the extract, transform and load (ETL) process into a fresh OMOP schema, keeping source values and source concept IDs alongside standard ones.
- Validate. Run the OHDSI Data Quality Dashboard and Achilles characterization to check conformance, completeness and plausibility.
- Release. Publish the converted data as a versioned release that researchers can cite.
- Repeat incrementally. Schedule refreshes, ideally with incremental loads from FHIR bulk data export rather than full rebuilds.
Common pitfalls in FHIR to OMOP conversion
- Duplicate events. The same medication can appear as a request, a dispense and an administration. Decide which to keep, or record all with distinct type concepts.
- Missing visit context. Resources without an Encounter reference need a rule for assigning or creating a visit.
- Date ambiguity. FHIR allows partial dates and periods. Agree how to set start and end dates when only a year or month is known.
- Profile drift. Different FHIR servers implement different profiles. A mapping built on one site’s data often needs adjustment for the next.
- Losing source detail. Always keep the original code and value in the source columns so that mappings can be audited and improved later.
Handling identifiers and privacy during conversion
FHIR resources often carry direct identifiers: names, addresses, medical record numbers and contact details. OMOP does not need them. The PERSON table holds a pseudonymous person ID, and location data can be generalized to a region. Strip or tokenize direct identifiers as the first transformation, before any data reaches the OMOP schema, and keep the linkage key in a separate, tightly controlled store. If records from several sources must be linked, use privacy-preserving record linkage so that raw identifiers are never pooled. Free-text fields such as clinical notes deserve particular care, because they can contain names and dates even when structured fields are clean.
Testing a conversion before researchers use it
Validation tools catch structural problems, but they cannot tell you whether a research answer is right. Before release, rebuild a small number of well-understood cohorts in the converted data, for example patients with a recorded diagnosis of type 2 diabetes and a prescription for metformin, and compare the counts and timelines with the same query run against the source system. Large gaps usually point to a missing code mapping or a routing rule that sent records to the wrong table. Record these test cohorts and rerun them with every new release so that regressions are caught early.
Where to run the conversion: centralized or federated
Once data is in OMOP, the next question is where analysis happens. Many projects convert data at each hospital and then copy it to a central warehouse. That creates new copies of sensitive records and new governance obligations.
| Dimension | Convert and centralize | Convert and federate |
|---|---|---|
| Data location | Copied to a central store | Stays at each institution |
| Governance | Data sharing agreements for every transfer | Access approvals; data never leaves the source |
| Multi-site queries | Run on pooled data | Same OMOP query runs at every site, results combined |
| Refresh | Re-transfer for every update | Each site refreshes locally |
| Output control | Depends on the central host | Automated airlock at every site |
Because OMOP gives every site the same structure, it is an ideal basis for federated analysis. A Trusted Research Environment at each data custodian can host the converted data, run approved queries locally and return only checked, aggregate results. The pattern is described in more detail in our guide to the federated data platform.
Practical next steps
Start small and measurable. Pick one research question, list the FHIR resources it depends on, and convert only those first. Measure mapping coverage, meaning the share of source records that reach a standard concept, and track it as you expand. Agree a release cadence with your research users, and decide early whether converted data will be pooled or analyzed where it sits. That decision shapes governance, cost and how quickly new sites can join.
Frequently asked questions
What is FHIR to OMOP conversion?
It is the process of transforming clinical data from HL7 FHIR resources into the OMOP Common Data Model, including table mapping, vocabulary translation to standard concepts and data quality validation.
Is FHIR or OMOP better for research?
They serve different purposes. FHIR is designed for exchanging individual records; OMOP is designed for consistent analysis across large populations. Most research programs use FHIR as a source and OMOP as the analysis model.
Which tools help with FHIR to OMOP conversion?
Common tools include OHDSI WhiteRabbit for profiling, Usagi for vocabulary mapping, Athena for vocabularies, and the Data Quality Dashboard and Achilles for validation. The HL7 FHIR to OMOP implementation guide provides reference mappings.
How long does a conversion project take?
It depends mostly on how many local codes need manual mapping. Sources that already use standard terminologies convert far faster than those with local or free-text codes.
Do I need to move data to convert it?
No. Conversion can run inside each institution, and federated analysis can then query the converted data where it sits.
How do I check conversion quality?
Run the OHDSI Data Quality Dashboard for conformance, completeness and plausibility checks, review mapping coverage, and compare key counts against the source system.