FHIR to OMOP FHIR IG, published by HL7 International / Biomedical Research and Regulation. This guide is not an authorized publication; it is the continuous build for version 2.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-omop-ig/ and changes regularly. See the Directory of published versions

Transformation Strategies & Best Practices

The successful implementation of FHIR-to-OMOP transformations requires careful balance between OMOP's clinical data model philosophy and the comprehensive data business and provenance needs of modern healthcare organizations. By understanding where these approaches differ, implementers can design robust, scalable solutions that serve both clinical research and operational stakeholders effectively.

ETL Documentation

FHIR-to-OMOP implementations benefit from comprehensive ETL documentation that specifies mapping choices and clearly articulates assumptions made during the transformation process. This documentation is a critical feature of implementations that scale over time, particularly when dealing with multiple source systems that might handle temporal data differently or have varying levels of data completeness. In any OMOP instance that is populated with a feed that has undergone a FHIR to OMOP transformation, the differences in purpose and structure of the underlying FHIR sources and the OMOP CDM dictate transformation choices that might need to be made to best serve the purpose of that specific OMOP instance. Aspects of ETL design rationale that ought to be documented include:

 * The limitations of certain mappings (e.g., MedicationRequest to drug_exposure).
 * Assumptions made during mapping (e.g., inferred exposure based on prescription data).
 * Guidance on when to filter data (e.g., removing planned procedures).

This guide leverages common EHR transformation scenarios and includes detailed examples as a foundation to help users develop navigate edge cases and develop implementation-specific strategies for effective and consistent ETL from FHIR to OMOP, especially where FHIR resources might vary by source. For organizations where audit requirements mandate robust provenance tracking, designing custom OMOP extensions for identifer management or recorded date preservation et al represents a strategic investment in long-term data usability. These extensions ought to be carefully planned to avoid conflicts with standard OMOP conventions while providing the necessary metadata for compliance and quality assurance processes.

Source Value Preservation

Consistently preserving source values is a critical component of FHIR to OMOP transformation, ensuring data lineage, maintenance of incremental data stores, supports future remapping efforts, and enabling quality assurance validation procedures. This strategy accomodates vocabulary evolution and improved mapping algorithms which might require reprocessing of source data, making original value retention essential for long-term data management.

Source value fields must always preserve original codes exactly as provided in FHIR resources, maintaining character-for-character accuracy to ensure complete traceability back to the source system. This includes maintaining any formatting, spacing, or special characters present in the original codes, as these might carry semantic meaning or system-specific significance that could be relevant for future processing or validation efforts. Source identifier fields are populated with OMOP concept_id values when source codes exist within the OHDSI Standardized Vocabularies. Where a source code has no Standard OMOP concept, the *_concept_id field is populated with 0; this convention, and the preservation of the original code in the source-value fields, is described in Coded Field Mapping.

Future-proofing an OMOP database includes designing storage and documentation strategies that accommodate vocabulary evolution, improved mapping methodologies, and changing clinical terminology standards. A corollary best practice to source data preservation is completion of transformation lineage documentation, including mapping decisions, prioritization choices, and any pre-processing or manual interventions performed during the transformation process. Together, these two steps enable future data validation efforts, support quality improvement initiatives, and provides the foundation for remapping activities when vocabulary updates or improved algorithms become available.

Incremental Loads and Re-runs

An OMOP instance built from FHIR is populated over time rather than once. Loads recur as new data become available, and individual loads are re-run after failures, after transformation defects are corrected, and after vocabulary updates warrant remapping. How a transformation behaves when the same source content is processed twice is therefore an operational property of consequence, not an edge case.

A transformation is idempotent with respect to a source snapshot when processing that snapshot twice leaves the target in the same state as processing it once. Without this property, a re-run duplicates clinical events: the same prescription appears twice in drug_exposure, the same diagnosis twice in condition_occurrence. Duplication of this kind is difficult to detect after the fact, because the duplicated records are individually valid and differ only in surrogate key. It inflates event counts, distorts incidence and prevalence calculations, and can survive undetected into published analyses.

Achieving idempotency requires that the transformation be able to recognize source content it has already processed. The natural basis for this is the source resource identity retained under Source Value Preservation together with the external mapping table described in Identifier Management, which together allow a target record to be traced to the FHIR resource that produced it. Implementations typically use this linkage in one of two ways: by checking for an existing target record before insertion, or by deleting and reloading the records attributable to a given source scope before processing it. The second is often simpler to reason about and is well suited to load units with clear boundaries, such as a Bulk Data export or a per-patient extraction.

Idempotency interacts with incremental loading in a way worth stating explicitly. A source system might reissue a resource with corrected content under the same identity, in which case the desired behavior is replacement rather than either duplication or silent skipping. A transformation that recognizes previously processed resources only by identity, and skips them, will fail to pick up corrections. Recognition ought to therefore consider resource version or last-updated information where the source provides it.

