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

Technical Artifacts

Page standards status: Trial-use

Highlight text changes?

Logical Models

This guide contains a set of logical models that describe the OMOP CDM. By expressing the CDM tables as FHIR Logical models, we are able to express the mappings between the tables and FHIR resources using FHIR StructureMaps.

Besides the CDM table logical models, we have also defined a RecordSet model that allows us to create a large set of OMOP records from one transformation. This is used in the FHIR Bundle to OMOP transformation as well as in the Blood Pressure Vital Signs transformation where one FHIR Observation results in multiple OMOP Measurement records.

CareSite OMOP Table	The CARE_SITE table contains a list of uniquely identified institutional (physical or organizational) units where healthcare delivery is practiced (offices, wards, hospitals, clinics, etc.).
Condition Era OMOP Table	A Condition Era is defined as a span of time when the Person is assumed to have a given condition. Similar to Drug Eras, Condition Eras are chronological periods of Condition Occurrence. Combining individual Condition Occurrences into a single Condition Era serves two purposes: It allows aggregation of chronic conditions that require frequent ongoing care, instead of treating each Condition Occurrence as an independent event. It allows aggregation of multiple, closely timed doctor visits for the same Condition to avoid double-counting the Condition Occurrences. For example, consider a Person who visits her Primary Care Physician (PCP) and who is referred to a specialist. At a later time, the Person visits the specialist, who confirms the PCP's original diagnosis and provides the appropriate treatment to resolve the condition. These two independent doctor visits should be aggregated into one Condition Era.
Condition Occurrence OMOP Table	This table contains records of Events of a Person suggesting the presence of a disease or medical condition stated as a diagnosis, a sign, or a symptom, which is either observed by a Provider or reported by the patient.
Cost OMOP Table	The COST table captures records containing the cost of any medical event recorded in one of the OMOP clinical event tables such as DRUG_EXPOSURE, PROCEDURE_OCCURRENCE, VISIT_OCCURRENCE, VISIT_DETAIL, DEVICE_OCCURRENCE, OBSERVATION or MEASUREMENT. Each record in the cost table account for the amount of money transacted for the clinical event. So, the COST table may be used to represent both receivables (charges) and payments (paid), each transaction type represented by its COST_CONCEPT_ID. The COST_TYPE_CONCEPT_ID field will use concepts in the Standardized Vocabularies to designate the source (provenance) of the cost data. A reference to the health plan information in the PAYER_PLAN_PERIOD table is stored in the record for information used for the adjudication system to determine the persons benefit for the clinical event.
Death OMOP Table	The death domain contains the clinical event for how and when a Person dies. A person can have up to one record if the source system contains evidence about the Death, such as: Condition in an administrative claim, status of enrollment into a health plan, or explicit record in EHR data.
Device Exposure OMOP Table	The Device domain captures information about a person's exposure to a foreign physical object or instrument which is used for diagnostic or therapeutic purposes through a mechanism beyond chemical action. Devices include implantable objects (e.g. pacemakers, stents, artificial joints), medical equipment and supplies (e.g. bandages, crutches, syringes), other instruments used in medical procedures (e.g. sutures, defibrillators) and material used in clinical care (e.g. adhesives, body material, dental material, surgical material).).
Dose Era OMOP Table	A Dose Era is defined as a span of time when the Person is assumed to be exposed to a constant dose of a specific active ingredient.
Drug Era OMOP Table	A Drug Era is defined as a span of time when the Person is assumed to be exposed to a particular active ingredient. A Drug Era is not the same as a Drug Exposure: Exposures are individual records corresponding to the source when Drug was delivered to the Person, while successive periods of Drug Exposures are combined under certain rules to produce continuous Drug Eras.
Drug Exposure OMOP Table	This table captures records about the exposure to a Drug ingested or otherwise introduced into the body. A Drug is a biochemical substance formulated in such a way that when administered to a Person it will exert a certain biochemical effect on the metabolism. Drugs include prescription and over-the-counter medicines, vaccines, and large-molecule biologic therapies. Radiological devices ingested or applied locally do not count as Drugs.
Episode Event OMOP Table	The EPISODE_EVENT table connects qualifying clinical events (such as CONDITION_OCCURRENCE, DRUG_EXPOSURE, PROCEDURE_OCCURRENCE, MEASUREMENT) to the appropriate EPISODE entry. For example, linking the precise location of the metastasis (cancer modifier in MEASUREMENT) to the disease episode.
Episode OMOP Table	The EPISODE table aggregates lower-level clinical events (VISIT_OCCURRENCE, DRUG_EXPOSURE, PROCEDURE_OCCURRENCE, DEVICE_EXPOSURE) into a higher-level abstraction representing clinically and analytically relevant disease phases,outcomes and treatments. The EPISODE_EVENT table connects qualifying clinical events (VISIT_OCCURRENCE, DRUG_EXPOSURE, PROCEDURE_OCCURRENCE, DEVICE_EXPOSURE) to the appropriate EPISODE entry. For example cancers including their development over time, their treatment, and final resolution.
Fact Relationship OMOP Table	The FACT_RELATIONSHIP table contains records about the relationships between facts stored as records in any table of the CDM. Relationships can be defined between facts from the same domain, or different domains. Examples of Fact Relationships include: Person relationships (parent-child), care site relationships (hierarchical organizational structure of facilities within a health system), indication relationship (between drug exposures and associated conditions), usage relationships (of devices during the course of an associated procedure), or facts derived from one another (measurements derived from an associated specimen).
Location OMOP Table	The LOCATION table represents a generic way to capture physical location or address information of Persons and Care Sites.
Measurement OMOP Table	The MEASUREMENT table contains records of Measurements, i.e. structured values (numerical or categorical) obtained through systematic and standardized examination or testing of a Person or Person's sample. The MEASUREMENT table contains both orders and results of such Measurements as laboratory tests, vital signs, quantitative findings from pathology reports, etc. Measurements are stored as attribute value pairs, with the attribute as the Measurement Concept and the value representing the result. The value can be a Concept (stored in VALUE_AS_CONCEPT), or a numerical value (VALUE_AS_NUMBER) with a Unit (UNIT_CONCEPT_ID). The Procedure for obtaining the sample is housed in the PROCEDURE_OCCURRENCE table, though it is unnecessary to create a PROCEDURE_OCCURRENCE record for each measurement if one does not exist in the source data. Measurements differ from Observations in that they require a standardized test or some other activity to generate a quantitative or qualitative result. If there is no result, it is assumed that the lab test was conducted but the result was not captured.
Note NLP OMOP Table	The NOTE_NLP table encodes all output of NLP on clinical notes. Each row represents a single extracted term from a note.
Note OMOP Table	The NOTE table captures unstructured information that was recorded by a provider about a patient in free text (in ASCII, or preferably in UTF8 format) notes on a given date. The type of note_text is CLOB or varchar(MAX) depending on RDBMS.
Observation OMOP Table	The OBSERVATION table captures clinical facts about a Person obtained in the context of examination, questioning or a procedure. Any data that cannot be represented by any other domains, such as social and lifestyle facts, medical history, family history, etc. are recorded here.
Observation Period OMOP Table	This table contains records which define spans of time during which two conditions are expected to hold: (i) Clinical Events that happened to the Person are recorded in the Event tables, and (ii) absense of records indicate such Events did not occur during this span of time.
Payer Plan Period OMOP Table	The PAYER_PLAN_PERIOD table captures details of the period of time that a Person is continuously enrolled under a specific health Plan benefit structure from a given Payer. Each Person receiving healthcare is typically covered by a health benefit plan, which pays for (fully or partially), or directly provides, the care. These benefit plans are provided by payers, such as health insurances or state or government agencies. In each plan the details of the health benefits are defined for the Person or her family, and the health benefit Plan might change over time typically with increasing utilization (reaching certain cost thresholds such as deductibles), plan availability and purchasing choices of the Person. The unique combinations of Payer organizations, health benefit Plans and time periods in which they are valid for a Person are recorded in this table. }
Person OMOP Table	This table serves as the central identity management for all Persons in the database. It contains records that uniquely identify each person or patient, and some demographic information.
Procedure Occurrence OMOP Table	This table contains records of activities or processes ordered by, or carried out by, a healthcare provider on the patient with a diagnostic or therapeutic purpose. }
Provider OMOP Table	The PROVIDER table contains a list of uniquely identified healthcare providers. These are individuals providing hands-on healthcare to patients, such as physicians, nurses, midwives, physical therapists etc.
Specimen OMOP Table	The specimen domain contains the records identifying biological samples from a person.
Visit Detail OMOP Table	The VISIT_DETAIL table is an optional table used to represents details of each record in the parent VISIT_OCCURRENCE table. A good example of this would be the movement between units in a hospital during an inpatient stay or claim lines associated with a one insurance claim. For every record in the VISIT_OCCURRENCE table there may be 0 or more records in the VISIT_DETAIL table with a 1:n relationship where n may be 0. The VISIT_DETAIL table is structurally very similar to VISIT_OCCURRENCE table and belongs to the visit domain.
Visit Occurrence OMOP Table	This table contains Events where Persons engage with the healthcare system for a duration of time. They are often also called "Encounters". Visits are defined by a configuration of circumstances under which they occur, such as (i) whether the patient comes to a healthcare institution, the other way around, or the interaction is remote, (ii) whether and what kind of trained medical staff is delivering the service during the Visit, and (iii) whether the Visit is transient or for a longer period involving a stay in bed.

Structure Maps

The mappings are represented via FHIR StructureMaps and those StructureMaps are presented using the FHIR Mapping Language. There do not exist mappings for all FHIR resources to all OMOP tables, but rather a select few. The mappings were chosen from the resources that were profiled by the International Patient Access IG along with Encounter and Procedure which were deemed to be important to map. For each mapping, there are considerations listed along with the mapping itself.

• Allergy Mapping
• Condition Mapping
• Encounter/Visit Mapping
• Immunization Mapping
• Medication Statement Mapping
• Observation Mappings
  • Observation to Measurement Mapping
  • Simple Vital Signs to Measurement Mapping
  • Blood Pressure to Measurement Mapping
  • Observation to Observation Mapping
• Person Mapping
• Procedure Mapping
• Bundle Mapping

Example Concept Maps

There are a number of example concept maps that are included here to facilitate testing of the StructureMaps. The StructureMaps currently reference these example concept maps but they are intentionally sparse and only include a few codes used for testing.

• Allergy Category Codes
• Intolerance Category Codes
• Allergy Substance Codes
• Blood Pressure Codes
• Clinical Findings Codes
• Condition Status Codes
• Encounter Admission Source Codes
• Encounter Class Codes
• Encounter Discharge Disposition Codes
• Immunization Information Source Codes
• Immunization Route Codes
• Immunization Vaccine Codes
• Vital Sign Codes