Where full idempotency is impractical, the transformation ought to at minimum be able to report what a re-run would affect, so that operators can assess the consequences before executing one. The run-level reporting described under Status and Intent Elements in FHIR Resources is a natural place for this information.

Guidance

A Transformation Engine SHOULD support idempotent re-processing of a given source snapshot, such that re-running a load does not duplicate clinical event records in the target.^§f2o-103

Granularity of FHIR Data vs. OMOP Standardization

FHIR resources can contain detailed data, such as drug dosage adjustments or specific intervals for medication administration, which might not have direct counterparts in OMOP’s more generalized tables. An implication for data transformation is that this disparity means some FHIR data might be lost or generalized in the transformation process to OMOP. This loss could impact certain use cases. When developing a data transformation from FHIR to OMOP, there is a need to identify and document potential data losses resulting from a mismatch in source to target data granularity to inform data users about impacts to, and potential limitations this might cause in analyses.

Run Metadata and Reproducibility

An OMOP instance is interpreted by people who did not build it, often years after it was populated, and frequently after the transformation that produced it has changed. A concept assignment that looked wrong might have been correct under the vocabulary release in force at the time. A record missing from the target might have been filtered by a rule since revised. Neither question can be settled without knowing what produced the data, and neither is answerable from the clinical records themselves.

Recording the conditions of each load addresses this. At minimum a run is identified by the OMOP CDM version it targets, the OHDSI Vocabulary release used to resolve concepts, the version of this Implementation Guide the transformation claims to follow, the version of the transformation software itself, and the time the run executed. These five together let a later reader reconstruct the context in which any given record was written. A Transformation Engine SHALL record the OHDSI Vocabulary release used to resolve concepts for each ETL run, as part of the run metadata.^§f2o-040

The vocabulary release deserves particular attention because it changes most often and affects the data most directly. Concepts are deprecated between releases, Maps to relationships are retargeted, and domain assignments are corrected, so two runs of identical source data under different vocabulary releases can legitimately produce different concept assignments. A target that does not record which release it used offers no way to distinguish that legitimate difference from a defect. Where a transformation caches terminology results, the release recorded for the run ought to be the release the cache is bound to, as described under Caching and Vocabulary Version Binding on the Terminology Server page.

Where this metadata is stored is a local decision. The OMOP CDM's cdm_source table accommodates several of these values, and implementations commonly extend it or maintain a parallel run log. What matters is that the values are recorded per run rather than per instance, since an instance populated incrementally over years will have been built under several different combinations.

Differentiating Between Patient-Reported and Clinician-Verified Data

FHIR resources such as MedicationStatement often contain patient-reported information, which might be less reliable than data verified or documented by clinicians. In contrast, OMOP’s data model does not consistently distinguish between data sources in a way that clearly conveys differences in reliability or verification status. Treating all records as equivalent can introduce interpretive challenges and potential bias, especially when patient-reported and clinician-verified records are analyzed together.

For example, a medication history reported directly by a patient might not carry the same evidentiary weight as a medication order formally documented by a prescribing clinician. To address this limitation, the Implementation Guide recommends using OMOP's type concepts to indicate the provenance of each record. Type concepts are a specialized class of concept in the OMOP CDM, stored in fields whose names end in _type_concept_id (for example, observation_type_concept_id and drug_type_concept_id), that record the origin or source-system context of a clinical fact: for instance, whether a medication record came from an EHR prescription, a pharmacy claim, or a patient self-report. They are populated alongside, and are distinct from, the Standard concept that describes what the clinical fact is. A full treatment of type concepts, including the mapping pattern, the populated field names across OMOP domains, and worked FHIR examples, is provided in Type Concepts in the OMOP Common Data Model on the Coded Field Mapping Principles page. By explicitly tagging records with their source, implementers can support analyses that require higher confidence in data accuracy or that need to filter data based on verification status. This practice improves transparency and helps maintain analytic rigor in research contexts where the reliability of the underlying data is critical.

Guidance

An Implementer SHALL document the points at which the transformation loses information because FHIR granularity exceeds what the OMOP CDM can represent, and SHALL make that documentation available to consumers of the resulting OMOP data.^§f2o-080

Where a FHIR element carries clinically meaningful content that has no representable target in the OMOP domain tables, a Transformation Engine SHOULD emit the residual content to the observation or note domain with a type concept identifying its origin, rather than discarding it silently.^§f2o-081

An Implementer SHALL produce and maintain ETL documentation recording mapping decisions, prioritization choices, pre-processing and manual interventions performed, and the known limitations of the transformation.^§f2o-082

An Implementer SHOULD maintain a traceability path from each clinical record in the Target OMOP Instance back to the FHIR resource that produced it.^§f2o-100

A Transformation Engine SHALL record, for each ETL run, the OMOP CDM version targeted, the OHDSI Vocabulary release used, the version of this Implementation Guide followed, the version of the transformation software, and the time of execution.^§f2o-102