Mappings Not Published by This Guide

The StructureMaps above express how FHIR elements populate OMOP fields. They do not express how individual codes translate into OMOP concepts, and this guide does not publish official ConceptMap artifacts for that purpose. The omission is deliberate. Code-to-concept translation is the province of the OHDSI Standardized Vocabularies, which are versioned, maintained by the OHDSI community, and updated on a cadence no Implementation Guide can usefully track. A ConceptMap published here would be a snapshot of those vocabularies at the moment of balloting, and would begin diverging from them immediately.

A more specialized guide built on this one might reasonably publish ConceptMaps: a guide scoped to a particular use case, a particular set of source systems, or a particular national realm can fix the code sets in play tightly enough for a published map to remain useful. This guide is foundational and does not have that luxury.

The practical consequence for an implementer is that concept translation resolves against the OHDSI Vocabularies rather than against an artifact shipped with this guide, whether through a terminology server or a locally loaded vocabulary, as described under Coded Field Mapping Principles. Where a transformation instead uses a fixed set of mappings prepared in advance, that set ought to be identified along with the vocabulary release it was derived from, so that a consumer of the resulting data can tell which vocabulary the concept assignments reflect.

Deviating from the Published Maps

A transformation might implement the mapping logic these StructureMaps express without executing the StructureMaps themselves, and the Connectathon workflows described below exercise exactly that range: reference tooling running the published maps, and participant tooling implementing equivalent logic in its own stack. Both are conformant, and the guide takes no position on which is preferable.

What the guide does ask is that departures be visible. A transformation that implements the maps faithfully in another technology produces output a consumer can reason about from the published maps alone. One that departs from them, whether by mapping an element the map does not, by omitting one it does, or by resolving a case differently, produces output the published maps no longer describe. Recording those departures in the ETL documentation is what allows a consumer to know which of the two they are looking at.

FHIR and OMOP 2025 Connectathon Validation Package

Created to support the Vulcan July 2025 Connectathon, this Jupyter notebook provides basic syntax and specification validation of FHIR JSON and OMOP CSV data for the Vulcan FHIR->OMOP Connectathon. The notebook can be run as-is from within Google Colab (with a Google account) or downloaded and run locally. Upload your FHIR JSON or OMOP CSVs into the colab temporary directory and update the paths accordingly.

1. Validate FHIR (HL7 FHIR Validator) FHIR for FHIR->OMOP testing must be valid FHIR R4 syntax for the IPA (https://hl7.org/fhir/uv/ipa/) Profile.

2. Validate OMOP (OHDSI Data Quality Dashboard - Subset) OMOP resulting from FHIR->OMOP conversion must be valid OMOP CDMv5.4. A subset of 100 OHDSI Data Quality Dashboard tests are implemented here to validate tables, columns, concepts, and a set of completeness and plausibility checks.

FHIR to OMOP 2026 Connectathon Tooling

The July 2026 Vulcan FHIR-to-OMOP Connectathon (7 to 8 July 2026) exercised three participation workflows, distinguished by whose tooling performs the transformation and how terminology is resolved: Workflow 1 used Working-Group reference tooling with a delegated terminology server; Workflow 2 used participant tooling with embedded local terminology and no outbound terminology calls; and Workflow 3 used participant tooling with a delegated, conformant terminology server of the participant's choice. All three produce OMOP CDM v5.4 CSV output from the same FHIR input, which is what allows participant output to be compared against the Workflow 1 baseline.

Workflow 1 used Working-Group reference tooling, maintained by Christopher Roeder and published at https://github.com/croeder-fhir-to-omop, which served as the gold-standard baseline against which Workflow 2 and Workflow 3 outputs were compared at the event. The tooling is a containerized pipeline in which a FHIR mapping server (matchbox) loads this Implementation Guide's StructureMaps and exposes a $transform operation for each, resolving clinical codes at runtime against a FHIR terminology server. The default configuration uses a local OMOP-backed terminology server (enchilada) seeded with OHDSI Vocabularies obtained from Athena; a hosted conformant terminology server might be substituted, and participants at the event used the Echidna public terminology service (echidna.fhir.org) in this role. The pipeline drives FHIR test fixtures through the transforms, writes the results into a DuckDB OMOP CDM v5.4 database, and runs the OHDSI Data Quality Dashboard together with a unit-test suite that asserts specific OMOP field values for each StructureMap. Published Docker images allow the stack to be run without cloning source.

The transformation operates on individual FHIR resources rather than Bundles, consistent with the resource-level mapping this guide defines. The reference tooling covers eleven StructureMaps spanning Person, Encounter, Condition, Observation, medication, immunization, and allergy content. In the medication area, MedicationStatement is mapped to drug_exposure, while MedicationRequest is treated as out of scope because it represents a prescription order, an intention, rather than a completed clinical act.

Capability Declaration

A consumer of OMOP data produced by a FHIR-to-OMOP transformation frequently needs to know, before using the data or even before running the transformation, what the transformation accepts and what it produces. Two declarations elsewhere in this guide answer parts of that question in human-readable form: an Implementer declares which input profiles the transformation accepts, whether International Patient Access, US Core, or base FHIR resources, and a conformant Target OMOP Instance discloses which OMOP tables it populates fully, populates partially, or leaves unpopulated. Read together, these tell a consumer the two endpoints of the transformation: what goes in and what comes out.

What neither declaration provides on its own is the mapping between them in a form a machine can consume. A researcher assembling a federated query across several OMOP instances, or a tool deciding whether a given transformation can supply the tables an analysis needs, benefits from a single artifact that states which input profiles produce records in which OMOP tables, and states it in a structure a program can read rather than prose a person must interpret. A capability manifest of this kind turns two separate human-readable declarations into one machine-consumable statement of what the transformation does, which is what allows capability to be reasoned about at scale rather than one engine at a time.

This guide does not yet define the format of such a manifest. Defining it properly requires a profile or logical model for the manifest itself, an example instance, and validation, so that a manifest produced by one engine can be processed the same way as a manifest produced by another. That work is a candidate for a future version of this guide. Until it exists, a manifest is useful as an engine-specific artifact but cannot yet be relied on for cross-engine interoperability, and the guidance below reflects that: publishing the manifest is recommended now as good practice and as a signal of direction, and a future version that defines the manifest format would be the point at which strengthening the recommendation could reasonably be considered.

Guidance

A Transformation Engine and Implementer SHOULD publish a machine-readable manifest declaring which input FHIR profiles the transformation supports and which OMOP tables it populates from them. This manifest makes machine-consumable, and connects, the input-profile declaration described for accepted FHIR profiles and the table-population disclosure described for the Target OMOP Instance. The format of the manifest is not defined in this version of the guide; publishing a manifest in an engine-specific format is nonetheless encouraged as a signal of capability and as preparation for a future version that defines a common format.^§f2o-003

A Target OMOP Instance SHALL conform to the logical model this guide defines for each OMOP table it populates.^§f2o-090

A Transformation Engine MAY execute the StructureMaps published by this guide, or MAY implement equivalent transformation logic in another technology.^§f2o-091

Where a transformation departs from the logic expressed by a published StructureMap, an Implementer SHALL record the departure and its rationale in the ETL documentation.^§f2o-092

A Transformation Engine SHALL resolve code-to-concept translation against the OHDSI Standardized Vocabularies. Where a fixed set of mappings prepared in advance is used instead of resolving against the vocabularies at transformation time, an Implementer SHALL identify that set and the vocabulary release from which it was derived.^§f2o-093

A Transformation Engine SHALL pass the reference test suite published by this guide for the transformations it claims to support. The suite is versioned independently of this guide, and a conformance claim identifies the suite version against which it was established.^§f2o-120

An Implementer SHOULD publish the results of the reference test suite, identifying the version of this Implementation Guide and the OHDSI Vocabulary release under which the run was performed.^§f2o-121

A Target OMOP Instance SHALL disclose which OMOP tables it populates fully, which it populates partially, and which it leaves unpopulated.^§f2o-122

Technical Considerations

The following tables provide some technical information about the guide.

Cross-Version Analysis

Intellectual Property Statements

No use of external IP

Global Profiles

There are no Global profiles defined

IG Dependencies

This IG Contains the following dependencies on other IGs.

Package hl7.fhir.uv.extensions.r5#5.3.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Sat, May 16, 2026 18:32+1000+10:00)

Package hl7.fhir.uv.tools.r5#1.1.2 This IG defines the extensions that the tools use internally. Some of these extensions are content that are being evaluated for elevation into the main spec, and others are tooling concerns (built Tue, Mar 24, 2026 11:13+1100+11:00)